# IAX2EndPoint Class Reference

`#include <iax2ep.h>`

Inheritance diagram for IAX2EndPoint:

[legend]
Collaboration diagram for IAX2EndPoint:
[legend]

## worker Methods

enum | IAX2RemoteAddressFields { protoIndex = 0, userIndex = 1, transportIndex = 2, addressIndex = 3, portIndex = 4, extensionIndex = 5, contextIndex = 6, maximumIndex = 7 }
enum | RegisteredError { RegisteredFailureUnknown }
enum | UnregisteredError { UnregisteredFailureUnknown }
PBoolean | Initialise ()
virtual void | IncomingEthernetFrame (IAX2Frame *frame)
PBoolean | ConectionForFrameIsAlive (IAX2Frame *f)
PINDEX | NextSrcCallNumber (IAX2Processor *processor)
void | ReportStoredConnections ()
WORD | ListenPortNumber ()
PString | GetLocalUserName ()
PString | GetLocalNumber ()
void | SetLocalUserName (PString newValue)
void | SetLocalNumber (PString newValue)
PString & | GetPassword ()
void | SetPassword (PString newValue)
PBoolean | ConnectionForFrameIsAlive (IAX2Frame *f)
PINDEX | GetOutSequenceNumberForStatusQuery ()
void | StartRinging (PString remoteCaller)
void | NewIncomingConnection (IAX2Frame *f)
void | OnEstablished (OpalConnection &con)
virtual void | OnReleased (OpalConnection &connection)
virtual OpalMediaFormatList | GetMediaFormats () const
PINDEX | GetSupportedCodecs (OpalMediaFormatList &list)
PINDEX | GetPreferredCodec (OpalMediaFormatList &list)
void | GetCodecLengths (PINDEX src, PINDEX &compressedBytes, PINDEX &duration)
void | ProcessReceivedEthernetFrames ()
void | ReportTransmitterLists (PString &answer, bool getFullReport=false)
void | CopyLocalMediaFormats (OpalMediaFormatList &list)
void | Register (const PString &host, const PString &username, const PString &password=PString::Empty(), PINDEX requestedRefreshTime=60)
virtual void | OnRegistered (const PString &host, const PString &userName, PBoolean isFailure, RegisteredError reason=RegisteredFailureUnknown)
void | Unregister (const PString &host, const PString &username)
virtual void | OnUnregistered (const PString &host, const PString &userName, PBoolean isFailure, UnregisteredError reason=UnregisteredFailureUnknown)
PBoolean | IsRegistered (const PString &host, const PString &username)
PINDEX | GetRegistrationsCount ()
PString | BuildUrl (const PString &host, const PString &userName=PString::Empty(), const PString &extension=PString::Empty(), const PString &context=PString::Empty(), const PString &transport=PString::Empty())
PBoolean | InitialisedOK ()
PBoolean | EthernetFramesToBeProcessed ()
IAX2Transmit * | transmitter
IAX2Receiver * | receiver
static PStringArray | DissectRemoteParty (const PString &other)

## Public Types

| DefaultUdpPort = 4569
| protoIndex = 0
| userIndex = 1
| transportIndex = 2
| addressIndex = 3
| portIndex = 4
| extensionIndex = 5
| contextIndex = 6
| maximumIndex = 7
| RegisteredFailureUnknown
| UnregisteredFailureUnknown
enum | { DefaultUdpPort = 4569 }

## Public Member Functions

Construction
| IAX2EndPoint (OpalManager &manager)
| ~IAX2EndPoint ()
connection Connection handling
virtual PString | GetDefaultTransport () const
virtual WORD | GetDefaultSignalPort () const
virtual PSafePtr< OpalConnection > | MakeConnection (OpalCall &call, const PString &party, void *userData=NULL, unsigned int options=0, OpalConnection::StringOptions *stringOptions=NULL)
virtual IAX2Connection * | CreateConnection (OpalCall &call, const PString &token, void *userData, const PString &remoteParty, const PString &remotePartyName=PString::Empty())

## Protected Member Functions

PBoolean | ProcessInMatchingConnection (IAX2Frame *f)
PBoolean | ProcessFrameInConnection (IAX2Frame *f, const PString &token)
PBoolean | ProcessInConnectionTestAll (IAX2Frame *f)

## Protected Attributes

IAX2IncomingEthernetFrames | incomingFrameHandler
IAX2FrameList | packetsReadFromEthernet
PUDPSocket * | sock
int | callnumbs
PMutex | callNumbLock
PTime | callStartTime
PString | localUserName
PString | localNumber
PString | password
PINDEX | statusQueryCounter
PMutex | statusQueryMutex
IAX2SpecialProcessor * | specialPacketHandler
PStringToString | tokenTable
PReadWriteMutex | mutexTokenTable
PAtomicInteger | callsEstablished
OpalMediaFormatList | localMediaFormats
PMutex | regProcessorsMutex
PArrayObjects | regProcessors

## Detailed Description

A class to manage global variables. There is one Endpoint per application.

## Member Enumeration Documentation

anonymous enum

Enumerator:

  DefaultUdpPort |

enum IAX2EndPoint::IAX2RemoteAddressFields

enum of the components from a remote party address string These fields are from the address,

[iax2:]{username@][transport$]address[/extension][+context]

Enumerator:

  protoIndex | the protocol, or iax2: field
  userIndex | the username, or alias field
  transportIndex | the transport, or transport field
  addressIndex | the address, or 192.168.1.1 field
  portIndex | the port number
  extensionIndex | the extension, or "extension"" field
  contextIndex | the context, or "+context" field
  maximumIndex | the number of possible fields

enum IAX2EndPoint::RegisteredError

Enumerator:

  RegisteredFailureUnknown |

enum IAX2EndPoint::UnregisteredError

Enumerator:

  UnregisteredFailureUnknown |

## Constructor & Destructor Documentation

IAX2EndPoint::IAX2EndPoint | ( | OpalManager & | manager | ) |

Create the endpoint, and define local variables

IAX2EndPoint::~IAX2EndPoint | ( |  | ) |

Destroy the endpoint, and all associated connections

## Member Function Documentation

PString IAX2EndPoint::BuildUrl | ( | const PString & | host,
|  | const PString & | userName = `PString::Empty()`,
|  | const PString & | extension = `PString::Empty()`,
|  | const PString & | context = `PString::Empty()`,
|  | const PString & | transport = `PString::Empty()` |
| ) |  |  |

Builds a url

PBoolean IAX2EndPoint::ConectionForFrameIsAlive | ( | IAX2Frame * | f | ) |

A simple test to report if the connection associated with this frame is still alive. This test is used when transmitting the frame. If the connection is gone, don't bother transmitting the frame. There are exceptins to this rule, such as when a hangup packet is sent (which is after the connections has died.

PBoolean IAX2EndPoint::ConnectionForFrameIsAlive | ( | IAX2Frame * | f | ) |

It is possible that a retransmitted frame has been in the transmit queue, and while sitting there that frames sending connection has died. Thus, prior to transmission, call tis method.

Returns:
  True if a connection (which matches this Frame ) can be found.

void IAX2EndPoint::CopyLocalMediaFormats | ( | OpalMediaFormatList & | list | ) |

Copy to the supplied OpalMediaList the media formats we support

virtual IAX2Connection* IAX2EndPoint::CreateConnection | ( | OpalCall & | call,
|  | const PString & | token,
|  | void * | userData,
|  | const PString & | remoteParty,
|  | const PString & | remotePartyName = `PString::Empty()` |
| ) |  |  | `[virtual]`

Create a connection for the IAX endpoint. The default implementation is to create a IAX2Connection.

Parameters:

  token | Owner of connection
  userData | token used to identify connection
  remoteParty | User data for connection
  remotePartyName | Url to call or is calling. Name to call or is calling.

static PStringArray IAX2EndPoint::DissectRemoteParty | ( | const PString & | other | ) | `[static]`

Given a remote party name of the format:

[proto:][alias@][transport$]address[/extension]

pull the string apart and get the components. The compoents are stored in a PStringList, indexed by the enum RemoteAddressFields

PBoolean IAX2EndPoint::EthernetFramesToBeProcessed | ( |  | ) | `[inline]`

Report if there are frames (from the ethernet) waiting to be processed

void IAX2EndPoint::GetCodecLengths | ( | PINDEX | src,
|  | PINDEX & | compressedBytes,
|  | PINDEX & | duration |
| ) |  |  |

Get the frame size (bytes) and frame duration (ms) for compressed data from this codec

virtual WORD IAX2EndPoint::GetDefaultSignalPort | ( |  | ) | const`[virtual]`

Get the default signal port for this endpoint.

Reimplemented from OpalEndPoint.

virtual PString IAX2EndPoint::GetDefaultTransport | ( |  | ) | const`[virtual]`

Get the default transports for the endpoint type. Overrides the default behaviour to return udp and tcp.

Reimplemented from OpalEndPoint.

PString IAX2EndPoint::GetLocalNumber | ( |  | ) | `[inline]`

Report the number used by the computer running this program

PString IAX2EndPoint::GetLocalUserName | ( |  | ) | `[inline]`

Report the local username

virtual OpalMediaFormatList IAX2EndPoint::GetMediaFormats | ( |  | ) | const`[virtual]`

Get the data formats this endpoint is capable of operating. This provides a list of media data format names that may be used by an OpalMediaStream may be created by a connection from this endpoint.

Note that a specific connection may not actually support all of the media formats returned here, but should return no more.

The default behaviour is pure.

Implements OpalEndPoint.

PINDEX IAX2EndPoint::GetOutSequenceNumberForStatusQuery | ( |  | ) |

Get out sequence number to use on status query frames

PString& IAX2EndPoint::GetPassword | ( |  | ) | `[inline]`

Report the password

PINDEX IAX2EndPoint::GetPreferredCodec | ( | OpalMediaFormatList & | list | ) |

Return the bitmask which specifies the preferred codec

PINDEX IAX2EndPoint::GetRegistrationsCount | ( |  | ) |

Get the number of accounts that are being registered

PINDEX IAX2EndPoint::GetSupportedCodecs | ( | OpalMediaFormatList & | list | ) |

Return the bitmask which specifies the possible codecs we support

virtual void IAX2EndPoint::IncomingEthernetFrame | ( | IAX2Frame * | frame | ) | `[virtual]`

Handle a received IAX frame. This may be a mini frame or full frame

PBoolean IAX2EndPoint::Initialise | ( |  | ) |

Setup the Endpoint internval variables, which is called at program startup.

PBoolean IAX2EndPoint::InitialisedOK | ( |  | ) | `[inline]`

Report if this iax2 endpoint class is correctly initialised

PBoolean IAX2EndPoint::IsRegistered | ( | const PString & | host,
|  | const PString & | username |
| ) |  |  |

Check if an account is registered or being registered

WORD IAX2EndPoint::ListenPortNumber | ( |  | ) | `[inline]`

Report the port in use for IAX calls

virtual PSafePtr<OpalConnection> IAX2EndPoint::MakeConnection | ( | OpalCall & | call,
|  | const PString & | party,
|  | void * | userData = `NULL`,
|  | unsigned int | options = `0`,
|  | OpalConnection::StringOptions * | stringOptions = `NULL` |
| ) |  |  | `[virtual]`

Set up a connection to a remote party. This is called from the OpalManager::MakeConnection() function once it has determined that this is the endpoint for the protocol.

The general form for this party parameter is:

[iax2:]{username@][transport$]address[/extension][+context]

where the various fields will have meanings specific to the endpoint type. For example, with H.323 it could be "h323:Fred@site.com" which indicates a user Fred at gatekeeper size.com. Whereas for the PSTN endpoint it could be "pstn:5551234" which is to call 5551234 on the first available PSTN line.

The proto field is optional when passed to a specific endpoint. If it is present, however, it must agree with the endpoints protocol name or false is returned.

This function usually returns almost immediately with the connection continuing to occur in a new background thread.

If false is returned then the connection could not be established. For example if a PSTN endpoint is used and the assiciated line is engaged then it may return immediately. Returning a non-NULL value does not mean that the connection will succeed, only that an attempt is being made.

The default behaviour is pure.

Parameters:

  call | Owner of connection
  party | Remote party to call
  userData | Arbitrary data to pass to connection
  options | options to pass to connection

Implements OpalEndPoint.

void IAX2EndPoint::NewIncomingConnection | ( | IAX2Frame * | f | ) |

Handle new incoming connection from listener.

A return value of true indicates that the transport object should be deleted by the caller. false indicates that something else (eg the connection) has taken over responsibility for deleting the transport.

Well, that is true of Opal. In iax2, we do all the work of creating a new connection etc. The transport arguement is ignore. In Iax2, this method is void, as no value is returned. Further, in iax2, we process the incoming frame.

Parameters:

  f | Frame carrying the new request.

PINDEX IAX2EndPoint::NextSrcCallNumber | ( | IAX2Processor * | processor | ) |

Request a new source call number, one that is different to all other source call numbers for this program.

Returns:
  P_MAX_INDEX if there is no available call number, or return a unique valid call number.

void IAX2EndPoint::OnEstablished | ( | OpalConnection & | con | ) | `[virtual]`

A call back function whenever a connection is established. This indicates that a connection to an endpoint was established. This usually occurs after OnConnected() and indicates that the connection is both connected and has media flowing.

Reimplemented from OpalEndPoint.

virtual void IAX2EndPoint::OnRegistered | ( | const PString & | host,
|  | const PString & | userName,
|  | PBoolean | isFailure,
|  | RegisteredError | reason = `RegisteredFailureUnknown` |
| ) |  |  | `[virtual]`

This is a call back if an event related to registration occurs. This callback should return as soon as possible.

virtual void IAX2EndPoint::OnReleased | ( | OpalConnection & | connection | ) | `[virtual]`

Called whenever a connection instance is finished being used to manage a call. We trap this callback to remove the connection from this endpoints token table. Once we are done the token table, we then call the generic OpalEndpoint::OnReleased method.

Parameters:

  connection | Connection that was established

Reimplemented from OpalEndPoint.

virtual void IAX2EndPoint::OnUnregistered | ( | const PString & | host,
|  | const PString & | userName,
|  | PBoolean | isFailure,
|  | UnregisteredError | reason = `UnregisteredFailureUnknown` |
| ) |  |  | `[virtual]`

This is a call back if an event related to unregistration occurs. This callback should return as soon as possible. Generally even if a failure occurs when unregistering it should be ignored because it does not matter to much that it couldn't unregister.

PBoolean IAX2EndPoint::ProcessFrameInConnection | ( | IAX2Frame * | f,
|  | const PString & | token |
| ) |  |  | `[protected]`

For the supplied IAX2Frame, pass it to a connection in the connectionsActive structure. We are told the token of the connection that matches this particular frame.

Returns:
  true - this is the normal and expected outcome.

  false - connection not found - say it died immediately before this method was called

PBoolean IAX2EndPoint::ProcessInConnectionTestAll | ( | IAX2Frame * | f | ) | `[protected]`

Take the supplied frame, and compare it with all the existing connections. If any of the existing connections has a matching dest call number, then put this frame to that connection.

Update the token translation dictionary if the supplied frame has a valid connection token.

PBoolean IAX2EndPoint::ProcessInMatchingConnection | ( | IAX2Frame * | f | ) | `[protected]`

For the supplied IAX2Frame, pass it to a connection in the connectionsActive structure. If no matching connection is found, return false;

If a matching connections is found, give the frame to the connection (for the connection to process) and return true;

void IAX2EndPoint::ProcessReceivedEthernetFrames | ( |  | ) |

Pull frames off the incoming list, and pass on to the relevant connection. If no matching connection found, delete the frame. Repeat the process until no frames are left.

void IAX2EndPoint::Register | ( | const PString & | host,
|  | const PString & | username,
|  | const PString & | password = `PString::Empty()`,
|  | PINDEX | requestedRefreshTime = `60` |
| ) |  |  |

Register with a remote iax2 server. The host can either be a hostname or ip address. The password is optional as some servers may not require it to register. The requested refresh time is the time that the registration should be refreshed in seconds. The time must be more than 10 seconds.

