E-MailRelay
Classes | Public Types | Public Member Functions | Static Public Member Functions | List of all members
GNet::Address Class Reference

The GNet::Address class encapsulates a TCP/UDP transport address. More...

#include <gaddress.h>

Classes

struct  Domain
 Overload discriminator for Address::supports() More...
 
struct  NotLocal
 Overload discriminator for Address::parse() More...
 

Public Types

enum class  Family { ipv4 , ipv6 , local }
 

Public Member Functions

 Address (const Address &)
 Copy constructor. More...
 
 Address (const AddressStorage &)
 Constructor taking a storage object. More...
 
 Address (const sockaddr *addr, socklen_t len)
 Constructor using a given sockaddr. More...
 
 Address (const sockaddr *addr, socklen_t len, bool fixup)
 An overload that conditionally applies the bsd ipv6 scope-id fixup. More...
 
 Address (Family, unsigned int port)
 Constructor for a wildcard address like INADDR_ANY with the given port number. More...
 
 Address (Address &&) noexcept
 Move constructor.
 
 ~Address ()
 Destructor.
 
Addressoperator= (const Address &)
 Assignment operator. More...
 
Addressoperator= (Address &&) noexcept
 Move assignment operator.
 
const sockaddr * address () const
 Returns the sockaddr address. More...
 
sockaddr * address ()
 This is a non-const version of address() for compiling on systems which are not properly const-clean. More...
 
socklen_t length () const
 Returns the size of the sockaddr address. See address(). More...
 
std::string displayString (bool with_scope_id=false) const
 Returns a string which represents the transport address. More...
 
std::string hostPartString (bool raw=false) const
 Returns a string which represents the network address. More...
 
std::string queryString () const
 Returns a string that can be used as a prefix for rDNS or DNSBL queries. More...
 
unsigned int port () const
 Returns port part of the address. More...
 
Family family () const
 Returns the address family enumeration. More...
 
int af () const
 Returns the address family number such as AF_INET or AFINET6. More...
 
bool sameHostPart (const Address &other) const
 Returns true if the two addresses have the same host part (ie. More...
 
AddresssetPort (unsigned int port)
 Sets the port number. More...
 
bool setZone (const std::string &)
 Sets the zone. More...
 
AddresssetScopeId (unsigned long)
 Sets the scope-id. More...
 
unsigned long scopeId (unsigned long default_=0UL) const
 Returns the scope-id. More...
 
G::StringArray wildcards () const
 Returns an ordered list of wildcard strings that match this address. More...
 
unsigned int bits () const
 Returns the number of leading bits set, relevant only to netmask addresses. More...
 
bool isLoopback () const
 Returns true if this is a loopback address. More...
 
bool isLinkLocal () const
 Returns true if this is a link-local address. More...
 
bool isUniqueLocal () const
 Returns true if this is a locally administered address. More...
 
bool isAny () const
 Returns true if this is the address family's 'any' address. More...
 
bool isLocal (std::string &reason) const
 Returns true if this seems to be a 'local' address, ie. More...
 
bool is4 () const
 Returns true if family() is ipv4. More...
 
bool is6 () const
 Returns true if family() is ipv6. More...
 
bool same (const Address &, bool ipv6_compare_with_scope) const
 Comparison function. More...
 
bool operator== (const Address &) const
 Comparison operator. More...
 
bool operator!= (const Address &) const
 Comparison operator. More...
 
void swap (Address &other) noexcept
 Swaps this with other. More...
 

Static Public Member Functions

static bool supports (Family)
 Returns true if the implementation supports the given address family. More...
 
static bool supports (int af, int dummy)
 Returns true if the implementation supports the given address family given as AF_INET etc. More...
 
static bool supports (const Domain &, int domain)
 Returns true if the implementation supports the given address domain given as PF_INET etc. More...
 
static Address parse (const std::string &display_string)
 Factory function for any address family. More...
 
static Address parse (const std::string &display_string, NotLocal)
 Factory function for Family::ipv4 or Family::ipv6. More...
 
static Address parse (const std::string &host_part_string, unsigned int port)
 Factory function for Family::ipv4 or Family::ipv6. More...
 
static Address parse (const std::string &host_part_string, const std::string &port)
 Factory function for Family::ipv4 or Family::ipv6. More...
 
static bool isFamilyLocal (const std::string &display_string)
 Returns true if the given address display string looks will parse to Family::local and Family::local is supported. More...
 
static Address defaultAddress ()
 Returns a default address, being the IPv4 wildcard address with a zero port number. More...
 
static Address loopback (Family, unsigned int port=0U)
 Returns a loopback address. More...
 
static int domain (Family)
 Returns the address 'domain' for the given family, eg. More...
 
static bool validPort (unsigned int n)
 Returns true if the port number is within the valid range. More...
 
static bool validString (const std::string &display_string, std::string *reason=nullptr)
 Returns true if the transport-address display string is valid. More...
 
static bool validString (const std::string &display_string, NotLocal, std::string *reason=nullptr)
 Returns true if the transport-address display string is valid. More...
 
static bool validStrings (const std::string &ip, const std::string &port_string, std::string *reason=nullptr)
 Returns true if the combined network-address string and port string is valid. More...
 
static bool validData (const sockaddr *, socklen_t len)
 Returns true if the sockaddr data is valid. More...
 

Detailed Description

The GNet::Address class encapsulates a TCP/UDP transport address.

The address is exposed as a 'sockaddr' structure for low-level socket operations.

A multi-pimple pattern is used for the implementation, with implementation classes including GNet::Address4 and GNet::Address6. In an IPv4-only build the GNet::Address6 can be forward-declared but not defined, with all methods forwarded to the GNet::Address4 sub-object.

See also
GNet::Resolver

Definition at line 52 of file gaddress.h.

Member Enumeration Documentation

◆ Family

enum class GNet::Address::Family
strong

Definition at line 55 of file gaddress.h.

Constructor & Destructor Documentation

◆ Address() [1/5]

GNet::Address::Address ( const Address other)

Copy constructor.

Definition at line 183 of file gaddress.cpp.

◆ Address() [2/5]

GNet::Address::Address ( const AddressStorage storage)
explicit

Constructor taking a storage object.

Definition at line 63 of file gaddress.cpp.

◆ Address() [3/5]

GNet::Address::Address ( const sockaddr *  addr,
socklen_t  len 
)

Constructor using a given sockaddr.

Throws an exception if an invalid structure. See also: validData()

Definition at line 77 of file gaddress.cpp.

◆ Address() [4/5]

GNet::Address::Address ( const sockaddr *  addr,
socklen_t  len,
bool  fixup 
)

An overload that conditionally applies the bsd ipv6 scope-id fixup.

Definition at line 93 of file gaddress.cpp.

◆ Address() [5/5]

GNet::Address::Address ( Family  f,
unsigned int  port 
)

Constructor for a wildcard address like INADDR_ANY with the given port number.

Throws an exception if an invalid port number. Postcondition: isAny()

See also
validPort()

Definition at line 51 of file gaddress.cpp.

Member Function Documentation

◆ address() [1/2]

sockaddr * GNet::Address::address ( )

This is a non-const version of address() for compiling on systems which are not properly const-clean.

Definition at line 425 of file gaddress.cpp.

◆ address() [2/2]

const sockaddr * GNet::Address::address ( ) const

Returns the sockaddr address.

Typically used when making socket system calls. Never returns nullptr.

Definition at line 434 of file gaddress.cpp.

◆ af()

int GNet::Address::af ( ) const

Returns the address family number such as AF_INET or AFINET6.

Definition at line 500 of file gaddress.cpp.

◆ bits()

unsigned int GNet::Address::bits ( ) const

Returns the number of leading bits set, relevant only to netmask addresses.

Definition at line 279 of file gaddress.cpp.

◆ defaultAddress()

GNet::Address GNet::Address::defaultAddress ( )
static

Returns a default address, being the IPv4 wildcard address with a zero port number.

Definition at line 242 of file gaddress.cpp.

◆ displayString()

std::string GNet::Address::displayString ( bool  with_scope_id = false) const

Returns a string which represents the transport address.

Definition at line 375 of file gaddress.cpp.

◆ domain()

int GNet::Address::domain ( Family  family)
static

Returns the address 'domain' for the given family, eg.

PF_INET for Family::ipv4.

Definition at line 483 of file gaddress.cpp.

◆ family()

GNet::Address::Family GNet::Address::family ( ) const

Returns the address family enumeration.

Definition at line 491 of file gaddress.cpp.

◆ hostPartString()

std::string GNet::Address::hostPartString ( bool  raw = false) const

Returns a string which represents the network address.

For unix-domain sockets this returns the address path and if the 'raw' parameter is set then any non-printing characters are not escaped.

Definition at line 384 of file gaddress.cpp.

◆ is4()

bool GNet::Address::is4 ( ) const

Returns true if family() is ipv4.

Definition at line 333 of file gaddress.cpp.

◆ is6()

bool GNet::Address::is6 ( ) const

Returns true if family() is ipv6.

Definition at line 338 of file gaddress.cpp.

◆ isAny()

bool GNet::Address::isAny ( ) const

Returns true if this is the address family's 'any' address.

Definition at line 324 of file gaddress.cpp.

◆ isFamilyLocal()

bool GNet::Address::isFamilyLocal ( const std::string &  display_string)
static

Returns true if the given address display string looks will parse to Family::local and Family::local is supported.

The address may still fail to parse if it is invalid.

Definition at line 237 of file gaddress.cpp.

◆ isLinkLocal()

bool GNet::Address::isLinkLocal ( ) const

Returns true if this is a link-local address.

Definition at line 306 of file gaddress.cpp.

◆ isLocal()

bool GNet::Address::isLocal ( std::string &  reason) const

Returns true if this seems to be a 'local' address, ie.

an address that is likely to be more trusted. Returns an explanation by reference otherwise.

Definition at line 297 of file gaddress.cpp.

◆ isLoopback()

bool GNet::Address::isLoopback ( ) const

Returns true if this is a loopback address.

Definition at line 288 of file gaddress.cpp.

◆ isUniqueLocal()

bool GNet::Address::isUniqueLocal ( ) const

Returns true if this is a locally administered address.

Definition at line 315 of file gaddress.cpp.

◆ length()

socklen_t GNet::Address::length ( ) const

Returns the size of the sockaddr address. See address().

Definition at line 443 of file gaddress.cpp.

◆ loopback()

GNet::Address GNet::Address::loopback ( Family  f,
unsigned int  port = 0U 
)
static

Returns a loopback address.

Definition at line 247 of file gaddress.cpp.

◆ operator!=()

bool GNet::Address::operator!= ( const Address other) const

Comparison operator.

Definition at line 361 of file gaddress.cpp.

◆ operator=()

GNet::Address & GNet::Address::operator= ( const Address other)

Assignment operator.

Definition at line 208 of file gaddress.cpp.

◆ operator==()

bool GNet::Address::operator== ( const Address other) const

Comparison operator.

Definition at line 352 of file gaddress.cpp.

◆ parse() [1/4]

GNet::Address GNet::Address::parse ( const std::string &  display_string)
static

Factory function for any address family.

Throws if an invalid string. See also validString().

Definition at line 217 of file gaddress.cpp.

◆ parse() [2/4]

GNet::Address GNet::Address::parse ( const std::string &  display_string,
Address::NotLocal  not_local 
)
static

Factory function for Family::ipv4 or Family::ipv6.

Throws if an invalid string. See also validString().

Definition at line 222 of file gaddress.cpp.

◆ parse() [3/4]

GNet::Address GNet::Address::parse ( const std::string &  host_part_string,
const std::string &  port 
)
static

Factory function for Family::ipv4 or Family::ipv6.

Throws if an invalid string. See also validStrings().

Definition at line 232 of file gaddress.cpp.

◆ parse() [4/4]

GNet::Address GNet::Address::parse ( const std::string &  host_part_string,
unsigned int  port 
)
static

Factory function for Family::ipv4 or Family::ipv6.

Throws if an invalid string. See also validStrings().

Definition at line 227 of file gaddress.cpp.

◆ port()

unsigned int GNet::Address::port ( ) const

Returns port part of the address.

Definition at line 452 of file gaddress.cpp.

◆ queryString()

std::string GNet::Address::queryString ( ) const

Returns a string that can be used as a prefix for rDNS or DNSBL queries.

Definition at line 393 of file gaddress.cpp.

◆ same()

bool GNet::Address::same ( const Address other,
bool  ipv6_compare_with_scope 
) const

Comparison function.

Definition at line 343 of file gaddress.cpp.

◆ sameHostPart()

bool GNet::Address::sameHostPart ( const Address other) const

Returns true if the two addresses have the same host part (ie.

the network address, ignoring the port number).

Definition at line 366 of file gaddress.cpp.

◆ scopeId()

unsigned long GNet::Address::scopeId ( unsigned long  default_ = 0UL) const

Returns the scope-id.

Returns the default if scope-ids are not supported by the underlying address type.

Definition at line 461 of file gaddress.cpp.

◆ setPort()

GNet::Address & GNet::Address::setPort ( unsigned int  port)

Sets the port number.

Throws an exception if an invalid port number (ie. too big).

Definition at line 252 of file gaddress.cpp.

◆ setScopeId()

GNet::Address & GNet::Address::setScopeId ( unsigned long  ipv6_scope_id)

Sets the scope-id.

Definition at line 270 of file gaddress.cpp.

◆ setZone()

bool GNet::Address::setZone ( const std::string &  ipv6_zone)

Sets the zone.

The parameter is normally a decimal string representation of the zone-id, aka scope-id (eg. "1"), but if not numeric then it is treated as an interface name which is mapped to a zone-id by if_nametoindex(3). Returns false on error. Returns true if zones are not used by the address family.

Definition at line 261 of file gaddress.cpp.

◆ supports() [1/3]

bool GNet::Address::supports ( const Domain ,
int  domain 
)
static

Returns true if the implementation supports the given address domain given as PF_INET etc.

Definition at line 46 of file gaddress.cpp.

◆ supports() [2/3]

bool GNet::Address::supports ( Family  f)
static

Returns true if the implementation supports the given address family.

Definition at line 33 of file gaddress.cpp.

◆ supports() [3/3]

bool GNet::Address::supports ( int  af,
int  dummy 
)
static

Returns true if the implementation supports the given address family given as AF_INET etc.

Definition at line 41 of file gaddress.cpp.

◆ swap()

void GNet::Address::swap ( Address other)
noexcept

Swaps this with other.

Definition at line 200 of file gaddress.cpp.

◆ validData()

bool GNet::Address::validData ( const sockaddr *  addr,
socklen_t  len 
)
static

Returns true if the sockaddr data is valid.

This can be used to avoid exceptions from the relevant constructor.

Definition at line 475 of file gaddress.cpp.

◆ validPort()

bool GNet::Address::validPort ( unsigned int  n)
static

Returns true if the port number is within the valid range.

This can be used to avoid exceptions from the relevant constructors.

Definition at line 470 of file gaddress.cpp.

◆ validString() [1/2]

bool GNet::Address::validString ( const std::string &  display_string,
NotLocal  ,
std::string *  reason = nullptr 
)
static

Returns true if the transport-address display string is valid.

This can be used to avoid exceptions from the relevant constructor.

Definition at line 410 of file gaddress.cpp.

◆ validString() [2/2]

bool GNet::Address::validString ( const std::string &  display_string,
std::string *  reason = nullptr 
)
static

Returns true if the transport-address display string is valid.

This can be used to avoid exceptions from the relevant constructor.

Definition at line 402 of file gaddress.cpp.

◆ validStrings()

bool GNet::Address::validStrings ( const std::string &  ip,
const std::string &  port_string,
std::string *  reason = nullptr 
)
static

Returns true if the combined network-address string and port string is valid.

This can be used to avoid exceptions from the relevant constructor.

Definition at line 417 of file gaddress.cpp.

◆ wildcards()

G::StringArray GNet::Address::wildcards ( ) const

Returns an ordered list of wildcard strings that match this address.

The fully-address-specific string (eg. "192.168.0.1") comes first, and the most general match-all wildcard like "*.*.*.*" or "128.0.0.0/1" comes last.

Definition at line 509 of file gaddress.cpp.


The documentation for this class was generated from the following files: