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

A class that represents the remote target for out-going client connections. More...

#include <glocation.h>

Public Member Functions

 Location (const std::string &spec, int family=AF_UNSPEC)
 Constructor taking a formatted "host:service" string. More...
 
std::string host () const
 Returns the remote host name derived from the constructor parameter. More...
 
std::string service () const
 Returns the remote service name derived from the constructor parameter. More...
 
int family () const
 Returns the preferred name resolution address family as passed to the constructor. More...
 
bool socks () const
 Returns true if a socks location. More...
 
bool resolveTrivially ()
 If host() and service() are already in address format then do a trivial update() so that the location is immediately resolved(), albeit with an empty canonical name(). More...
 
void update (const Address &address, const std::string &canonical_name)
 Updates the address and canonical name, typically after doing a name lookup on host() and service(). More...
 
bool update (const Address &address, const std::string &canonical_name, std::nothrow_t)
 Updates the address and canonical name, typically after doing a name lookup on host() and service(). More...
 
bool resolved () const
 Returns true after update() has been called or resolveTrivially() succeeded. More...
 
Address address () const
 Returns the remote address. More...
 
std::string name () const
 Returns the remote canonical name. More...
 
std::string displayString () const
 Returns a string representation for logging and debug. More...
 
G::SystemTime updateTime () const
 Returns the time of the last update() or zero if never update()d. More...
 
unsigned int socksFarPort () const
 Returns the port number for the socks far server. More...
 
std::string socksFarHost () const
 Returns the port for the socks far server. More...
 

Static Public Member Functions

static Location nosocks (const std::string &spec, int family=AF_UNSPEC)
 Factory function for a remote location but not allowing the extended syntax for socks. More...
 
static Location socks (const std::string &socks_server, const std::string &far_server)
 Factory function for a remote location explicitly accessed via socks. More...
 

Detailed Description

A class that represents the remote target for out-going client connections.

It holds a host/service name pair and the preferred address family (if any) and also the results of a DNS lookup, ie. the remote address and canonical host name.

The actual DNS lookup of host() and service() should be done externally, with the results deposited into the Location object with update().

An extended format is supported for transparent SOCKS connection: before the "@" separator is the host/port pair passed verbatim to the socks server for it to resolve; after the "@" is the host/service pair for the socks server itself, which should be resolved as normal.

URL-style square brackets can be used for IPv6 address, eg( "[::1]:1").

Local-domain socket addresses are supported, but obviously DNS lookups of host() and service() will never work, update() will reject them, and the socks code will not allow them as the 'far' address.

Synopsis:

Location location( remote_server ) ;
location.resolveTrivially() ;
if( !location.resolved() )
{
Resolver resolver( location.host() , location.service() , location.family() ) ;
if( resolver.resolve() )
location.update( resolver.address() , resolver.cname() ) ;
}
Location(const std::string &spec, int family=AF_UNSPEC)
Constructor taking a formatted "host:service" string.
Definition: glocation.cpp:27
See also
GNet::Client, GNet::Resolver

Definition at line 70 of file glocation.h.

Constructor & Destructor Documentation

◆ Location()

GNet::Location::Location ( const std::string &  spec,
int  family = AF_UNSPEC 
)
explicit

Constructor taking a formatted "host:service" string.

The location specification allows an extended format for socks, as "far-host:far-port@socks-host:socks-service". Throws if incorrectly formatted. The optional 'family' parameter is made available to the resolver via the family() method.

Definition at line 27 of file glocation.cpp.

Member Function Documentation

◆ address()

GNet::Address GNet::Location::address ( ) const

Returns the remote address.

Definition at line 147 of file glocation.cpp.

◆ displayString()

std::string GNet::Location::displayString ( ) const

Returns a string representation for logging and debug.

Definition at line 182 of file glocation.cpp.

◆ family()

int GNet::Location::family ( ) const

Returns the preferred name resolution address family as passed to the constructor.

Definition at line 125 of file glocation.cpp.

◆ host()

std::string GNet::Location::host ( ) const

Returns the remote host name derived from the constructor parameter.

Definition at line 115 of file glocation.cpp.

◆ name()

std::string GNet::Location::name ( ) const

Returns the remote canonical name.

Returns the empty string if not available.

Definition at line 177 of file glocation.cpp.

◆ nosocks()

GNet::Location GNet::Location::nosocks ( const std::string &  spec,
int  family = AF_UNSPEC 
)
static

Factory function for a remote location but not allowing the extended syntax for socks.

Definition at line 72 of file glocation.cpp.

◆ resolved()

bool GNet::Location::resolved ( ) const

Returns true after update() has been called or resolveTrivially() succeeded.

Definition at line 142 of file glocation.cpp.

◆ resolveTrivially()

bool GNet::Location::resolveTrivially ( )

If host() and service() are already in address format then do a trivial update() so that the location is immediately resolved(), albeit with an empty canonical name().

Does nothing if already resolved(). Returns resolved().

Definition at line 130 of file glocation.cpp.

◆ service()

std::string GNet::Location::service ( ) const

Returns the remote service name derived from the constructor parameter.

Definition at line 120 of file glocation.cpp.

◆ socks() [1/2]

bool GNet::Location::socks ( ) const

Returns true if a socks location.

Definition at line 204 of file glocation.cpp.

◆ socks() [2/2]

GNet::Location GNet::Location::socks ( const std::string &  socks_server,
const std::string &  far_server 
)
static

Factory function for a remote location explicitly accessed via socks.

Definition at line 77 of file glocation.cpp.

◆ socksFarHost()

std::string GNet::Location::socksFarHost ( ) const

Returns the port for the socks far server.

Precondition: socks()

Definition at line 215 of file glocation.cpp.

◆ socksFarPort()

unsigned int GNet::Location::socksFarPort ( ) const

Returns the port number for the socks far server.

Precondition: socks()

Definition at line 209 of file glocation.cpp.

◆ update() [1/2]

void GNet::Location::update ( const Address address,
const std::string &  canonical_name 
)

Updates the address and canonical name, typically after doing a name lookup on host() and service().

Throws if an invalid address family.

Definition at line 152 of file glocation.cpp.

◆ update() [2/2]

bool GNet::Location::update ( const Address address,
const std::string &  canonical_name,
std::nothrow_t   
)

Updates the address and canonical name, typically after doing a name lookup on host() and service().

Returns false if an invalid address family.

Definition at line 158 of file glocation.cpp.

◆ updateTime()

G::SystemTime GNet::Location::updateTime ( ) const

Returns the time of the last update() or zero if never update()d.

Definition at line 199 of file glocation.cpp.


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