void IAX2EndPoint::ReportStoredConnections | ( |  | ) |

Write the token of all connections in the connectionsActive structure to the trace file

void IAX2EndPoint::ReportTransmitterLists | ( | PString & | answer,
|  | bool | getFullReport = `false` |
| ) |  |  |

Report on the frames in the current transmitter class, which are pending transmission

void IAX2EndPoint::SetLocalNumber | ( | PString | newValue | ) |

Set the local (on this host) number to some value

void IAX2EndPoint::SetLocalUserName | ( | PString | newValue | ) |

Set the username to some value

void IAX2EndPoint::SetPassword | ( | PString | newValue | ) |

Set the password to some value

void IAX2EndPoint::StartRinging | ( | PString | remoteCaller | ) |

We have an incoming call. Do we accept ?

void IAX2EndPoint::Unregister | ( | const PString & | host,
|  | const PString & | username |
| ) |  |  |

Unregister from a registrar. This function is synchronous so it will block.

## Field Documentation

PMutex IAX2EndPoint::callNumbLock `[protected]`

lock on access to call numbers variable

int IAX2EndPoint::callnumbs `[protected]`

Number of active calls

PAtomicInteger IAX2EndPoint::callsEstablished `[protected]`

Thread safe counter which keeps track of the calls created by this endpoint. This value is used when giving outgoing calls a unique ID

PTime IAX2EndPoint::callStartTime `[protected]`

Time when a call was started

IAX2IncomingEthernetFrames IAX2EndPoint::incomingFrameHandler `[protected]`

Thread which transfers frames from the Receiver to the appropriate connection. It momentarily locks the connection list, searches through, and then completes the trasnsfer. If need be, this thread will create a new conneciton (to cope with a new incoming call) and add the new connections to the internal list.

OpalMediaFormatList IAX2EndPoint::localMediaFormats `[protected]`

Local copy of the media types we can handle

PString IAX2EndPoint::localNumber `[protected]`

Number, as used by the computer on the host running this program

PString IAX2EndPoint::localUserName `[protected]`

Name of this user, which is used as the IeCallingNumber

PReadWriteMutex IAX2EndPoint::mutexTokenTable `[protected]`

Threading mutex on the variable tokenTable. We can now safely read/write to this table, with the minimum of interference between threads.

IAX2FrameList IAX2EndPoint::packetsReadFromEthernet `[protected]`

List of iax2 packets which has been read from the ethernet, and is to be sent to the matching IAX2Connection

PString IAX2EndPoint::password `[protected]`

Password for this user, which is used when processing an authentication request

IAX2Receiver* IAX2EndPoint::receiver

Pointer to the receiver class, which is always valid

PArrayObjects IAX2EndPoint::regProcessors `[protected]`

An array of register processors. These are created when another class calls register and deleted when another class calls unregister or class destructor is called. This collection must be protected by the regProcessorsMutex

PMutex IAX2EndPoint::regProcessorsMutex `[protected]`

A mutex to protect the registerProcessors collection

PUDPSocket* IAX2EndPoint::sock `[protected]`

The socket on which all data is sent/received.

IAX2SpecialProcessor* IAX2EndPoint::specialPacketHandler `[protected]`

Pointer to the Processor class which handles special packets (eg lagrq) that have no destination call to handle them.

PINDEX IAX2EndPoint::statusQueryCounter `[protected]`

Counter to use for sending on status query frames

PMutex IAX2EndPoint::statusQueryMutex `[protected]`

Mutex for the statusQueryCounter

PStringToString IAX2EndPoint::tokenTable `[protected]`

tokenTable is a hack to allow IAX2 to fit in with one of the demands of the opal library.

Opal demands that at connection setup, we know the unique ID which this call will use.

Since the unique ID is remote ip adress + remote's Source Call number, this is unknown if we are initiating the call. Consequently, this table is needed, as it provides a translation between the initial (or psuedo) token and the token that is later adopted

IAX2Transmit* IAX2EndPoint::transmitter

Pointer to the transmitter class, which is always valid

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

- iax2ep.h