randolf.ca  1.00
Randolf Richardson's C++ classes
Loading...
Searching...
No Matches
randolf::rlabel Struct Reference

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

#include <rlabel>

+ 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).
 
std::string get (const int flags=HOSTNAME_DEFAULT)
 Provice label as an std::string with any needed conversions.
 
bool operator< (const rlabel &rhl) const
 Built-in comparison operator used by std::set for ordering rlabel objects by the underlying label data.
 

Public Attributes

std::string data
 Label data.
 
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

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_argumentIf the label is blank or there is a problem with the format (e.g., invalid characters)
Parameters
dataLabel data
flagsHOSTNAME_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
flagsHOSTNAME_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
rhlThis 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: