OPAL  Version 3.10.10
OpalEndPoint Class Reference

#include <endpoint.h>

Inheritance diagram for OpalEndPoint:
IAX2EndPoint OpalLineEndPoint OpalLocalEndPoint OpalRTPEndPoint OpalFaxEndPoint OpalIVREndPoint OpalMixerEndPoint OpalPCSSEndPoint H323EndPoint SIPEndPoint

Data Structures

class  ConnectionDict

Public Types

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
PBoolean StartListeners (const PStringArray &interfaces)
PBoolean StartListener (const OpalTransportAddress &iface)
PBoolean StartListener (OpalListener *listener)
virtual PStringArray GetDefaultListeners () const
virtual PString GetDefaultTransport () const
OpalListenerFindListener (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)
 PDECLARE_NOTIFIER (PThread, OpalEndPoint, ListenerCallback)
virtual PBoolean NewIncomingConnection (OpalTransport *transport)
virtual void OnNewConnection (OpalCall &call, OpalConnection &connection)
Connection management
virtual PSafePtr< OpalConnectionMakeConnection (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< OpalConnectionGetConnectionWithLock (const PString &token, PSafetyMode mode=PSafeReadWrite)
template<class ConnClass >
PSafePtr< ConnClass > GetConnectionWithLockAs (const PString &token, PSafetyMode mode=PSafeReadWrite)
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)
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 PBoolean GarbageCollection ()
Member variable access
OpalManagerGetManager () const
const PString & GetPrefixName () const
PBoolean HasAttribute (Attributes opt) const
WORD GetDefaultSignalPort () const
const OpalProductInfoGetProductInfo () 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)
unsigned GetInitialBandwidth () const
void SetInitialBandwidth (unsigned 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

OpalConnectionAddConnection (OpalConnection *connection)

Protected Attributes

OpalManagermanager
PCaselessString prefixName
unsigned attributeBits
WORD defaultSignalPort
PINDEX m_maxSizeUDP
OpalProductInfo productInfo
PString defaultLocalPartyName
PString defaultDisplayName
unsigned initialBandwidth
OpalConnection::StringOptions m_defaultStringOptions
OpalConnection::SendUserInputModes defaultSendUserInputMode
OpalListenerList listeners
OpalEndPoint::ConnectionDict connectionsActive
PMutex inUseFlag

Friends

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

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

Enumerator:
CanTerminateCall 
SupportsE164 

Constructor & Destructor Documentation

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

Create a new endpoint.

Parameters
managerManager of all endpoints.
prefixPrefix for URL style address strings
attributesBit 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
localMedia formats a local ones to be presented to remote
connectionConnection that is about to use formats
mediaFormatsMedia 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
reasonReason for call clearing
waitFlag 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
tokenToken for identifying connection
reasonReason for call clearing
syncSync 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
tokenToken for identifying connection
reasonReason for call clearing
syncSync 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
connectionConnection needing created video device
mediaFormatMedia format for stream
deviceCreated device
autoDeleteFlag 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
connectionConnection needing created video device
mediaFormatMedia format for stream
previewFlag indicating is a preview output
deviceCreated device
autoDeleteFlag for auto delete device
virtual void OpalEndPoint::DestroyConnection ( OpalConnection connection)
virtual

Destroy the connection.

Parameters
connectionConnection to destroy
OpalListener* OpalEndPoint::FindListener ( const OpalTransportAddress iface)

Find a listener given the transport address.

Parameters
ifaceAddress 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
protoProtocol to findlistener, e.g "tcp" or "udp"
addrAddress 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, and SIPEndPoint.

PStringList OpalEndPoint::GetAllConnections ( )

Get all calls current on the endpoint.

PINDEX OpalEndPoint::GetConnectionCount ( ) const
inline

Get calls count on the endpoint

References connectionsActive.

PSafePtr<OpalConnection> OpalEndPoint::GetConnectionWithLock ( const PString &  token,
PSafetyMode  mode = PSafeReadWrite 
)
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().

Parameters
tokenToken to identify connection
modeLocking mode

References connectionsActive.

Referenced by GetConnectionWithLockAs(), OpalIVREndPoint::GetIVRConnectionWithLock(), and OpalLineEndPoint::GetLIDConnectionWithLock().

template<class ConnClass >
PSafePtr<ConnClass> OpalEndPoint::GetConnectionWithLockAs ( const PString &  token,
PSafetyMode  mode = PSafeReadWrite 
)
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
tokenToken to identify connection
modeLocking mode

References OpalManager::FindCallWithLock(), GetConnectionWithLock(), and manager.

const PString& OpalEndPoint::GetDefaultDisplayName ( ) const
inline

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

References defaultDisplayName.

virtual PStringArray OpalEndPoint::GetDefaultListeners ( ) const
virtual

Get the default listeners for the endpoint type. Default behaviour returns empty list if defaultSignalPort is zero, else one entry using tcp and INADDR_ANY, eg tcp$*:1720

const PString& OpalEndPoint::GetDefaultLocalPartyName ( ) const
inline

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

References defaultLocalPartyName.

WORD OpalEndPoint::GetDefaultSignalPort ( ) const
inline

Get the default signal port for this endpoint.

References defaultSignalPort.

const OpalConnection::StringOptions& OpalEndPoint::GetDefaultStringOptions ( ) const
inline

Get the default options for created connections.

References m_defaultStringOptions.

virtual PString OpalEndPoint::GetDefaultTransport ( ) const
virtual

Get comma separated list of transport protocols to create if no explicit listeners started.

Reimplemented in H323EndPoint, and SIPEndPoint.

unsigned OpalEndPoint::GetInitialBandwidth ( ) const
inline

Get the initial bandwidth parameter.

Reimplemented in H323EndPoint.

References initialBandwidth.

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

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

Parameters
excludeLocalHostFlag to exclude 127.0.0.1
associatedTransportAssociated transport for precedence and translation
const OpalListenerList& OpalEndPoint::GetListeners ( ) const
inline

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

References listeners.

OpalManager& OpalEndPoint::GetManager ( ) const
inline

Get the manager for this endpoint.

References manager.

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 OpalMixerEndPoint, IAX2EndPoint, OpalLineEndPoint, OpalIVREndPoint, OpalFaxEndPoint, and OpalLocalEndPoint.

const PString& OpalEndPoint::GetPrefixName ( ) const
inline

Get the protocol prefix name for the endpoint.

References prefixName.

const OpalProductInfo& OpalEndPoint::GetProductInfo ( ) const
inline

Get the product info for all endpoints.

References productInfo.

OpalConnection::SendUserInputModes OpalEndPoint::GetSendUserInputMode ( ) const
inline

Get the default mode for sending User Input Indications.

References defaultSendUserInputMode.

PBoolean OpalEndPoint::HasAttribute ( Attributes  opt) const
inline

Get an indication of if this endpoint has particular option.

References attributeBits.

virtual PBoolean OpalEndPoint::HasConnection ( const PString &  token)
virtual

Determine if a connection is active.

Parameters
tokenToken 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
callOwner of connection
partyRemote party to call
userDataArbitrary data to pass to connection
optionsOptions bit mask to pass to conneciton
stringOptionsOptions to pass to connection

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

virtual PBoolean OpalEndPoint::Message ( const PString &  to,
const PString &  body 
)
virtual

Send text message

virtual PBoolean OpalEndPoint::Message ( const PURL &  to,
const PString &  type,
const PString &  body,
PURL &  from,
PString &  conversationId 
)
virtual
virtual PBoolean OpalEndPoint::Message ( OpalIM Message)
virtual

Reimplemented in SIPEndPoint.

virtual PBoolean OpalEndPoint::NewIncomingConnection ( OpalTransport transport)
virtual

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.

The default behaviour just returns true.

Parameters
transportTransport connection came in on

Reimplemented in H323EndPoint, IAX2EndPoint, and SIPEndPoint.

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
connectionConnection 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
connectionconnection that is being answered
callercaller

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
streamMedia stream being closed
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
connectionConnection 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
connectionConnection 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
connectionConnection that was held
remotePartyThe new remote party
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
connectionConnection that was held/retrieved
fromRemoteIndicates remote has held local connection
onHoldIndicates have just been held/retrieved.
virtual void OpalEndPoint::OnHold ( OpalConnection connection)
virtual
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
connectionConnection that is calling
optionsoptions for new connection (can't use default value as overrides will fail)
stringOptionsOptions 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
partyName of party MWI is for
typeType of message that is waiting
extraInfoAddition 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
callCall that owns the newly created connection.
connectionNew 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
connectionConnection that owns the media stream
streamNew 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
connectionConnection 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
connectionConnection 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
connectionConnection being transferred.
infoInformation 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
connectionConnection input has come from
valueString 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
connectionConnection input has come from
toneTone received
durationDuration of tone
OpalEndPoint::PDECLARE_NOTIFIER ( PThread  ,
OpalEndPoint  ,
ListenerCallback   
)

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
strmStream 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
connectionConnection to read input from
terminatorsCharacters that can terminte input
lastDigitTimeoutTimeout on last digit in string
firstDigitTimeoutTimeout 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
listenerTransport dependent listener.
void OpalEndPoint::SetDefaultDisplayName ( const PString &  name)
inline

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

References defaultDisplayName.

virtual void OpalEndPoint::SetDefaultLocalPartyName ( const PString &  name)
inlinevirtual

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

Parameters
nameName for local party

Reimplemented in H323EndPoint.

References defaultLocalPartyName.

void OpalEndPoint::SetDefaultStringOption ( const PCaselessString &  key,
const PString &  data 
)
inline

Set the default option for created connections.

References m_defaultStringOptions.

void OpalEndPoint::SetDefaultStringOptions ( const OpalConnection::StringOptions opts)
inline

Set the default options for created connections.

References m_defaultStringOptions.

void OpalEndPoint::SetInitialBandwidth ( unsigned  bandwidth)
inline

Get the initial bandwidth parameter.

Reimplemented in H323EndPoint.

References initialBandwidth.

void OpalEndPoint::SetProductInfo ( const OpalProductInfo info)
inline

Set the product info for all endpoints.

References productInfo.

void OpalEndPoint::SetSendUserInputMode ( OpalConnection::SendUserInputModes  mode)
inline

Set the default mode for sending User Input Indications.

References defaultSendUserInputMode.

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, and SIPEndPoint.

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
ifaceAddress of interface to listen on.
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
listenerTransport dependent listener.
PBoolean OpalEndPoint::StartListeners ( const PStringArray &  interfaces)

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

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
interfacesAddress of interface to listen on.
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
ifaceAddress of interface we may be listening on.

Friends And Related Function Documentation

void OpalConnection::Release ( CallEndReason  ,
bool   
)
friend

Field Documentation

unsigned OpalEndPoint::attributeBits
protected

Referenced by HasAttribute().

OpalEndPoint::ConnectionDict OpalEndPoint::connectionsActive
protected
PString OpalEndPoint::defaultDisplayName
protected
PString OpalEndPoint::defaultLocalPartyName
protected
OpalConnection::SendUserInputModes OpalEndPoint::defaultSendUserInputMode
protected
WORD OpalEndPoint::defaultSignalPort
protected

Referenced by GetDefaultSignalPort().

unsigned OpalEndPoint::initialBandwidth
protected
PMutex OpalEndPoint::inUseFlag
protected
OpalListenerList OpalEndPoint::listeners
protected

Referenced by GetListeners().

OpalConnection::StringOptions OpalEndPoint::m_defaultStringOptions
protected
PINDEX OpalEndPoint::m_maxSizeUDP
protected
PCaselessString OpalEndPoint::prefixName
protected

Referenced by GetPrefixName().

OpalProductInfo OpalEndPoint::productInfo
protected

Referenced by GetProductInfo(), and SetProductInfo().


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