# OpalCall Class Reference

`#include <call.h>`

List of all members.

## Public Member Functions

virtual PBoolean | StartRecording (const PFilePath &fn)
virtual bool | IsRecording () const
virtual void | StopRecording ()
void | OnStopRecordAudio (const PString &callToken)
Overrides from PObject
void | PrintOn (ostream &strm) const
Basic operations
PBoolean | IsEstablished () const
virtual void | OnEstablishedCall ()
OpalConnection::CallEndReason | GetCallEndReason () 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 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
PSafePtr< OpalConnection > | GetConnection (PINDEX idx, PSafetyMode mode=PSafeReference)
template<class ConnClass>
PSafePtr< ConnClass > | GetConnectionAs (PINDEX count=0, PSafetyMode mode=PSafeReadWrite)
bool | Hold ()
bool | Retrieve ()
bool | IsOnHold () const
bool | Transfer (OpalConnection &connection, const PString &newAddress)
Media management
virtual OpalMediaFormatList | GetMediaFormats (const OpalConnection &connection, PBoolean includeSpecifiedConnection)
virtual bool | OpenSourceMediaStreams (OpalConnection &connection, const OpalMediaType &mediaType, unsigned sessionID=0, const OpalMediaFormat &preselectedFormat=OpalMediaFormat())
virtual bool | SelectMediaFormats (const OpalMediaFormatList &srcFormats, const OpalMediaFormatList &dstFormats, const OpalMediaFormatList &allFormats, OpalMediaFormat &srcFormat, OpalMediaFormat &dstFormat) const
virtual void | OnRTPStatistics (const OpalConnection &connection, const RTP_Session &session)
virtual void | CloseMediaStreams ()
virtual PBoolean | IsMediaBypassPossible (const OpalConnection &connection, unsigned sessionID) const
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)
bool | IsNetworkOriginated () const
const PTime & | GetStartTime () const

## Protected Member Functions

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

## Protected Attributes

OpalManager & | manager
PString | myToken
PString | m_partyA
PString | m_partyB
PTime | startTime
bool | isEstablished
bool | isClearing
OpalConnection::CallEndReason | callEndReason
PSafeList< OpalConnection > | connectionsActive
PSyncPoint * | endCallSyncPoint

## 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]`

OpalCall::OpalCall | ( | OpalManager & | manager | ) |

Create a new call.

Parameters:

  manager | Manager for the opal system

OpalCall::~OpalCall | ( |  | ) |

Destroy call.

## Member Function Documentation

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

PBoolean OpalCall::IsEstablished | ( |  | ) | const`[inline]`

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

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

OpalConnection::CallEndReason OpalCall::GetCallEndReason | ( |  | ) | const`[inline]`

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

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

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::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::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 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 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 PBoolean OpalCall::OnAlerting | ( | OpalConnection & | connection | ) | `[virtual]`

Call back for alerting.

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

Parameters:

  connection | Connection that indicates it is alerting

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 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 has media flowing.

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

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

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

Get the specified active connection in call.

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.

bool OpalCall::Hold | ( |  | ) |

Put call on hold.

bool OpalCall::Retrieve | ( |  | ) |

Retrieve call from hold.

bool OpalCall::IsOnHold | ( |  | ) | const

Indicate if call is in hold.

bool OpalCall::Transfer | ( | OpalConnection & | connection,
|  | const PString & | newAddress |
| ) |  |  |

Transfer connection. If the newAddress indicates a protocol type and it is the same as connection then this simply calls TransferConnection on the connection variable.

If there is a protocol change, e.g. "pc" to "t38", then the connection is completely closed, all links to the second conection in the call (if any) severed and a new connection establshed and new streams started.

Parameters:

  connection | Connection to transfer
  newAddress | New address to transfer to

virtual OpalMediaFormatList OpalCall::GetMediaFormats | ( | const OpalConnection & | connection,
|  | PBoolean | includeSpecifiedConnection |
| ) |  |  | `[virtual]`

