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(). More...
 
void update (const Address &address)
 Updates the address, typically after doing a name lookup on host() and service(). More...
 
bool update (const Address &address, std::nothrow_t)
 Updates the address, 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 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 for the remote address.

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() ) ;
}
Location(const std::string &spec, int family=AF_UNSPEC)
Constructor taking a formatted "host:service" string.
Definition: glocation.cpp:28
See also
GNet::Client, GNet::Resolver

Definition at line 69 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 28 of file glocation.cpp.

Member Function Documentation

◆ address()

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

Returns the remote address.

Definition at line 153 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 132 of file glocation.cpp.

◆ host()

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

Returns the remote host name derived from the constructor parameter.

Definition at line 122 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 77 of file glocation.cpp.

◆ resolved()

bool GNet::Location::resolved ( ) const

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

Definition at line 148 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().

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

Definition at line 137 of file glocation.cpp.

◆ service()

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

Returns the remote service name derived from the constructor parameter.

Definition at line 127 of file glocation.cpp.

◆ socks() [1/2]

bool GNet::Location::socks ( ) const

Returns true if a socks location.

Definition at line 206 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 83 of file glocation.cpp.

◆ socksFarHost()

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

Returns the port for the socks far server.

Precondition: socks()

Definition at line 217 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 211 of file glocation.cpp.

◆ update() [1/2]

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

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

Throws if an invalid address family.

Definition at line 158 of file glocation.cpp.

◆ update() [2/2]

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

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

Returns false if an invalid address family.

Definition at line 164 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 200 of file glocation.cpp.


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