#include <call.h>

Inherits PSafeObject.

Collaboration diagram for OpalCall:

Public Member Functions
bool	StartRecording (const PFilePath &filename, const OpalRecordManager::Options &options=false)

bool	StartRecording (const PDirectory &outputDir, const PString &fileTemplate, const PString &fileType, const OpalRecordManager::Options &options=false)

bool	IsRecording () const

bool	StopRecording ()

virtual bool	OnStartRecording (const PString &streamId, const OpalMediaFormat &format)

virtual void	OnStopRecording (const PString &streamId)

virtual void	OnRecordAudio (const PString &streamId, const RTP_DataFrame &frame)

virtual void	OnRecordVideo (const PString &streamId, const RTP_DataFrame &frame)

void	InternalOnClear ()

void	SetPartyNames ()

Construction
	OpalCall (OpalManager &manager)

	~OpalCall ()

Overrides from PObject
void	PrintOn (ostream &strm) const

Basic operations
PBoolean	IsEstablished () const

virtual void	OnEstablishedCall ()

OpalConnection::CallEndReason	GetCallEndReason () const

PString	GetCallEndReasonText () const

void	SetCallEndReason (OpalConnection::CallEndReason reason)

void	Clear (OpalConnection::CallEndReason reason=OpalConnection::EndedByLocalUser, PSyncPoint *sync=NULL)

virtual void	OnCleared ()

Connection management
virtual void	OnNewConnection (OpalConnection &connection)

virtual PBoolean	OnSetUp (OpalConnection &connection)

virtual void	OnProceeding (OpalConnection &connection)

virtual void	OnAlerting (OpalConnection &connection, bool withMedia)

virtual PBoolean	OnAlerting (OpalConnection &connection)

virtual OpalConnection::AnswerCallResponse	OnAnswerCall (OpalConnection &connection, const PString &caller)

virtual PBoolean	OnConnected (OpalConnection &connection)

virtual PBoolean	OnEstablished (OpalConnection &connection)

virtual void	OnReleased (OpalConnection &connection)

virtual void	OnHold (OpalConnection &connection, bool fromRemote, bool onHold)

PSafePtr< OpalConnection >	GetOtherPartyConnection (const OpalConnection &connection) const

PINDEX	GetConnectionCount () const

PSafePtr< OpalConnection >	GetConnection (PINDEX idx, PSafetyMode mode=PSafeReference)

template<class ConnClass >
PSafePtr< ConnClass >	GetConnectionAs (PINDEX count=0, PSafetyMode mode=PSafeReadWrite)

bool	Hold (bool hold=true)

bool	Retrieve ()

bool	IsOnHold (bool fromRemote=false) const

bool	Transfer (const PString &address, OpalConnection *connection=NULL)

Media management
virtual OpalMediaFormatList	GetMediaFormats (const OpalConnection &connection)

virtual void	AdjustMediaFormats (bool local, const OpalConnection &connection, OpalMediaFormatList &mediaFormats) const

virtual bool	OpenSourceMediaStreams (OpalConnection &connection, const OpalMediaType &mediaType, unsigned sessionID=0, const OpalMediaFormat &preselectedFormat=OpalMediaFormat(), OpalVideoFormat::ContentRole contentRole=OpalVideoFormat::eNoRole, bool transfer=false, bool startPaused=false)

virtual bool	SelectMediaFormats (const OpalMediaType &mediaType, const OpalMediaFormatList &srcFormats, const OpalMediaFormatList &dstFormats, const OpalMediaFormatList &masterFormats, OpalMediaFormat &srcFormat, OpalMediaFormat &dstFormat) const

virtual void	CloseMediaStreams ()

bool	GetStatistics (const OpalMediaType &mediaType, bool fromAparty, OpalMediaStatistics &statistics)
	Get media statistics of the type, received from the specified party. More...

User indications
virtual void	OnUserInputString (OpalConnection &connection, const PString &value)

virtual void	OnUserInputTone (OpalConnection &connection, char tone, int duration)

Member variable access
OpalManager &	GetManager () const

const PString &	GetToken () const

const PString &	GetPartyA () const

const PString &	GetPartyB () const

void	SetPartyB (const PString &b)

const PString &	GetNameA () const

const PString &	GetNameB () const

const PString &	GetIdentityA () const

const PString &	GetIdentityB () const

bool	IsNetworkOriginated () const

const PString &	GetRemoteParty () const

const PString &	GetLocalParty () const

const PString &	GetRemoteName () const

const PString &	GetLocalName () const

const PTime &	GetStartTime () const

const PTime &	GetEstablishedTime () const

Protected Member Functions
bool	EnumerateConnections (PSafePtr< OpalConnection > &connection, PSafetyMode mode, const OpalConnection *skipConnection=NULL) const

friend	OpalConnection::OpalConnection (OpalCall &, OpalEndPoint &, const PString &, unsigned int, OpalConnection::StringOptions *)

friend	OpalConnection::~OpalConnection ()

	P_REMOVE_VIRTUAL_VOID (OnRTPStatistics(const OpalConnection &, const OpalRTPSession &))

Protected Attributes
OpalManager &	m_manager

PString	m_token

PString	m_partyA

PString	m_partyB

PString	m_nameA

PString	m_nameB

PString	m_identityA

PString	m_identityB

bool	m_networkOriginated

PTime	m_startTime

PTime	m_establishedTime

bool	m_isEstablished

bool	m_isClearing

bool	m_handlingHold

atomic< bool >	m_isCleared

OpalConnection::CallEndReason	m_callEndReason

PCriticalSection	m_callEndReasonMutex

std::list< PSyncPoint * >	m_endCallSyncPoint

PSafeArray< OpalConnection >	m_connectionsActive

OpalRecordManager *	m_recordManager

Detailed Description

This class manages a call. A call consists of one or more OpalConnection instances. While these connections may be created elsewhere this class is responsible for their disposal.

An OpalCall could manage (for example) a H323Connection and PCSSConnection instance, which allows the user to use opal in a H.323 application. Alternatively, if OpalCall manages a H323Connection and a SIPConnection instance, the call is being gatewayed from one protocol to another.

In a conference situation, one OpalCall would manage lots of H323Connection/SIPConnection classes.

Constructor & Destructor Documentation

OpalCall::OpalCall ( OpalManager & manager )

Create a new call.

Parameters

manager Manager for the opal system

OpalCall::~OpalCall ( )

Destroy call.

OpalCall::OpalConnection::~OpalConnection ( )

protected

Member Function Documentation

virtual void OpalCall::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

void OpalCall::Clear	(	OpalConnection::CallEndReason	reason = `OpalConnection::EndedByLocalUser`,
		PSyncPoint *	sync = `NULL`
	)

Clear call. This releases all connections currently attached to the call. Note that this function will return quickly as the release and disposal of the connections is done by another thread.

The sync parameter is a PSyncPoint that will be signalled during the destructor for the OpalCall. Note only one thread may do this at a time.

Parameters

reason	Reason for call clearing
sync	Sync point to signal on call destruction

virtual void OpalCall::CloseMediaStreams ( )

virtual

Close the media streams on the connections.

bool OpalCall::EnumerateConnections	(	PSafePtr< OpalConnection > &	connection,
		PSafetyMode	mode,
		const OpalConnection *	skipConnection = `NULL`
	)		const

protected

OpalConnection::CallEndReason OpalCall::GetCallEndReason ( ) const

Get the call clearand reason for this connection shutting down. Note that this function is only generally useful in the OpalEndPoint::OnClearedCall() function. This is due to the connection not being cleared before that, and the object not even existing after that.

If the call is still active then this will return OpalConnection::NumCallEndReasons.

Referenced by GetCallEndReasonText().

PString OpalCall::GetCallEndReasonText ( ) const

inline

Get the reason for this connection shutting down as text.

References GetCallEndReason(), and OpalConnection::GetCallEndReasonText().

PSafePtr<OpalConnection> OpalCall::GetConnection	(	PINDEX	idx,
		PSafetyMode	mode = `PSafeReference`
	)

inline

Get the specified active connection in call.

References m_connectionsActive.

template<class ConnClass >

PSafePtr<ConnClass> OpalCall::GetConnectionAs	(	PINDEX	count = `0`,
		PSafetyMode	mode = `PSafeReadWrite`
	)

inline

Find a connection of the specified class. This searches the call for the Nth connection of the specified class.

References m_connectionsActive.

PINDEX OpalCall::GetConnectionCount ( ) const

inline

Get number of connections in call.

References m_connectionsActive.

