# OpalTransportAddress Class Reference

`#include <transports.h>`

Inheritance diagram for OpalTransportAddress:

[legend]
Collaboration diagram for OpalTransportAddress:
[legend]

## 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

## 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, const char *proto=NULL)
virtual PObject * | Clone () const
| Clone function.

## 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

## Detailed Description

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:3e7b26]:5060 Send packet out on link-local address fe80::224:21ff:fe9e:3e7b and interface id 26.

## Member Enumeration Documentation

enum OpalTransportAddress::BindOptions

Enumerator:

  NoBinding |
  HostOnly |
  FullTSAP |
  Streamed |
  Datagram |
  RouteInterface |
  NumBindOptions |

## Constructor & Destructor Documentation

OpalTransportAddress::OpalTransportAddress | ( |  | ) |

OpalTransportAddress::OpalTransportAddress | ( | const char * | address,
|  | WORD | port = `0`,
|  | const char * | proto = `NULL` |
| ) |  |  |

Parameters:

  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` |
| ) |  |  |

Parameters:

  address | Address string to parse
  port | Default port number
  proto | Default is "tcp"

OpalTransportAddress::OpalTransportAddress | ( | const PIPSocket::Address & | ip,
|  | WORD | port,
|  | const char * | proto = `NULL` |
| ) |  |  |

Parameters:

  ip | IP address for transport
  port | Default port number
  proto | Default is "tcp"

## Member Function Documentation

virtual PObject* OpalTransportAddress::Clone | ( |  | ) | const`[inline, virtual]`

Clone function.

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.

Parameters:

  endpoint | Endpoint object for transport creation.
  option | Options for how to create listener

virtual OpalTransport* OpalTransportAddress::CreateTransport | ( | OpalEndPoint & | endpoint,
|  | BindOptions | option = `HostOnly` |
| ) |  |  | const`[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.

Parameters:

  endpoint | Endpoint object for transport creation.
  option | Options for how to create transport

virtual PString OpalTransportAddress::GetHostName | ( | bool | includeService = `false` | ) | const`[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 | ( | PIPSocketAddressAndPort & | ipPort | ) | const

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.

PCaselessString OpalTransportAddress::GetProto | ( | bool | withDollar = `false` | ) | const`[inline]`

PCaselessString OpalTransportAddress::GetProtoPrefix | ( |  | ) | const`[inline]`

Return the underlying protocol for the transport address.

static const PCaselessString& OpalTransportAddress::IpPrefix | ( |  | ) | `[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.

Parameters:

  address | Address to compare
  wildcards | Allow wildcards

void OpalTransportAddress::SetInternalTransport | ( | WORD | port,
|  | const char * | proto |
| ) |  |  | `[protected]`

Parameters:

  port | Default port number
  proto | Default is "tcp"

static const PCaselessString& OpalTransportAddress::TcpPrefix | ( |  | ) | `[static]`

static const PCaselessString& OpalTransportAddress::UdpPrefix | ( |  | ) | `[static]`

## Field Documentation

OpalInternalTransport* OpalTransportAddress::m_transport `[protected]`

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

- transports.h