#include <endpoint.h>

Inheritance diagram for OpalEndPoint:

Collaboration diagram for OpalEndPoint:

Data Structures
class	ConnectionDict

Public Member Functions
	P_DECLARE_BITWISE_ENUM (Attributes, 2,(NoAttributes, IsNetworkEndPoint, SupportsE164))

Construction
	OpalEndPoint (OpalManager &manager, const PCaselessString &prefix, Attributes 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 (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 bool	GetMediaTransportAddresses (const OpalConnection &source, const OpalConnection &destination, const OpalMediaType &mediaType, OpalTransportAddressArray &transports) const

virtual PBoolean	OnOpenMediaStream (OpalConnection &connection, OpalMediaStream &stream)

virtual void	OnClosedMediaStream (const OpalMediaStream &stream)

virtual void	OnFailedMediaStream (OpalConnection &connection, bool fromRemote, const PString &reason)

void	SetMediaCryptoSuites (const PStringArray &security)

PStringArray	GetMediaCryptoSuites () const

virtual PStringArray	GetAllMediaCryptoSuites () const

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

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

void	RemoveDefaultStringOption (const PCaselessString &key)

virtual PStringList	GetAvailableStringOptions () const

OpalConnection::SendUserInputModes	GetSendUserInputMode () const

void	SetSendUserInputMode (OpalConnection::SendUserInputModes mode)

Protected Member Functions
OpalConnection *	AddConnection (OpalConnection *connection)

Protected Attributes
OpalManager &	manager

PCaselessString	prefixName

Attributes	m_attributes

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

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.

Constructor & Destructor Documentation

OpalEndPoint::OpalEndPoint	(	OpalManager &	manager,
		const PCaselessString &	prefix,
		Attributes	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 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, SIPEndPoint, H323EndPoint, and OpalIMEndPoint.

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.

Referenced by GetMediaCryptoSuites().

virtual PStringList OpalEndPoint::GetAvailableStringOptions ( ) const

virtual

Get available string option names.

Reimplemented in SIPEndPoint, and H323EndPoint.

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

References connectionsActive.

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

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

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

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

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

References defaultLocalPartyName.

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.

References m_defaultStringOptions.

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 ( const OpalTransport * associatedTransport = NULL ) const

Return the transport addresses for all listeners on this endpoint. If associatedTransport is provided then only listeners that are using the same interface as that trasnprt are returned.

Parameters

associatedTransport Associated 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.

Referenced by OpalMixerEndPoint::GetManager(), OpalPCSSEndPoint::GetVideoDisplayDevice(), OpalPCSSEndPoint::GetVideoGrabberDevice(), and OpalPCSSEndPoint::GetVideoPreviewDevice().

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" }.

References GetAllMediaCryptoSuites(), and m_mediaCryptoSuites.

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, OpalLocalEndPoint, and OpalIMEndPoint.

virtual bool OpalEndPoint::GetMediaTransportAddresses	(	const OpalConnection &	source,
		const OpalConnection &	destination,
		const OpalMediaType &	mediaType,
		OpalTransportAddressArray &	transports
	)		const

virtual

Get transports for the media session on the connection. This is primarily used by the media bypass feature controlled by the OpalManager::GetMediaTransferMode() function. It allows one side of the call to get the transport address of the media on the other side, so it can pass it on, bypassing the local host.

Returns: true if a transport address is available and may be used to pass on to a remote system for direct access.

Parameters

source	Half of call providing media transport addresses
destination	Other half of call needing media transport addresses
mediaType	Media type for session to return information
transports	Information on media session

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.

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.

bool OpalEndPoint::HasAttribute ( Attributes opt ) const

inline

Get an indication of if this endpoint has particular option.

References m_attributes.

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 IAX2EndPoint, H323EndPoint, SIPEndPoint, OpalLocalEndPoint, OpalLineEndPoint, OpalIVREndPoint, and OpalIMEndPoint.

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

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

Reimplemented in OpalConsolePCSSEndPoint.

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 void OpalEndPoint::OnFailedMediaStream	(	OpalConnection &	connection,
		bool	fromRemote,
		const PString &	reason
	)

virtual

Call back for a media stream that failed to open.

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

Parameters

connection	Connection that attempted to open media stream
fromRemote	Flag indicating the attempt to open was from remote
reason	Reason for the open fail

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

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, OpalConsolePCSSEndPoint, H323EndPoint, 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 greater than zero then it indicates the end of the tone output and how long the tone had run.

Note, there is no guarantee a zero value (start tone) will occur. There is also no guarantee this function is called at all, given how the remote may send user indications. For simple, "event" based, user indications the OnUserInputString() should be used. THis function is only for when a more precise representation of the tone, and it's duration, is required.

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::P_DECLARE_BITWISE_ENUM	(	Attributes	,
		2	,
		(NoAttributes, IsNetworkEndPoint, SupportsE164)
	)

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

void OpalEndPoint::RemoveDefaultStringOption ( const PCaselessString & key )

inline

Removet the default option for created connections.

References m_defaultStringOptions.

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.

References defaultDisplayName.

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

inlinevirtual

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

Parameters

name	Name 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	(	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.

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, OpalConsolePCSSEndPoint, H323EndPoint, OpalIMEndPoint, 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

iface Address 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

listener Transport dependent listener.

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