const PTime& OpalCall::GetEstablishedTime ( ) const

inline

Get the time the call started.

References m_establishedTime.

const PString& OpalCall::GetIdentityA ( ) const

inline

Get the A party identity for the call. Note this will be available even after the A party connection has been released from the call.

References m_identityA.

const PString& OpalCall::GetIdentityB ( ) const

inline

Get the B party URI for the call. Note this will be available even after the B party connection has been released from the call. Also this will only be the first B party if the object represents a conference call with more that 2 parties.

References m_identityB.

const PString& OpalCall::GetLocalName ( ) const

inline

Get local party display name.

References m_nameA, m_nameB, and m_networkOriginated.

const PString& OpalCall::GetLocalParty ( ) const

inline

Get local party URI.

References m_networkOriginated, m_partyA, and m_partyB.

OpalManager& OpalCall::GetManager ( ) const

inline

Get the manager for this endpoint.

References m_manager.

virtual OpalMediaFormatList OpalCall::GetMediaFormats ( const OpalConnection & connection )

virtual

Get the media formats of the connections in call. This returns the intersection of all the media formats available in connections in the call, not including the parameter. It is in esence the "local" media formats available to the connection.

This will also add to the list all media formats for which there are transcoders registered.

Parameters

connection Connection requesting formats

const PString& OpalCall::GetNameA ( ) const

inline

Get the A party display name for the call. Note this will be available even after the A party connection has been released from the call.

References m_nameA.

const PString& OpalCall::GetNameB ( ) const

inline

Get the B party display name for the call. Note this will be available even after the B party connection has been released from the call. Also this will only be the first B party if the object represents a conference call with more that 2 parties.

References m_nameB.

PSafePtr<OpalConnection> OpalCall::GetOtherPartyConnection ( const OpalConnection & connection ) const

Get the other party's connection object. This will return the other party in the call. It will return NULL if there is no other party yet, or there are more than two parties in the call. Usefull during certain stages during initial call set up.

Parameters

connection Source requesting formats

const PString& OpalCall::GetPartyA ( ) const

inline

Get the A party URI for the call. Note this will be available even after the A party connection has been released from the call.

References m_partyA.

const PString& OpalCall::GetPartyB ( ) const

inline

Get the B party URI for the call. Note this will be available even after the B party connection has been released from the call. Also this will only be the first B party if the object represents a conference call with more that 2 parties.

References m_partyB.

const PString& OpalCall::GetRemoteName ( ) const

inline

Get remote/network party display name.

References m_nameA, m_nameB, and m_networkOriginated.

const PString& OpalCall::GetRemoteParty ( ) const

inline

Get remote/network party URI.

References m_networkOriginated, m_partyA, and m_partyB.

const PTime& OpalCall::GetStartTime ( ) const

inline

Get the time the call started.

References m_startTime.

bool OpalCall::GetStatistics	(	const OpalMediaType &	mediaType,
		bool	fromAparty,
		OpalMediaStatistics &	statistics
	)

Get media statistics of the type, received from the specified party.

Parameters

mediaType	Media type to get statistics for
fromAparty	Getting from A-party or B-party
statistics	Received statistics

const PString& OpalCall::GetToken ( ) const

inline

Get the internal identifier token for this connection.

References m_token.

bool OpalCall::Hold ( bool hold = true )

Put call on hold. This function places the remote user of the network connection in the call on hold.

Referenced by Retrieve().

void OpalCall::InternalOnClear ( )

PBoolean OpalCall::IsEstablished ( ) const

inline

Indicate tha all connections in call are connected and media is going.

References m_isEstablished.

bool OpalCall::IsNetworkOriginated ( ) const

inline

Get indication that A-Party is the network. This will indicate if the call is "incoming" or "outgoing" by looking at the type of the A-party connection.

References m_networkOriginated.

bool OpalCall::IsOnHold ( bool fromRemote = false ) const

Indicate if call is in hold. This function determines if the local or remote user of the network connection in the call is currently on hold.

bool OpalCall::IsRecording ( ) const

Indicate if recording is currently active on call.

virtual void OpalCall::OnAlerting	(	OpalConnection &	connection,
		bool	withMedia
	)

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 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 is to call SetAlerting() on all the other connections in the call.

Parameters

connection	Connection that indicates it is alerting
withMedia	Indicated media should be started, if possible

