randolf::rlabel Struct Reference

Internal structure that rhostname uses to store rlabel portions, of which at least one comprises a hostname. More...

Collaboration diagram for randolf::rlabel:

Public Types
enum	HOSTNAME_FLAGS : int {   HOSTNAME_DEFAULT = 0 ,   HOSTNAME_IP_ADDR = 1 ,   HOSTNAME_FROM_PATH = 2 ,   HOSTNAME_WITHOUT_EXCEPTIONS = 4 ,   HOSTNAME_FQDN_OPT = 8 ,   HOSTNAME_DNS_RR = 16 ,   HOSTNAME_UTF8 = 32 ,   HOSTNAME_XN = 64 }
	Optional flags that alter, modify, or enhance the operation of hostname handling. More...

Public Member Functions
	rlabel (const std::string data, const int flags=HOSTNAME_DEFAULT)
	Structure constructor that detects whether any UTF-8 sequence is present in the data and/or if it's already in punycode format (e.g., it begins with the "xn--" sequence). More...
std::string	get (const int flags=HOSTNAME_DEFAULT)
	Provice label as an std::string with any needed conversions. More...
bool	operator< (const rlabel &rhl) const
	Built-in comparison operator used by std::set for ordering rlabel objects by the underlying label data. More...

Public Attributes
std::string	data
	Label data. More...
bool	dns_rr = false
int	idn2rc = IDN2_OK
bool	utf8 = false
bool	xn = false

Detailed Description

Internal structure that rhostname uses to store rlabel portions, of which at least one comprises a hostname.

Note

See the UTF-8 Everywhere web site for simple, straight-forward, and helpful insights and advice on how to properly work with UTF8 data in C++ (and other languages) at: https://www.utf8everywhere.org/

See also

rhostname

Member Enumeration Documentation

HOSTNAME_FLAGS

enum randolf::rlabel::HOSTNAME_FLAGS : int

Optional flags that alter, modify, or enhance the operation of hostname handling.

Enumerator
HOSTNAME_DEFAULT	The HOSTNAME_DEFAULT flag isn't necessary, but it's included here for completeness as it accomodates programming styles that prefer to emphasize when defaults are being relied upon.
HOSTNAME_IP_ADDR	Alternate between an IP address and its IN-ADDR.ARPA formatted counter-part. This causes an IP address's octets (IPv4 format) or segments (IPv6 format), when supplied where a hostname would normally be expected, to be effectively reveresed. Or, deconvert for output an effectively-reversed IP-address-as-a-hostname in the appropriate IPv4/IPv6 format. (All remaining labels will be removed.) Note This format is commonly used to query DNS-based blocklists/blacklists, greylists, whitelists, etc.
HOSTNAME_FROM_PATH	Convert path to hostname. This converts a path, delimited by slashes (as is standard in UNIX, Linux, etc., as well as with internet URIs), to a hostname with the top-level portion corresponding to the top-level label as used in the Domain Name System, the second-level portion with the second-level label, etc. For example: The path "/internet/com/example/www/" gets converted into the DNS hostname "www.example.com.internet" (to remove the top/last label, use the remove(-1) method after conversion, or use the path_to_hostname method which provides an additional parameter to specify how many elements of the path to skip from both the beginning and the end).
HOSTNAME_WITHOUT_EXCEPTIONS	Don't throw exceptions when parsing a hostname string when the format is invalid (or the data is corrupt). When an index parameter is out of range, automatically truncate it to the maximum bounds of any underlying vector instead of throwing an exception when an index is out of range. This is useful for evaluating a hostname from a data source that is intended to be reported on in a diagnostic fashion, or as part of a debugging effort.
HOSTNAME_FQDN_OPT	If hostname is an FQDN, then include the final period at the end (used by the rhostname method, primarily). (The "OPT" portion of this flag name means "optional.")
HOSTNAME_DNS_RR	Convert label from/to DNS RR format (this is mostly only useful for authors of DNS client or server software, or raw DNS packet analysis code). This format is used in DNS packets, and so this flag could be useful in software projects like DNS resolvers, DNS daemons, and DNS packet analyzers.
HOSTNAME_UTF8	Convert label from/to normal UTF-8 data. Warning The HOSTNAME_UTF8 and HOSTNAME_XN flags represent two exclusively different formats, and combining them in for a hostname (or for an individual label) is likely to yield unpredictable results (the order in which these two flags are tested will vary depending on which blocks of code are doing the processing, and the programming logic being used; and future updates to the code may also affect changes to the order of flag tests and the programming logic). This format is normally presented to users to present hostnames natively in different languages. See also HOSTNAME_XN
HOSTNAME_XN	Convert label from/to punycode format wherein the first four characters will begin with the ASCII sequence "xn--" if any UTF-8 sequences are present. Warning The HOSTNAME_XN and HOSTNAME_UTF8 flags represent two exclusively different formats, and combining them in for a hostname (or for an individual label) is likely to yield unpredictable results (the order in which these two flags are tested will vary depending on which blocks of code are doing the processing, and the programming logic being used; and future updates to the code may also affect changes to the order of flag tests and the programming logic). This format is used by client software (e.g., eMail applicaitons and web browsers) when attempting to resolve the IP addresses of remote hosts or lookup other DNS records. See also HOSTNAME_UTF8