Get the media formats of the connections in call. This returns the intersection of all the media formats that all connections in the call, optionally excepting the one provided as a parameter, are capable of.

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

Parameters:

  connection | Connection requesting formats
  includeSpecifiedConnection | Include parameters media

virtual bool OpalCall::OpenSourceMediaStreams | ( | OpalConnection & | connection,
|  | const OpalMediaType & | mediaType,
|  | unsigned | sessionID = `0`,
|  | const OpalMediaFormat & | preselectedFormat = `OpalMediaFormat()` |
| ) |  |  | `[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

virtual bool OpalCall::SelectMediaFormats | ( | const OpalMediaFormatList & | srcFormats,
|  | const OpalMediaFormatList & | dstFormats,
|  | const OpalMediaFormatList & | allFormats,
|  | OpalMediaFormat & | srcFormat,
|  | OpalMediaFormat & | dstFormat |
| ) |  |  | const`[virtual]`

Select media format pair from the source/destination list.

Default behavour calls OpalTranscoder::SelectFormats().

Parameters:

  srcFormats | Names of possible source formats
  dstFormats | Names of possible destination formats
  allFormats | Master list of formats for merging options
  srcFormat | Selected source format to be used
  dstFormat | Selected destination format to be used

virtual void OpalCall::OnRTPStatistics | ( | const OpalConnection & | connection,
|  | const RTP_Session & | session |
| ) |  |  | `[virtual]`

Callback from the RTP session for statistics monitoring. This is called every so many packets on the transmitter and receiver threads of the RTP session indicating that the statistics have been updated.

The default behaviour does nothing.

Parameters:

  connection | Connection for the channel
  session | Session with statistics

virtual void OpalCall::CloseMediaStreams | ( |  | ) | `[virtual]`

Close the media streams on the connections.

virtual PBoolean OpalCall::IsMediaBypassPossible | ( | const OpalConnection & | connection,
|  | unsigned | sessionID |
| ) |  |  | const`[virtual]`

See if the media can bypass the local host.

Parameters:

  connection | Source connection
  sessionID | Session ID for media channel

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 non-zero then it indicates the end of the tone output.

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

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

Get the manager for this endpoint.

const PString& OpalCall::GetToken | ( |  | ) | const`[inline]`

Get the internal identifier token for this connection.

const PString& OpalCall::GetPartyA | ( |  | ) | const`[inline]`

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

const PString& OpalCall::GetPartyB | ( |  | ) | const`[inline]`

Get the B party 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.

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.

bool OpalCall::IsNetworkOriginated | ( |  | ) | const

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.

const PTime& OpalCall::GetStartTime | ( |  | ) | const`[inline]`

Get the time the call started.

virtual PBoolean OpalCall::StartRecording | ( | const PFilePath & | fn | ) | `[virtual]`

virtual bool OpalCall::IsRecording | ( |  | ) | const`[virtual]`

virtual void OpalCall::StopRecording | ( |  | ) | `[virtual]`

void OpalCall::OnStopRecordAudio | ( | const PString & | callToken | ) |

void OpalCall::SetPartyNames | ( |  | ) | `[protected]`

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

OpalCall::OpalConnection::OpalConnection | ( | OpalCall & | ,
|  | OpalEndPoint & | ,
|  | const PString & | ,
|  | unsigned | int,
|  | OpalConnection::StringOptions * |  |
| ) |  |  | `[protected]`

## Member Data Documentation

OpalManager& OpalCall::manager `[protected]`

PString OpalCall::myToken `[protected]`

PString OpalCall::m_partyA `[protected]`

PString OpalCall::m_partyB `[protected]`

PTime OpalCall::startTime `[protected]`

bool OpalCall::isEstablished `[protected]`

bool OpalCall::isClearing `[protected]`

OpalConnection::CallEndReason OpalCall::callEndReason `[protected]`

PSafeList<OpalConnection> OpalCall::connectionsActive `[protected]`

PSyncPoint* OpalCall::endCallSyncPoint `[protected]`

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

- call.h