virtual PBoolean OpalCall::OnAlerting ( OpalConnection & connection )

virtual

virtual OpalConnection::AnswerCallResponse OpalCall::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 returns AnswerCallPending.

virtual void OpalCall::OnCleared ( )

virtual

Call back to indicate that the call has been cleared. At this point in time there are no connections left in the call.

The default behaviour is to call OpalManager::OnClearedCall().

virtual PBoolean OpalCall::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 is to call SetConnected() on all other connections in the call.

Parameters

connection Connection that indicates it is alerting

virtual PBoolean OpalCall::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 media can flow.

In the context of H.323 this means that the CONNECT pdu has been received and either fast start was in operation or the subsequent Open Logical Channels have occurred. For SIP it indicates the INVITE/OK/ACK sequence is complete.

The default behaviour is to check that all connections in call are established and if so, marks the call as established and calls OnEstablishedCall().

Parameters

connection Connection that indicates it is alerting

virtual void OpalCall::OnEstablishedCall ( )

virtual

Call back to indicate that the call has been established. At this point in time every connection in the call is in the "Established" state. This is a better function than using OnEstablished() on a particular connection as it assures that bi-direction media is flowing.

The default behaviour is to call OpalManager::OnEstablishedCall().

virtual void OpalCall::OnHold	(	OpalConnection &	connection,
		bool	fromRemote,
		bool	onHold
	)

virtual

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

The default behaviour does nothing.

Parameters

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

virtual void OpalCall::OnNewConnection ( 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

connection New connection just created

virtual void OpalCall::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 does nothing.

Parameters

connection Connection that is proceeeding

virtual void OpalCall::OnRecordAudio	(	const PString &	streamId,
		const RTP_DataFrame &	frame
	)

virtual

Call back for having a frame of audio to record.

Parameters

streamId	Unique ID for stream within call
frame	Media data

virtual void OpalCall::OnRecordVideo	(	const PString &	streamId,
		const RTP_DataFrame &	frame
	)

virtual

Call back for having a frame of video to record.

Parameters

streamId	Unique ID for stream within call
frame	Media data

virtual void OpalCall::OnReleased ( OpalConnection & connection )

virtual

A call back function whenever a connection is released.

The default behaviour releases the remaining connection if there is only one left.

Parameters

connection Connection that was established

virtual PBoolean OpalCall::OnSetUp ( OpalConnection & connection )

virtual

Call back for SetUp conenction.

The default behaviour is to call SetUpConnection() on all the other connections in the call.

Parameters

connection Connection that indicates it is alerting

virtual bool OpalCall::OnStartRecording	(	const PString &	streamId,
		const OpalMediaFormat &	format
	)

virtual

Call back on recording started.

Parameters

streamId	Unique ID for stream within call
format	Media format for stream

virtual void OpalCall::OnStopRecording ( const PString & streamId )

virtual

Call back on recording stopped.

Parameters

streamId Unique ID for stream within call

virtual void OpalCall::OnUserInputString	(	OpalConnection &	connection,
		const PString &	value
	)

virtual

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

The default behaviour call OpalConnection::SetUserInput() which saves the value so the GetUserInput() function can return it.

Parameters

connection	Connection input has come from
value	String value of indication

virtual void OpalCall::OnUserInputTone	(	OpalConnection &	connection,
		char	tone,
		int	duration
	)

virtual

Call back for remote enpoint has sent user input as tones. 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 connection.OnUserInputString(tone) if there are no other connections in the call, otherwise it calls SendUserInputTone() for each of the other connections in the call.

Parameters

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

OpalCall::OpalConnection::OpalConnection	(	OpalCall &	,
		OpalEndPoint &	,
		const PString &	,
		unsigned	int,
		OpalConnection::StringOptions *
	)

protected

virtual bool OpalCall::OpenSourceMediaStreams	(	OpalConnection &	connection,
		const OpalMediaType &	mediaType,
		unsigned	sessionID = `0`,
		const OpalMediaFormat &	preselectedFormat = `OpalMediaFormat()`,
		OpalVideoFormat::ContentRole	contentRole = `OpalVideoFormat::eNoRole`,
		bool	transfer = `false`,
		bool	startPaused = `false`
	)

virtual

Open source media streams for the specified connection. A source media stream is opened for the connection, if successful then sink media streams are created for every other connection in the call. If at least one sink is created then an OpalMediaPatch is created to transfer data from the source to the sinks.

If session ID is zero a new session is created. If session ID is non zero then that existing session is replaced.

Parameters

connection	Connection requesting open
mediaType	Media type of channel to open
sessionID	Session to start streams on
preselectedFormat	Format for source stream to choose from
contentRole	Content role for video

OpalCall::P_REMOVE_VIRTUAL_VOID ( OnRTPStatistics(const OpalConnection &, const OpalRTPSession &) )

protected

void OpalCall::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

bool OpalCall::Retrieve ( )

inline

Retrieve call from hold. This function retrieves the remote user of the network connection in the call from hold.

References Hold().

virtual bool OpalCall::SelectMediaFormats	(	const OpalMediaType &	mediaType,
		const OpalMediaFormatList &	srcFormats,
		const OpalMediaFormatList &	dstFormats,
		const OpalMediaFormatList &	masterFormats,
		OpalMediaFormat &	srcFormat,
		OpalMediaFormat &	dstFormat
	)		const

virtual

Select media format pair from the source/destination list.

Default behavour calls OpalTranscoder::SelectFormats().

Parameters

mediaType	Media type for selection.
srcFormats	Names of possible source formats
dstFormats	Names of possible destination formats
masterFormats	Master list of formats for merging options
srcFormat	Selected source format to be used
dstFormat	Selected destination format to be used

void OpalCall::SetCallEndReason ( OpalConnection::CallEndReason reason )

Set the call clearance reason. An application should have no cause to use this function. It is present for the H323EndPoint::ClearCall() function to set the clearance reason.

Parameters

reason Reason for clearance of connection.

void OpalCall::SetPartyB ( const PString & b )

inline

Set the B party for a call. This is used when we wish to make two outgoing calls and bridge them. When the OnConnected() call back occurs for the first outgoing call (the A-Party) then this variable ised to make teh second outgoing call.

References m_partyB.

void OpalCall::SetPartyNames ( )

bool OpalCall::StartRecording	(	const PFilePath &	filename,
		const OpalRecordManager::Options &	options = `false`
	)

Start recording a call. Current version saves to a WAV file. It may either mix the receive and transmit audio stream to a single mono file, or the streams are placed into the left and right channels of a stereo WAV file.

Parameters

filename	File into which to record
options	Record mixing options

bool OpalCall::StartRecording	(	const PDirectory &	outputDir,
		const PString &	fileTemplate,
		const PString &	fileType,
		const OpalRecordManager::Options &	options = `false`
	)

Start recording a call using a template. CALL-ID% Call identifier FROM% Calling party TO% Answer party REMOTE% Remote party LOCAL% Local party DATE% Date for call TIME% Time for call TIMESTAMP% Date/Time for call in ISO9660 format HOST% Host name of machine

Parameters

outputDir	Directory for output file
fileTemplate	File template for output file
fileType	Output container type, e.g ".wav"
options	Record mixing options

bool OpalCall::StopRecording ( )

Stop a recording. Returns true if the call does exists, an active call is not indicated.

bool OpalCall::Transfer	(	const PString &	address,
		OpalConnection *	connection = `NULL`
	)

Transfer connection. There are several scenarios for this function.

If 'connection' is not NULL and the protocol type for 'address' is the same, or the protocol type is "*", or the address is a valid and current call token, then this simply calls TransferConnection() on the 'connection' variable.

e.g. connection="sip:fred@bloggs.com" and address="*:1234", then connection->TransferConnection("sip:1234") is called, which sends a REFER command to the remote. The connection and call are subsequently released in this case.

Another example, if connection="pc:Speakers" and address="pc:Headset", then the sound device in the 'connection' instance is changed and the call and media is continued unchanged. The connection and call are not released in this case.

If there is a protocol change, e.g. "pc:" to "t38:", then 'connection' is completely released, all media streams to the second conection in the call (if any) are severed and a new connection established and new media streams started.

If 'connection' is NULL, it will choose the first connection in the call of the same protocol type. For example, in the previous example above where address="pc:Headset", and the call is from "pc:Speakers" to "sip:fred@bloggs.com", the function would operate the same even if 'connection' is NULL.

If there are no connections of the same protocol type, then nothing is done and false is returned.

Parameters