OPAL
Version 3.18.8
|
#include <transports.h>
Public Member Functions | |
Construction | |
OpalTransportAddress () | |
OpalTransportAddress (const char *address, WORD port=0, const char *proto=NULL) | |
OpalTransportAddress (const PString &address, WORD port=0, const char *proto=NULL) | |
OpalTransportAddress (const PIPSocket::Address &ip, WORD port=0, const char *proto=NULL) | |
OpalTransportAddress (const PIPSocket::AddressAndPort &ap, const char *proto=NULL) | |
virtual PObject * | Clone () const |
Clone function. More... | |
Static Public Member Functions | |
static const PCaselessString & | IpPrefix () |
static const PCaselessString & | UdpPrefix () |
static const PCaselessString & | TcpPrefix () |
Protected Member Functions | |
void | SetInternalTransport (WORD port, const char *proto) |
Protected Attributes | |
OpalInternalTransport * | m_transport |
Operations | |
enum | BindOptions { NoBinding, HostOnly, FullTSAP, Streamed, Datagram, RouteInterface, NumBindOptions } |
PBoolean | IsEquivalent (const OpalTransportAddress &address, bool wildcards=false) const |
PBoolean | IsCompatible (const OpalTransportAddress &address) const |
PCaselessString | GetProtoPrefix () const |
PCaselessString | GetProto (bool withDollar=false) const |
PBoolean | GetIpAddress (PIPSocket::Address &ip) const |
PBoolean | GetIpAndPort (PIPSocket::Address &ip, WORD &port) const |
PBoolean | GetIpAndPort (PIPSocketAddressAndPort &ipPort) const |
virtual PString | GetHostName (bool includeService=false) const |
OpalListener * | CreateListener (OpalEndPoint &endpoint, BindOptions option) const |
virtual OpalTransport * | CreateTransport (OpalEndPoint &endpoint, BindOptions option=HostOnly) const |
Describe a network transport address. This describes a full definition of a network transport address, which is usually more than just a host address. Broadly it consists of a low level protocol and a protocol specific address/port.
At present only Internet Protocol based addresses are supported.
There are some semantic differences when this is being used as an address to connect to, or as an address to listen on. The latter has several "wildcard" variants so it is not necessary to explicitly know a-priori everything about interfaces to start listening for incoming connections.
The syntax of the OpalTransportAddress string is:
transport-address = proto "$" proto-address
proto = "ip" | "tcp" | "udp" | "tls" | token
proto-address = addrport | any-string addrport = addr [ ":" port ]
addr = [ host ] [ "%" interface ] host = hostname | IPv4address | IPv6address | "*"
hostname = *( domainlabel "." ) toplabel [ "." ] domainlabel = alphanum | alphanum *( alphanum | "-" ) alphanum toplabel = alpha | alpha *( alphanum | "-" ) alphanum
IPv4address = 1*digit "." 1*digit "." 1*digit "." 1*digit
IPv6address = "[" hexpart [ "%" scope-id ] "]" hexpart = hexseq | hexseq "::" [ hexseq ] / "::" [ hexseq ] hexseq = hex4 *( ":" hex4) hex4 = 1*4 hexdigit hexdigit = digit | A-F | a-f scope-id = number | token
interface = number | any-string
port = number | token | "*" number = *digit
token = alpha * (alphanum) alphanum = alpha | digit alpha = A-Z | a-z digit = 0-9
any-string = 1* (any-char) any-char = %20-%7f
The semantics of certain elements are as follows: addr Must have at least one of host or "%" interface-name host = "*" indicates a wildcard match for all IP addresses. Note that for UDP there is a distinction between "*" and "0.0.0.0" and "[::]". A "*" will listen on both IPv4 and IPv6, while the INADDR_ANY and INADDR6_ANY values will only listen on that version of IP. For tcp "*" is a synonym for "0.0.0.0". port = "*" indicates port 0. This is only allowed when the OpalTransportAddress is being used to "listen" on a socket. It indicates any port number will do and should be allocated by the operating system. port = token Indicates a string as defined by getservbyname() scope-id Is dependent on the underlying operating system. For Win32 this must be a number indicating the interface id, for Linux this may be string, e.g. "eth0". Generally, the scope-id is only required to disambiguate "link-local" addresses. interface The number here is not necessarily the same as the number in scope-id. It is the index into the table returned by the PIPSocket::GetInterfaceTable() function. The text version of the interface is dependent on the operating system. For Linux this is the expected "eth0" etc, for Win32 this can be a quite long and complex name string.
Examples: tcp$*:1720 Listen on all interfaces for TCP port 1720. udp$127.0.0.1:5060 Indicate UDP port 5060 at local host udp$ppp0:5060 Listen on interface name ppp0, this may come on and off line at any time, and change the actual IP address used at any time. The system will do it's best to "do the right thing" in this situation. udp$10.0.1.1Win32 Interface Name:5060 Explicitly use address 10.0.1.1 on interface "Win32 interface name" tcp$my.host.domain.com:1720" A DNS lookup of my.host.domain.com is used to determine address. udp$[::]:5060 Listen on all IPv6 interfaces. This differs from udp$*:5060 in that only IPv6 interfaces are listened to. Similarly udp$0.0.0.0:5060 would only listen on IPv4 interfaces. udp$[fe80::224:21ff:fe9e:3e7b%26]:5060 Send packet out on link-local address fe80::224:21ff:fe9e:3e7b and interface id 26.
OpalTransportAddress::OpalTransportAddress | ( | ) |
Referenced by Clone().
OpalTransportAddress::OpalTransportAddress | ( | const char * | address, |
WORD | port = 0 , |
||
const char * | proto = NULL |
||
) |
address | Address string to parse |
port | Default port number |
proto | Default is "tcp" |
OpalTransportAddress::OpalTransportAddress | ( | const PString & | address, |
WORD | port = 0 , |
||
const char * | proto = NULL |
||
) |
address | Address string to parse |
port | Default port number |
proto | Default is "tcp" |
OpalTransportAddress::OpalTransportAddress | ( | const PIPSocket::Address & | ip, |
WORD | port = 0 , |
||
const char * | proto = NULL |
||
) |
ip | IP address for transport |
port | Default port number |
proto | Default is "tcp" |
OpalTransportAddress::OpalTransportAddress | ( | const PIPSocket::AddressAndPort & | ap, |
const char * | proto = NULL |
||
) |
ap | IP address and port for transport |
proto | Default is "tcp" |
|
inlinevirtual |
Clone function.
References OpalTransportAddress().
OpalListener* OpalTransportAddress::CreateListener | ( | OpalEndPoint & | endpoint, |
BindOptions | option | ||
) | const |
Create a listener based on this transport address. The BindOptions parameter indicates how the listener is to be created. Note that some transport types may not use this parameter.
With FullTSAP the the full address is used for any local binding, for example, an address of "tcp$10.0.0.1:1720" would create a TCP listening socket that would be bound to the specific interface 10.0.0.1 and listens on port 1720. Note that the address "tcp$*:1720" can be used to bind to INADDR_ANY, and a port number of zero indicates allocate a new random port number.
With HostOnly it would be equivalent to translating the above example to "tcp$10.0.0.1:0" before using it.
Using Streamed or Datagram is similar to HostOnly as only the host part of the address is used, but instead of using the protocol type specifed by the address it guarentees the specifeid type. In the above example Streamed would be identical to HostOnly and Datagram would translate the address to udp$10.0.0.1:0 before using it.
With NoBinding then a compatible listener is created and no local binding is made. This is equivalent to translating the address to "tcp$*:0" so that only the overall protocol type is used.
With RouteInterface, the address is considered a remote address and the created transport is bound only to the address associated with the interface that would be used to get to that address.
Also note that if the address has a trailing '+' character then the socket will be bound using the REUSEADDR option, where relevant.
endpoint | Endpoint object for transport creation. |
option | Options for how to create listener |
|
virtual |
Create a transport suitable for this address type. The BindOptions parameter indicates how the transport is to be created. Note that some transport types may not use this parameter.
With FullTSAP the the full address is used for any local binding, for example, an address of "tcp$10.0.0.1:1720" would create a TCP transport socket that would be bound to the specific interface 10.0.0.1 and port 1720. Note that the address "tcp$*:1720" can be used to bind to INADDR_ANY, and a port number of zero indicates allocate a new random port number.
With HostOnly it would be equivalent to translating the above example to "tcp$10.0.0.1:0" before using it.
Using Streamed or Datagram is similar to HostOnly as only the host part of the address is used, but instead of using the protocol type specifed by the address it guarentees the specifeid type. In the above example Streamed would be identical to HostOnly and Datagram would translate the address to udp$10.0.0.1:0 before using it.
With NoBinding then a compatible transport is created and no local binding is made. This is equivalent to translating the address to "tcp$*:0" so that only the overall protocol type is used.
Also note that if the address has a trailing '+' character then the socket will be bound using the REUSEADDR option.
endpoint | Endpoint object for transport creation. |
option | Options for how to create transport |
|
virtual |
Translate the transport address to a more human readable form. Returns the hostname if using IP.
PBoolean OpalTransportAddress::GetIpAddress | ( | PIPSocket::Address & | ip | ) | const |
Extract the ip address from transport address. Returns false, if the address is not an IP transport address.
PBoolean OpalTransportAddress::GetIpAndPort | ( | PIPSocket::Address & | ip, |
WORD & | port | ||
) | const |
Extract the ip address and port number from transport address. Returns false, if the address is not an IP transport address.
PBoolean OpalTransportAddress::GetIpAndPort | ( | PIPSocketAddressAndPort & | ipPort | ) | const |
|
inline |
|
inline |
Return the underlying protocol for the transport address.
|
static |
PBoolean OpalTransportAddress::IsCompatible | ( | const OpalTransportAddress & | address | ) | const |
Determine if the two transport addresses are compatible.
PBoolean OpalTransportAddress::IsEquivalent | ( | const OpalTransportAddress & | address, |
bool | wildcards = false |
||
) | const |
Determine if the two transport addresses are equivalent. The second parameter indicates if wildcards are allowed. A wildcard IP address is one for which isAny() returns true, a wildcard port is the value 65535.
address | Address to compare |
wildcards | Allow wildcards |
|
protected |
port | Default port number |
proto | Default is "tcp" |
|
static |
|
static |
|
protected |