# OpalEndPoint Class Reference

`#include <endpoint.h>`

Inheritance diagram for OpalEndPoint:

[legend]
Collaboration diagram for OpalEndPoint:
[legend]

## Public Types

| CanTerminateCall = 1
| SupportsE164 = 2
enum | Attributes { CanTerminateCall = 1, SupportsE164 = 2 }

## Public Member Functions

Construction
| OpalEndPoint (OpalManager &manager, const PCaselessString &prefix, unsigned attributes)
| ~OpalEndPoint ()
virtual void | ShutDown ()
Overrides from PObject
void | PrintOn (ostream &strm) const
Listeners management
bool | StartListeners (const PStringArray &interfaces, bool add=true)
PBoolean | StartListener (const OpalTransportAddress &iface)
PBoolean | StartListener (OpalListener *listener)
virtual PStringArray | GetDefaultListeners () const
virtual PString | GetDefaultTransport () const
virtual WORD | GetDefaultSignalPort () const
OpalListener * | FindListener (const OpalTransportAddress &iface)
bool | FindListenerForProtocol (const char *proto, OpalTransportAddress &addr)
PBoolean | StopListener (const OpalTransportAddress &iface)
PBoolean | RemoveListener (OpalListener *listener)
OpalTransportAddressArray | GetInterfaceAddresses (PBoolean excludeLocalHost=true, const OpalTransport *associatedTransport=NULL) const
| PDECLARE_AcceptHandlerNotifier (OpalEndPoint, NewIncomingConnection)
virtual void | OnNewConnection (OpalCall &call, OpalConnection &connection)
Connection management
virtual PSafePtr< OpalConnection > | MakeConnection (OpalCall &call, const PString &party, void *userData=NULL, unsigned int options=0, OpalConnection::StringOptions *stringOptions=NULL)=0
virtual PBoolean | OnSetUpConnection (OpalConnection &connection)
virtual PBoolean | OnIncomingConnection (OpalConnection &connection, unsigned options, OpalConnection::StringOptions *stringOptions)
virtual void | OnProceeding (OpalConnection &connection)
virtual void | OnAlerting (OpalConnection &connection)
virtual OpalConnection::AnswerCallResponse | OnAnswerCall (OpalConnection &connection, const PString &caller)
virtual void | OnConnected (OpalConnection &connection)
virtual void | OnEstablished (OpalConnection &connection)
virtual void | OnReleased (OpalConnection &connection)
virtual void | OnHold (OpalConnection &connection, bool fromRemote, bool onHold)
virtual void | OnHold (OpalConnection &connection)
virtual PBoolean | OnForwarded (OpalConnection &connection, const PString &remoteParty)
virtual bool | OnTransferNotify (OpalConnection &connection, const PStringToString &info)
virtual PBoolean | ClearCall (const PString &token, OpalConnection::CallEndReason reason=OpalConnection::EndedByLocalUser, PSyncPoint *sync=NULL)
virtual PBoolean | ClearCallSynchronous (const PString &token, OpalConnection::CallEndReason reason=OpalConnection::EndedByLocalUser, PSyncPoint *sync=NULL)
virtual void | ClearAllCalls (OpalConnection::CallEndReason reason=OpalConnection::EndedByLocalUser, PBoolean wait=true)
PSafePtr< OpalConnection > | GetConnectionWithLock (const PString &token, PSafetyMode mode=PSafeReadWrite) const
template<class ConnClass>
PSafePtr< ConnClass > | GetConnectionWithLockAs (const PString &token, PSafetyMode mode=PSafeReadWrite) const
PStringList | GetAllConnections ()
PINDEX | GetConnectionCount () const
virtual PBoolean | HasConnection (const PString &token)
virtual void | DestroyConnection (OpalConnection *connection)
Media Streams management
virtual OpalMediaFormatList | GetMediaFormats () const =0
virtual void | AdjustMediaFormats (bool local, const OpalConnection &connection, OpalMediaFormatList &mediaFormats) const
virtual PBoolean | OnOpenMediaStream (OpalConnection &connection, OpalMediaStream &stream)
virtual void | OnClosedMediaStream (const OpalMediaStream &stream)
void | SetMediaCryptoSuites (const PStringArray &security)
PStringArray | GetMediaCryptoSuites () const
virtual PStringArray | GetAllMediaCryptoSuites () const
virtual PBoolean | CreateVideoInputDevice (const OpalConnection &connection, const OpalMediaFormat &mediaFormat, PVideoInputDevice *&device, PBoolean &autoDelete)
virtual PBoolean | CreateVideoOutputDevice (const OpalConnection &connection, const OpalMediaFormat &mediaFormat, PBoolean preview, PVideoOutputDevice *&device, PBoolean &autoDelete)
User indications
virtual void | OnUserInputString (OpalConnection &connection, const PString &value)
virtual void | OnUserInputTone (OpalConnection &connection, char tone, int duration)
virtual PString | ReadUserInput (OpalConnection &connection, const char *terminators="#\r\n", unsigned lastDigitTimeout=4, unsigned firstDigitTimeout=30)
Instant Messaging
virtual PBoolean | Message (const PString &to, const PString &body)
virtual PBoolean | Message (const PURL &to, const PString &type, const PString &body, PURL &from, PString &conversationId)
virtual PBoolean | Message (OpalIM &Message)
virtual void | OnMessageReceived (const OpalIM &message)
Other services
virtual void | OnMWIReceived (const PString &party, OpalManager::MessageWaitingType type, const PString &extraInfo)
virtual bool | GetConferenceStates (OpalConferenceStates &states, const PString &name=PString::Empty()) const
virtual void | OnConferenceStatusChanged (OpalEndPoint &endpoint, const PString &uri, OpalConferenceState::ChangeType change)
virtual PStringList | GetNetworkURIs (const PString &name) const
virtual PBoolean | GarbageCollection ()
Member variable access
OpalManager & | GetManager () const
const PString & | GetPrefixName () const
PBoolean | HasAttribute (Attributes opt) const
const OpalProductInfo & | GetProductInfo () const
void | SetProductInfo (const OpalProductInfo &info)
const PString & | GetDefaultLocalPartyName () const
virtual void | SetDefaultLocalPartyName (const PString &name)
const PString & | GetDefaultDisplayName () const
void | SetDefaultDisplayName (const PString &name)
OpalBandwidth | GetInitialBandwidth (OpalBandwidth::Direction dir) const
void | SetInitialBandwidth (OpalBandwidth::Direction dir, OpalBandwidth bandwidth)
const OpalListenerList & | GetListeners () const
const OpalConnection::StringOptions & | GetDefaultStringOptions () const
void | SetDefaultStringOptions (const OpalConnection::StringOptions &opts)
void | SetDefaultStringOption (const PCaselessString &key, const PString &data)
OpalConnection::SendUserInputModes | GetSendUserInputMode () const
void | SetSendUserInputMode (OpalConnection::SendUserInputModes mode)

## Protected Member Functions

OpalConnection * | AddConnection (OpalConnection *connection)

## Protected Attributes

OpalManager & | manager
PCaselessString | prefixName
unsigned | attributeBits
PINDEX | m_maxSizeUDP
OpalProductInfo | productInfo
PString | defaultLocalPartyName
PString | defaultDisplayName
PStringArray | m_mediaCryptoSuites
OpalBandwidth | m_initialRxBandwidth
OpalBandwidth | m_initialTxBandwidth
OpalConnection::StringOptions | m_defaultStringOptions
OpalConnection::SendUserInputModes | defaultSendUserInputMode
OpalListenerList | listeners
OpalEndPoint::ConnectionDict | connectionsActive

## Friends

void | OpalManager::GarbageCollection ()
void | OpalConnection::Release (CallEndReason, bool)

## Data Structures

class | ConnectionDict

## Detailed Description

This class describes an endpoint base class. Each protocol (or psuedo-protocol) would create a descendant off this class to manage its particular subsystem. Typically this would involve listening for incoming connections and being able to set up outgoing connections. Depending on exact semantics it may need to spawn many threads to achieve this.

An endpoint will also have a default set of media data formats that it can support. Connections created by it would initially have the same set, but according to the semantics of the underlying protocol may end up using a different set.

Various call backs are provided for points in the connection management. As a rule these are passed straight on to the OpalManager for processing. An application may create descendants off this class' subclasses, eg H323EndPoint, to modify or monitor its behaviour but it does not have to do so as all basic operations are passed to the OpalManager so only that class need be subclassed.

## Member Enumeration Documentation

enum OpalEndPoint::Attributes

Enumerator:

  CanTerminateCall |
  SupportsE164 |

## Constructor & Destructor Documentation

OpalEndPoint::OpalEndPoint | ( | OpalManager & | manager,
|  | const PCaselessString & | prefix,
|  | unsigned | attributes |
| ) |  |  |

Create a new endpoint.

Parameters:

  manager | Manager of all endpoints.
  prefix | Prefix for URL style address strings
  attributes | Bit mask of attributes endpoint has

OpalEndPoint::~OpalEndPoint | ( |  | ) |

Destroy the endpoint.

## Member Function Documentation

OpalConnection* OpalEndPoint::AddConnection | ( | OpalConnection * | connection | ) | `[protected]`

virtual void OpalEndPoint::AdjustMediaFormats | ( | bool | local,
|  | const OpalConnection & | connection,
|  | OpalMediaFormatList & | mediaFormats |
| ) |  |  | const`[virtual]`

Adjust media formats available on a connection. This is called by a connection after it has called OpalCall::GetMediaFormats() to get all media formats that it can use so that an application may remove or reorder the media formats before they are used to open media streams.

The default behaviour calls the OpalManager function of the same name.

Parameters:

  local | Media formats a local ones to be presented to remote
  connection | Connection that is about to use formats
  mediaFormats | Media formats to use

virtual void OpalEndPoint::ClearAllCalls | ( | OpalConnection::CallEndReason | reason = `OpalConnection::EndedByLocalUser`,
|  | PBoolean | wait = `true` |
| ) |  |  | `[virtual]`

Clear all current connections. This hangs up all the connections to remote endpoints. The wait parameter is used to wait for all the calls to be cleared and their memory usage cleaned up before returning. This is typically used in the destructor for your descendant of H323EndPoint.

Parameters:

  reason | Reason for call clearing
  wait | Flag for wait for calls to e cleared.

virtual PBoolean OpalEndPoint::ClearCall | ( | const PString & | token,
|  | OpalConnection::CallEndReason | reason = `OpalConnection::EndedByLocalUser`,
|  | PSyncPoint * | sync = `NULL` |
| ) |  |  | `[virtual]`

Clear a call. This finds the call by using the token then calls the OpalCall::Clear() function on it. All connections are released, and the conenctions and call disposed of. Note that this function returns quickly and the disposal happens at some later time by a background thread. This it is safe to call this function from anywhere.

If `sync` is not NULL then it is signalled when the calls are cleared.

Parameters:

  token | Token for identifying connection
  reason | Reason for call clearing
  sync | Sync point to wait on.

virtual PBoolean OpalEndPoint::ClearCallSynchronous | ( | const PString & | token,
|  | OpalConnection::CallEndReason | reason = `OpalConnection::EndedByLocalUser`,
|  | PSyncPoint * | sync = `NULL` |
| ) |  |  | `[virtual]`

Clear a current connection. This hangs up the connection to a remote endpoint. Note that this function is always synchronous. If `sync` is NULL then a local PSyncPoint is used.

Parameters:

  token | Token for identifying connection
  reason | Reason for call clearing
  sync | Sync point to wait on.

virtual PBoolean OpalEndPoint::CreateVideoInputDevice | ( | const OpalConnection & | connection,
|  | const OpalMediaFormat & | mediaFormat,
|  | PVideoInputDevice *& | device,
|  | PBoolean & | autoDelete |
| ) |  |  | `[virtual]`

Create an PVideoInputDevice for a source media stream.

Parameters:

  connection | Connection needing created video device
  mediaFormat | Media format for stream
  device | Created device
  autoDelete | Flag for auto delete device

virtual PBoolean OpalEndPoint::CreateVideoOutputDevice | ( | const OpalConnection & | connection,
|  | const OpalMediaFormat & | mediaFormat,
|  | PBoolean | preview,
|  | PVideoOutputDevice *& | device,
|  | PBoolean & | autoDelete |
| ) |  |  | `[virtual]`

Create an PVideoOutputDevice for a sink media stream or the preview display for a source media stream.

Parameters:

  connection | Connection needing created video device
  mediaFormat | Media format for stream
  preview | Flag indicating is a preview output
  device | Created device
  autoDelete | Flag for auto delete device

virtual void OpalEndPoint::DestroyConnection | ( | OpalConnection * | connection | ) | `[virtual]`

Destroy the connection.

Parameters:

  connection | Connection to destroy

OpalListener* OpalEndPoint::FindListener | ( | const OpalTransportAddress & | iface | ) |

Find a listener given the transport address.

Parameters:

  iface | Address of interface we may be listening on.

bool OpalEndPoint::FindListenerForProtocol | ( | const char * | proto,
|  | OpalTransportAddress & | addr |
| ) |  |  |

Find a listener that is compatible with the specified protocol

Parameters:

  proto | Protocol to findlistener, e.g "tcp" or "udp"
  addr | Address of listner interface

virtual PBoolean OpalEndPoint::GarbageCollection | ( |  | ) | `[virtual]`

Execute garbage collection for endpoint. Returns true if all garbage has been collected. Default behaviour deletes the objects in the connectionsActive list.

Reimplemented in OpalMixerEndPoint, OpalIMEndPoint, and SIPEndPoint.

PStringList OpalEndPoint::GetAllConnections | ( |  | ) |

Get all calls current on the endpoint.

virtual PStringArray OpalEndPoint::GetAllMediaCryptoSuites | ( |  | ) | const`[virtual]`

Get all possible media security methods for this endpoint type. Note this will always return "Clear" as the first entry.

virtual bool OpalEndPoint::GetConferenceStates | ( | OpalConferenceStates & | states,
|  | const PString & | name = `PString::Empty()` |
| ) |  |  | const`[virtual]`

Get conference state information for all nodes. This obtains the state of one or more conferences managed by this endpoint. If this endpoint does not do conferencing, then false is returned.

The `name` parameter may be one of the aliases for the conference, or the internal URI for the conference. An empty string indicates all active conferences are to be returned.

Note that if the `name` does not match an active conference, true is still returned, but the states list will be empty.

The default behaviour returns false indicating this is not a conferencing endpoint.

Parameters:

  states | List of conference states
  name | Name for specific node, empty string is all

Reimplemented in OpalMixerEndPoint.

PINDEX OpalEndPoint::GetConnectionCount | ( |  | ) | const`[inline]`

Get calls count on the endpoint

PSafePtr<OpalConnection> OpalEndPoint::GetConnectionWithLock | ( | const PString & | token,
|  | PSafetyMode | mode = `PSafeReadWrite` |
| ) |  |  | const

Find a connection that uses the specified token. This searches the endpoint for the connection that is identified by the connection token as provided by functions such as MakeConnection().

The `token` string may also be the call token that identifies the OpalCall instance. The first connection in that call that has this endpoint as it's endpoint is returned.

Finally, the `token` string may also be of the form prefix:name, e.g. ivr:fred, and the GetLocalPartyName() is used to locate the connection.

Parameters:

  token | Token to identify connection
  mode | Locking mode

template<class ConnClass>

PSafePtr<ConnClass> OpalEndPoint::GetConnectionWithLockAs | ( | const PString & | token,
|  | PSafetyMode | mode = `PSafeReadWrite` |
| ) |  |  | const`[inline]`

Find a connection that uses the specified token. This searches the endpoint for the connection that contains the token as provided by functions such as MakeConnection(). If not then it attempts to use the token as a OpalCall token and find a connection of the same class.

Parameters:

  token | Token to identify connection
  mode | Locking mode

const PString& OpalEndPoint::GetDefaultDisplayName | ( |  | ) | const`[inline]`

Get the default local display name for all connections on this endpoint.

virtual PStringArray OpalEndPoint::GetDefaultListeners | ( |  | ) | const`[virtual]`

Get the default listeners for the endpoint type. Default behaviour uses GetDefaultTransport() to produce a list of listener addresses based on IPv4 and IPv6 versions of INADDR_ANY.

const PString& OpalEndPoint::GetDefaultLocalPartyName | ( |  | ) | const`[inline]`

Get the default local party name for all connections on this endpoint.

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

Get the default signal port for this endpoint.

Reimplemented in H323EndPoint, IAX2EndPoint, and SIPEndPoint.

const OpalConnection::StringOptions& OpalEndPoint::GetDefaultStringOptions | ( |  | ) | const`[inline]`

Get the default options for created connections.

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

Get comma separated list of transport protocols to create if no explicit listeners started. Transport protocols are as per OpalTransportAddress, e.g. "udp$". It may also have a ":port" after it if that transport type does not use the value from GetDefaultSignalPort().

Reimplemented in H323EndPoint, IAX2EndPoint, and SIPEndPoint.

OpalBandwidth OpalEndPoint::GetInitialBandwidth | ( | OpalBandwidth::Direction | dir | ) | const

Get the initial bandwidth parameter for a connection.

Parameters:

  dir | Bandwidth direction

OpalTransportAddressArray OpalEndPoint::GetInterfaceAddresses | ( | PBoolean | excludeLocalHost = `true`,
|  | const OpalTransport * | associatedTransport = `NULL` |
| ) |  |  | const

Return a list of the transport addresses for all listeners on this endpoint

Parameters:

  excludeLocalHost | Flag to exclude 127.0.0.1
  associatedTransport | Associated transport for precedence and translation

const OpalListenerList& OpalEndPoint::GetListeners | ( |  | ) | const`[inline]`

Get the set of listeners (incoming call transports) for this endpoint.

OpalManager& OpalEndPoint::GetManager | ( |  | ) | const`[inline]`

Get the manager for this endpoint.

Reimplemented in OpalMixerEndPoint, and OpalIMEndPoint.

PStringArray OpalEndPoint::GetMediaCryptoSuites | ( |  | ) | const`[inline]`

Get media security methods in priority order. Returns an array of names for security methods, e.g. { "Clear", "AES_CM_128_HMAC_SHA1_80", "AES_CM_128_HMAC_SHA1_32" }.

virtual OpalMediaFormatList OpalEndPoint::GetMediaFormats | ( |  | ) | const`[pure 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.

Implemented in OpalIVREndPoint, OpalLocalEndPoint, OpalMixerEndPoint, IAX2EndPoint, OpalIMEndPoint, OpalLineEndPoint, and OpalFaxEndPoint.

virtual PStringList OpalEndPoint::GetNetworkURIs | ( | const PString & | name | ) | const`[virtual]`

Reimplemented in SIPEndPoint.

const PString& OpalEndPoint::GetPrefixName | ( |  | ) | const`[inline]`

Get the protocol prefix name for the endpoint.

const OpalProductInfo& OpalEndPoint::GetProductInfo | ( |  | ) | const`[inline]`

Get the product info for all endpoints.

OpalConnection::SendUserInputModes OpalEndPoint::GetSendUserInputMode | ( |  | ) | const`[inline]`

Get the default mode for sending User Input Indications.

PBoolean OpalEndPoint::HasAttribute | ( | Attributes | opt | ) | const`[inline]`

Get an indication of if this endpoint has particular option.

virtual PBoolean OpalEndPoint::HasConnection | ( | const PString & | token | ) | `[virtual]`

Determine if a connection is active.

Parameters:

  token | Token for identifying connection

virtual PSafePtr<OpalConnection> OpalEndPoint::MakeConnection | ( | OpalCall & | call,
|  | const PString & | party,
|  | void * | userData = `NULL`,
|  | unsigned int | options = `0`,
|  | OpalConnection::StringOptions * | stringOptions = `NULL` |
| ) |  |  | `[pure 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:

[proto:][alias@][transport$]address[:port]

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 bit mask to pass to conneciton
  stringOptions | Options to pass to connection

Implemented in OpalIVREndPoint, OpalLocalEndPoint, H323EndPoint, IAX2EndPoint, OpalIMEndPoint, OpalLineEndPoint, SIPEndPoint, and OpalFaxEndPoint.

virtual PBoolean OpalEndPoint::Message | ( | OpalIM & | Message | ) | `[virtual]`

virtual PBoolean OpalEndPoint::Message | ( | const PURL & | to,
|  | const PString & | type,
|  | const PString & | body,
|  | PURL & | from,
|  | PString & | conversationId |
| ) |  |  | `[virtual]`

virtual PBoolean OpalEndPoint::Message | ( | const PString & | to,
|  | const PString & | body |
| ) |  |  | `[virtual]`

Send text message

virtual void OpalEndPoint::OnAlerting | ( | OpalConnection & | connection | ) | `[virtual]`

Call back for remote party being alerted. This function is called after the connection is informed that the remote endpoint is "ringing". Generally some time after the MakeConnection() function was called, this is function is called.

If false is returned the connection is aborted.

If an application overrides this function, it should generally call the ancestor version for correct operation. An application would typically only intercept this function if it wishes to do some form of logging. For this you can obtain the name of the caller by using the function OpalConnection::GetRemotePartyName().

The default behaviour calls the OpalManager function of the same name.

Parameters:

  connection | Connection that is alerting

virtual OpalConnection::AnswerCallResponse OpalEndPoint::OnAnswerCall | ( | OpalConnection & | connection,
|  | const PString & | caller |
| ) |  |  | `[virtual]`

Call back for answering an incoming call. This function is called after the connection has been acknowledged but before the connection is established

This gives the application time to wait for some event before signalling to the endpoint that the connection is to proceed. For example the user pressing an "Answer call" button.

If AnswerCallDenied is returned the connection is aborted and the connetion specific end call PDU is sent. If AnswerCallNow is returned then the connection proceeding, Finally if AnswerCallPending is returned then the protocol negotiations are paused until the AnsweringCall() function is called.

The default behaviour simply returns AnswerNow.

Parameters:

  connection | connection that is being answered
  caller | caller

Reimplemented in H323EndPoint.

virtual void OpalEndPoint::OnClosedMediaStream | ( | const OpalMediaStream & | stream | ) | `[virtual]`

Call back for closed a media stream.

The default behaviour calls the OpalManager function of the same name.

Parameters:

  stream | Media stream being closed

virtual void OpalEndPoint::OnConferenceStatusChanged | ( | OpalEndPoint & | endpoint,
|  | const PString & | uri,
|  | OpalConferenceState::ChangeType | change |
| ) |  |  | `[virtual]`

Call back when conferencing state information changes. If a conferencing endpoint type detects a change in a conference nodes state, as would be returned by GetConferenceStatus() then this function will be called on all endpoints in the OpalManager.

The `uri` parameter is as is the internal URI for the conference.

Default behaviour does nothing.

Parameters:

  uri | < Endpoint sending state change Internal URI of conference node that changed
  change | Change that occurred

Reimplemented in SIPEndPoint.

virtual void OpalEndPoint::OnConnected | ( | OpalConnection & | connection | ) | `[virtual]`

A call back function whenever a connection is "connected". This indicates that a connection to an endpoint was connected. That is the endpoint received acknowledgement via whatever protocol it uses that the connection may now start media streams.

In the context of H.323 this means that the CONNECT pdu has been received.

The default behaviour calls the OpalManager function of the same name.

Parameters:

  connection | Connection that was established

virtual void OpalEndPoint::OnEstablished | ( | OpalConnection & | connection | ) | `[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.

In the context of H.323 this means that the signalling and control channels are open and the TerminalCapabilitySet and MasterSlave negotiations are complete.

The default behaviour does nothing.

Parameters:

  connection | Connection that was established

Reimplemented in IAX2EndPoint.

virtual PBoolean OpalEndPoint::OnForwarded | ( | OpalConnection & | connection,
|  | const PString & | remoteParty |
| ) |  |  | `[virtual]`

A call back function whenever a connection is forwarded.

The default behaviour does nothing.

Parameters:

  connection | Connection that was held
  remoteParty | The new remote party

virtual void OpalEndPoint::OnHold | ( | OpalConnection & | connection | ) | `[virtual]`

virtual void OpalEndPoint::OnHold | ( | OpalConnection & | connection,
|  | bool | fromRemote,
|  | bool | onHold |
| ) |  |  | `[virtual]`

A call back function whenever a connection is "held" or "retrieved". This indicates that a connection to an endpoint was held, or retrieved, either locally or by the remote endpoint.

The default behaviour calls the OpalManager function of the same name.

Parameters:

  connection | Connection that was held/retrieved
  fromRemote | Indicates remote has held local connection
  onHold | Indicates have just been held/retrieved.

virtual PBoolean OpalEndPoint::OnIncomingConnection | ( | OpalConnection & | connection,
|  | unsigned | options,
|  | OpalConnection::StringOptions * | stringOptions |
| ) |  |  | `[virtual]`

Call back for answering an incoming call. This function is used for an application to control the answering of incoming calls.

If true is returned then the connection continues. If false then the connection is aborted.

Note this function should not block for any length of time. If the decision to answer the call may take some time eg waiting for a user to pick up the phone, then AnswerCallPending or AnswerCallDeferred should be returned.

If an application overrides this function, it should generally call the ancestor version to complete calls. Unless the application completely takes over that responsibility. Generally, an application would only intercept this function if it wishes to do some form of logging. For this you can obtain the name of the caller by using the function OpalConnection::GetRemotePartyName().

The default behaviour calls the OpalManager function of the same name.

Parameters:

  connection | Connection that is calling
  options | options for new connection (can't use default value as overrides will fail)
  stringOptions | Options to pass to connection

virtual void OpalEndPoint::OnMessageReceived | ( | const OpalIM & | message | ) | `[virtual]`

Called when text message received

virtual void OpalEndPoint::OnMWIReceived | ( | const PString & | party,
|  | OpalManager::MessageWaitingType | type,
|  | const PString & | extraInfo |
| ) |  |  | `[virtual]`

Callback called when Message Waiting Indication (MWI) is received. Multiple callbacks may occur with each MessageWaitingType. A `type` of NumMessageWaitingTypes indicates the server is unable to distinguish the message type.

The `extraInfo` parameter is generally of the form "a/b" where a and b unsigned integers representing new and old message count. However, it may be a simple "yes" or "no" if the remote cannot provide a message count.

Parameters:

  party | Name of party MWI is for
  type | Type of message that is waiting
  extraInfo | Addition information on the MWI

virtual void OpalEndPoint::OnNewConnection | ( | OpalCall & | call,
|  | OpalConnection & | connection |
| ) |  |  | `[virtual]`

Call back for a new connection has been constructed. This is called after CreateConnection has returned a new connection. It allows an application to make any custom adjustments to the connection before it begins to process the protocol. behind it.

Parameters:

  call | Call that owns the newly created connection.
  connection | New connection just created

virtual PBoolean OpalEndPoint::OnOpenMediaStream | ( | OpalConnection & | connection,
|  | OpalMediaStream & | stream |
| ) |  |  | `[virtual]`

Call back when opening a media stream. This function is called when a connection has created a new media stream according to the logic of its underlying protocol.

The usual requirement is that media streams are created on all other connections participating in the call and all of the media streams are attached to an instance of an OpalMediaPatch object that will read from one of the media streams passing data to the other media streams.

The default behaviour calls the OpalManager function of the same name.

Parameters:

  connection | Connection that owns the media stream
  stream | New media stream being opened

virtual void OpalEndPoint::OnProceeding | ( | OpalConnection & | connection | ) | `[virtual]`

Call back for remote party is now responsible for completing the call. This function is called when the remote system has been contacted and it has accepted responsibility for completing, or failing, the call. This is distinct from OnAlerting() in that it is not known at this time if anything is ringing. This indication may be used to distinguish between "transport" level error, in which case another host may be tried, and that finalising the call has moved "upstream" and the local system has no more to do but await a result.

If an application overrides this function, it should generally call the ancestor version for correct operation.

The default behaviour calls the OpalManager function of the same name.

Parameters:

  connection | Connection that is proceeeding

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

A call back function whenever a connection is broken. This function can do any internal cleaning up and waiting on background threads that may be using the connection object.

Note that there is not a one to one relationship with the OnEstablishedConnection() function. This function may be called without that function being called. For example if MakeConnection() was used but the call never completed.

Classes that override this function should make sure they call the ancestor version for correct operation.

An application will not typically call this function as it is used by the OpalManager during a release of the connection.

The default behaviour removes the connection from the internal database and calls the OpalManager function of the same name.

Parameters:

  connection | Connection that was established

Reimplemented in IAX2EndPoint, and SIPEndPoint.

virtual PBoolean OpalEndPoint::OnSetUpConnection | ( | OpalConnection & | connection | ) | `[virtual]`

Callback for outgoing connection, it is invoked after OpalLineConnection::SetUpConnection This function allows the application to set up some parameters or to log some messages

virtual bool OpalEndPoint::OnTransferNotify | ( | OpalConnection & | connection,
|  | const PStringToString & | info |
| ) |  |  | `[virtual]`

A call back function to monitor the progress of a transfer. When a transfer operation is initiated, the Transfer() function will generally return immediately and the transfer may take some time. This call back can give an indication to the application of the progress of the transfer. the transfer.

For example in SIP, the OpalCall::Transfer() function will have sent a REFER request to the remote party. The remote party sends us NOTIFY requests about the progress of the REFER request.

An application can now make a decision during the transfer operation to short circuit the sequence, or let it continue. It can also determine if the transfer did not go through, and it should "take back" the call. Note no action is required to "take back" the call other than indicate to the user that they are back on.

A return value of false will immediately disconnect the current call.

The exact format of the `info` parameter is dependent on the protocol being used. As a minimum, it will always have a values info["result"] and info["party"].

The info["party"] indicates the part the `connection` is playing in the transfer. This will be: "A" party being transferred "B" party initiating the transfer of "A" "C" party "A" is being transferred to

The info["result"] will be at least one of the following: "success" Transfer completed successfully (party A or B) "incoming" New call was from a transfer (party C) "started" Transfer operation has started (party A) "progress" Transfer is in progress (party B) "blind" Transfer is blind, no further notification (party B) "error" Transfer could not begin (party B) "failed" Transfer started but did not complete (party A or B)

For SIP, there may be an additional info["state"] containing the NOTIFY subscription state, an info["code"] entry containing the 3 digit code returned in the NOTIFY body and info["Referred-By"] indicating the URI of party B. Other fields may also be present.

The default behaviour calls the OpalManager function of the same name. The default action of that function is to return false, thereby releasing the connection if the info["result"] == "success".

Parameters:

  connection | Connection being transferred.
  info | Information on the transfer

virtual void OpalEndPoint::OnUserInputString | ( | OpalConnection & | connection,
|  | const PString & | value |
| ) |  |  | `[virtual]`

Call back for remote enpoint has sent user input as a string.

The default behaviour calls the OpalManager function of the same name.

Parameters:

  connection | Connection input has come from
  value | String value of indication

virtual void OpalEndPoint::OnUserInputTone | ( | OpalConnection & | connection,
|  | char | tone,
|  | int | duration |
| ) |  |  | `[virtual]`

Call back for remote enpoint has sent user input. If duration is zero then this indicates the beginning of the tone. If duration is non-zero then it indicates the end of the tone output.

The default behaviour calls the OpalManager function of the same name.

Parameters:

  connection | Connection input has come from
  tone | Tone received
  duration | Duration of tone

OpalEndPoint::PDECLARE_AcceptHandlerNotifier | ( | OpalEndPoint | ,
|  | NewIncomingConnection |  |
| ) |  |  |

Handle new incoming connection. This will either create a new connection object or utilise a previously created connection on the same transport address and reference number.

void OpalEndPoint::PrintOn | ( | ostream & | strm | ) | const

Standard stream print function. The PObject class has a << operator defined that calls this function polymorphically.

Parameters:

  strm | Stream to output text representation

virtual PString OpalEndPoint::ReadUserInput | ( | OpalConnection & | connection,
|  | const char * | terminators = `"#\r\n"`,
|  | unsigned | lastDigitTimeout = `4`,
|  | unsigned | firstDigitTimeout = `30` |
| ) |  |  | `[virtual]`

Read a sequence of user indications from connection with timeouts.

Parameters:

  connection | Connection to read input from
  terminators | Characters that can terminte input
  lastDigitTimeout | Timeout on last digit in string
  firstDigitTimeout | Timeout on receiving any digits

PBoolean OpalEndPoint::RemoveListener | ( | OpalListener * | listener | ) |

Remove a listener from the endoint. If the listener parameter is NULL then all listeners are removed.

Parameters:

  listener | Transport dependent listener.

void OpalEndPoint::SetDefaultDisplayName | ( | const PString & | name | ) | `[inline]`

Set the default local display name for all connections on this endpoint.

virtual void OpalEndPoint::SetDefaultLocalPartyName | ( | const PString & | name | ) | `[inline, virtual]`

Set the default local party name for all connections on this endpoint.

Parameters:

  name | Name for local party

Reimplemented in H323EndPoint.

void OpalEndPoint::SetDefaultStringOption | ( | const PCaselessString & | key,
|  | const PString & | data |
| ) |  |  | `[inline]`

Set the default option for created connections.

void OpalEndPoint::SetDefaultStringOptions | ( | const OpalConnection::StringOptions & | opts | ) | `[inline]`

Set the default options for created connections.

void OpalEndPoint::SetInitialBandwidth | ( | OpalBandwidth::Direction | dir,
|  | OpalBandwidth | bandwidth |
| ) |  |  |

Set the initial bandwidth parameter for a connection.

Parameters:

  dir | Bandwidth direction
  bandwidth | New bandwidth

void OpalEndPoint::SetMediaCryptoSuites | ( | const PStringArray & | security | ) |

Set media security methods in priority order. The `security` parameter is an array of names for security methods, e.g. { "Clear", "AES_CM_128_HMAC_SHA1_80", "AES_CM_128_HMAC_SHA1_32" }. Note "Clear" is not compulsory and if absent will mean that a secure media is required or the call will not proceed.

An empty list is assumed to be "Clear".

Parameters:

  security | New security methods to use

void OpalEndPoint::SetProductInfo | ( | const OpalProductInfo & | info | ) | `[inline]`

Set the product info for all endpoints.

void OpalEndPoint::SetSendUserInputMode | ( | OpalConnection::SendUserInputModes | mode | ) | `[inline]`

Set the default mode for sending User Input Indications.

virtual void OpalEndPoint::ShutDown | ( |  | ) | `[virtual]`

Shut down the endpoint, this is called by the OpalManager just before destroying the object and can be handy to make sure some things are stopped before the vtable gets clobbered.

Reimplemented in OpalMixerEndPoint, H323EndPoint, OpalIMEndPoint, and SIPEndPoint.

PBoolean OpalEndPoint::StartListener | ( | OpalListener * | listener | ) |

Add a listener to the endoint. This allows for the automatic creating of incoming call connections. An application should use OnConnectionEstablished() to monitor when calls have arrived and been successfully negotiated.

Parameters:

  listener | Transport dependent listener.

PBoolean OpalEndPoint::StartListener | ( | const OpalTransportAddress & | iface | ) |

Add a listener to the endoint. This allows for the automatic creating of incoming call connections. / If the address is empty then the first entry of GetDefaultListeners() is used.

See OpalTransportAddress for more details on the syntax of an interface definition.

Parameters:

  iface | Address of interface to listen on.

bool OpalEndPoint::StartListeners | ( | const PStringArray & | interfaces,
|  | bool | add = `true` |
| ) |  |  |

Start a set of listeners on the endoint. This allows for the automatic creating of incoming call connections. If the list is empty then GetDefaultListeners() is used.

The `add` parameter indicatest that existing listeners are left running and new ones are added. If false then listeners that are not in the `interfaces` list are stopped. Listeners not already running are started and ones that are already running are untouched.

Note: while the `interfaces` parameter is a string array, each element of the array should be compatible with OpalTransportAddress.

See OpalTransportAddress for more details on the syntax of an interface definition.

Parameters:

  interfaces | Addresses of interfaces to listen on.
  add | Add listeners to existing list

PBoolean OpalEndPoint::StopListener | ( | const OpalTransportAddress & | iface | ) |

Stop a listener given the transport address. Returns true if a listener was on that interface, and was stopped.

Parameters:

  iface | Address of interface we may be listening on.

## Friends And Related Function Documentation

void OpalConnection::Release | ( | CallEndReason | ,
|  | bool |  |
| ) |  |  | `[friend]`

void OpalManager::GarbageCollection | ( |  | ) | `[friend]`

## Field Documentation

unsigned OpalEndPoint::attributeBits `[protected]`

OpalEndPoint::ConnectionDict OpalEndPoint::connectionsActive `[protected]`

PString OpalEndPoint::defaultDisplayName `[protected]`

PString OpalEndPoint::defaultLocalPartyName `[protected]`

OpalConnection::SendUserInputModes OpalEndPoint::defaultSendUserInputMode `[protected]`

OpalListenerList OpalEndPoint::listeners `[protected]`

OpalConnection::StringOptions OpalEndPoint::m_defaultStringOptions `[protected]`

OpalBandwidth OpalEndPoint::m_initialRxBandwidth `[protected]`

OpalBandwidth OpalEndPoint::m_initialTxBandwidth `[protected]`

PINDEX OpalEndPoint::m_maxSizeUDP `[protected]`

PStringArray OpalEndPoint::m_mediaCryptoSuites `[protected]`

OpalManager& OpalEndPoint::manager `[protected]`

PCaselessString OpalEndPoint::prefixName `[protected]`

OpalProductInfo OpalEndPoint::productInfo `[protected]`

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

- endpoint.h