Constructor & Destructor Documentation

rlabel()

randolf::rlabel::rlabel ( const std::string  data, const int  flags = HOSTNAME_DEFAULT  )

inline

Structure constructor that detects whether any UTF-8 sequence is present in the data and/or if it's already in punycode format (e.g., it begins with the "xn--" sequence).

Although the default behaviour is to not convert the data between UTF-8 and punycode, either the HOSTNAME_UTF8 or HOSTNAME_XN flag may be specified to cause such a conversion for underlying storage. The benefit of using these flags here is mostly for performance optimization where repeated outbound conversions can be prevented when accessing the data multiple times.

Exceptions

std::invalid_argument

If the label is blank or there is a problem with the format (e.g., invalid characters)

Parameters

data	Label data
flags	HOSTNAME_DNS_RR Convert label from DNS RR format HOSTNAME_UTF8 Convert label to raw UTF-8 format (optional) HOSTNAME_XN Convert label to punycode format (optional)

Member Function Documentation

get()

std::string randolf::rlabel::get ( const int  flags = HOSTNAME_DEFAULT )

inline

Provice label as an std::string with any needed conversions.

Returns

Label as an std::string object

Parameters

flags

HOSTNAME_DNS_RR Convert label to DNS RR format HOSTNAME_UTF8 Convert label to raw UTF-8 format (optional) HOSTNAME_XN Convert label to punycode format (optional)

operator<()

bool randolf::rlabel::operator< ( const rlabel &  rhl ) const

inline

Built-in comparison operator used by std::set for ordering rlabel objects by the underlying label data.

Returns

Underlying rsocket_label

Parameters

rhl	This rlabel structure

Member Data Documentation

data

std::string randolf::rlabel::data

Label data.

dns_rr

bool randolf::rlabel::dns_rr = false

The DNS RR flag indicates that this label is derived from a DNS RR wherein the first character indicates the length of the label in bytes)

utf8

bool randolf::rlabel::utf8 = false

The UTF-8 flag indicates that this label is an internationalized label because it contains at least one UTF-8 sequence

xn

bool randolf::rlabel::xn = false

The xn flag indicates that this label seems to be in punycode format, because it begins with the sequence "xn--" and is at least 5 bytes long

idn2rc

int randolf::rlabel::idn2rc = IDN2_OK

Conversion return code (IDN2_OK = successful conversion to UTF8 or punycode; or this is the default because no conversion was performed)

---

The documentation for this struct was generated from the following file:

• randolf/rlabel