# OpalRTPConnection Class Reference

`#include <rtpconn.h>`

Inheritance diagram for OpalRTPConnection:

[legend]
Collaboration diagram for OpalRTPConnection:
[legend]

## Public Member Functions

Construction
| OpalRTPConnection (OpalCall &call, OpalRTPEndPoint &endpoint, const PString &token, unsigned options=0, OpalConnection::StringOptions *stringOptions=NULL)
| ~OpalRTPConnection ()
virtual void | OnReleased ()
Overrides from OpalConnection
virtual OpalMediaStream * | CreateMediaStream (const OpalMediaFormat &mediaFormat, unsigned sessionID, PBoolean isSource)
virtual bool | GetMediaTransportAddresses (const OpalMediaType &mediaType, OpalTransportAddressArray &transports) const
virtual void | AdjustMediaFormats (bool local, const OpalConnection *otherConnection, OpalMediaFormatList &mediaFormats) const
virtual void | OnPatchMediaStream (PBoolean isSource, OpalMediaPatch &patch)
virtual bool | OnMediaCommand (OpalMediaStream &stream, const OpalMediaCommand &command)
virtual PBoolean | SendUserInputTone (char tone, unsigned duration=0)
RTP Session Management
virtual unsigned | GetNextSessionID (const OpalMediaType &mediaType, bool isSource)
| P_DECLARE_BITWISE_ENUM (CreateMediaSessionsSecurity, 2,(e_NoMediaSessions, e_ClearMediaSession, e_SecureMediaSession))
vector< bool > | CreateAllMediaSessions (CreateMediaSessionsSecurity security)
virtual OpalMediaSession * | CreateMediaSession (unsigned sessionId, const OpalMediaType &mediaType, const PString &sessionType=PString::Empty())
virtual OpalMediaSession * | GetMediaSession (unsigned sessionID) const
virtual OpalMediaSession * | FindSessionByLocalPort (WORD port) const
virtual OpalMediaSession * | UseMediaSession (unsigned sessionId, const OpalMediaType &mediaType, const PString &sessionType=PString::Empty())
virtual void | ReleaseMediaSession (unsigned sessionID)
virtual bool | ChangeSessionID (unsigned fromSessionID, unsigned toSessionID)
virtual void | ReplaceMediaSession (unsigned sessionId, OpalMediaSession *mediaSession)
virtual bool | SetSessionQoS (OpalRTPSession *session)
NAT Management
virtual void | DetermineRTPNAT (const PIPSocket::Address &localAddr, const PIPSocket::Address &peerAddr, const PIPSocket::Address &signalAddr)

## Protected Member Functions

virtual bool | GarbageCollection ()
| PDECLARE_NOTIFIER (OpalRFC2833Info, OpalRTPConnection, OnUserInputInlineRFC2833)
void | CheckForMediaBypass (OpalMediaSession &session)
| P_REMOVE_VIRTUAL (PBoolean, IsRTPNATEnabled(const PIPSocket::Address &, const PIPSocket::Address &, const PIPSocket::Address &, PBoolean), false)

## Protected Attributes

SessionMap | m_sessions
bool | m_remoteBehindNAT
OpalRFC2833Proto * | m_rfc2833Handler
PSimpleTimer | m_rtcpIntraFrameRequestTimer

## Data Structures

class | SessionMap

## Detailed Description

This is the base class for OpalConnections that use RTP sessions, such as H.323 and SIPconnections to an endpoint.

## Constructor & Destructor Documentation

OpalRTPConnection::OpalRTPConnection | ( | OpalCall & | call,
|  | OpalRTPEndPoint & | endpoint,
|  | const PString & | token,
|  | unsigned | options = `0`,
|  | OpalConnection::StringOptions * | stringOptions = `NULL` |
| ) |  |  |

Create a new connection.

Parameters:

  call | Owner calll for connection
  endpoint | Owner endpoint for connection
  token | Token to identify the connection
  options | Connection options
  stringOptions | more complex options

OpalRTPConnection::~OpalRTPConnection | ( |  | ) |

Destroy connection.

## Member Function Documentation

virtual void OpalRTPConnection::AdjustMediaFormats | ( | bool | local,
|  | const OpalConnection * | otherConnection,
|  | 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.

This function may also be executed by other connections in the call. If this happens then the "otherConnection" parameter will be non-NULL. The "local" parameter sense is relative to the "otherConnection" parameter, if NULL then it is relative to "this".

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

Parameters:

  local | Media formats a local ones to be presented to remote
  otherConnection | Other connection we are adjusting media for
  mediaFormats | Media formats to use

Reimplemented from OpalConnection.

virtual bool OpalRTPConnection::ChangeSessionID | ( | unsigned | fromSessionID,
|  | unsigned | toSessionID |
| ) |  |  | `[virtual]`

Change the sessionID for an existing session. This will adjust the RTP session and media streams.

Return false if no such session exists.

Parameters:

  fromSessionID | Session ID to search for
  toSessionID | Session ID to change to

void OpalRTPConnection::CheckForMediaBypass | ( | OpalMediaSession & | session | ) | `[protected]`

vector<bool> OpalRTPConnection::CreateAllMediaSessions | ( | CreateMediaSessionsSecurity | security | ) |

Create all media sessions for available media types. Note that the sessions are not opened, just created.

Sessions using media security will alsoe be created if `secure` is true. This indicates the media key exchange can be done securely, typically it means signaling channel is also secure.

Returns:
  a list of the media types for which sessions where created.

Parameters:

  security | Wse secure media, or not

virtual OpalMediaSession* OpalRTPConnection::CreateMediaSession | ( | unsigned | sessionId,
|  | const OpalMediaType & | mediaType,
|  | const PString & | sessionType = `PString::Empty()` |
| ) |  |  | `[virtual]`

Create an RTP session for the specified ID. The type of RTP session that is created will be compatible with the transport. At this time only IP (RTP over UDP) is supported.

Parameters:

  sessionId | Unique (in connection) session ID for session
  mediaType | Media type for session
  sessionType | Type of session to create

virtual OpalMediaStream* OpalRTPConnection::CreateMediaStream | ( | const OpalMediaFormat & | mediaFormat,
|  | unsigned | sessionID,
|  | PBoolean | isSource |
| ) |  |  | `[virtual]`

Create a new media stream. This will create a media stream of an appropriate subclass as required by the underlying connection protocol. For instance H.323 would create an OpalRTPStream.

The sessionID parameter may not be needed by a particular media stream and may be ignored. In the case of an OpalRTPStream it us used.

Note that media streams may be created internally to the underlying protocol. This function is not the only way a stream can come into existance.

Parameters:

  mediaFormat | Media format for stream
  sessionID | Session number for stream
  isSource | Is a source stream

Reimplemented from OpalConnection.

Reimplemented in SIPConnection.

virtual void OpalRTPConnection::DetermineRTPNAT | ( | const PIPSocket::Address & | localAddr,
|  | const PIPSocket::Address & | peerAddr,
|  | const PIPSocket::Address & | signalAddr |
| ) |  |  | `[virtual]`

Determine if the RTP session needs to accommodate a NAT router. For endpoints that do not use STUN or something similar to set up all the correct protocol embeddded addresses correctly when a NAT router is between the endpoints, it is possible to still accommodate the call, with some restrictions. This function determines if the RTP can proceed with special NAT allowances.

The special allowance is that the RTP code will ignore whatever the remote indicates in the protocol for the address to send RTP data and wait for the first packet to arrive from the remote and will then proceed to send all RTP data back to that address AND port.

The default behaviour checks the values of the physical link (localAddr/peerAddr) against the signaling address the remote indicated in the protocol, eg H.323 SETUP sourceCallSignalAddress or SIP "To" or "Contact" fields, and makes a guess that the remote is behind a NAT router.

Parameters:

  localAddr | Local physical address of connection
  peerAddr | Remote physical address of connection
  signalAddr | Remotes signaling address as indicated by protocol of connection

Reimplemented in H323Connection.

virtual OpalMediaSession* OpalRTPConnection::FindSessionByLocalPort | ( | WORD | port | ) | const`[virtual]`

Find an RTP session for the specified local port. If there is no session, NULL is returned.

Parameters:

  port | Local port number

virtual bool OpalRTPConnection::GarbageCollection | ( |  | ) | `[protected, virtual]`

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

Reimplemented from OpalConnection.

Reimplemented in SIPConnection.

virtual OpalMediaSession* OpalRTPConnection::GetMediaSession | ( | unsigned | sessionID | ) | const`[virtual]`

Get an RTP session for the specified ID. If there is no session of the specified ID, NULL is returned.

Parameters:

  sessionID | RTP session number

virtual bool OpalRTPConnection::GetMediaTransportAddresses | ( | 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:

  mediaType | Media type for session to return information
  transports | Information on media session

Reimplemented from OpalConnection.

Reimplemented in H323Connection, and SIPConnection.

virtual unsigned OpalRTPConnection::GetNextSessionID | ( | const OpalMediaType & | mediaType,
|  | bool | isSource |
| ) |  |  | `[virtual]`

Get next available session ID for the media type.

Parameters:

  mediaType | Media type of stream being opened
  isSource | Stream is a source/sink

Reimplemented from OpalConnection.

Reimplemented in H323Connection.

virtual bool OpalRTPConnection::OnMediaCommand | ( | OpalMediaStream & | stream,
|  | const OpalMediaCommand & | command |
| ) |  |  | `[virtual]`

Callback for media commands. Calls the SendIntraFrameRequest on the rtp session

Returns:
  true if command is handled.

Parameters:

  stream | Stream command executed on
  command | Media command being executed

Reimplemented from OpalConnection.

Reimplemented in H323Connection, and SIPConnection.

virtual void OpalRTPConnection::OnPatchMediaStream | ( | PBoolean | isSource,
|  | OpalMediaPatch & | patch |
| ) |  |  | `[virtual]`

Call back when patching a media stream. This function is called when a connection has created a new media patch between two streams. This is usually called twice per media patch, once for the source stream and once for the sink stream.

Note this is not called within the context of the patch thread and is called before that thread has started.

Parameters:

  isSource | Is source/sink call
  patch | New patch

Reimplemented from OpalConnection.

Reimplemented in SIPConnection.

virtual void OpalRTPConnection::OnReleased | ( |  | ) | `[virtual]`

Clean up the termination of the connection. 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 SetUpConnection() 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 calls the OpalEndPoint function of the same name.

Reimplemented from OpalConnection.

Reimplemented in H323Connection, and SIPConnection.

OpalRTPConnection::P_DECLARE_BITWISE_ENUM | ( | CreateMediaSessionsSecurity | ,
|  | 2 | ,
|  | (e_NoMediaSessions, e_ClearMediaSession, e_SecureMediaSession) |  |
| ) |  |  |

OpalRTPConnection::P_REMOVE_VIRTUAL | ( | PBoolean | ,
|  | IsRTPNATEnabled(const PIPSocket::Address &, const PIPSocket::Address &, const PIPSocket::Address &, PBoolean) | ,
|  | false |  |
| ) |  |  | `[protected]`

OpalRTPConnection::PDECLARE_NOTIFIER | ( | OpalRFC2833Info | ,
|  | OpalRTPConnection | ,
|  | OnUserInputInlineRFC2833 |  |
| ) |  |  | `[protected]`

virtual void OpalRTPConnection::ReleaseMediaSession | ( | unsigned | sessionID | ) | `[virtual]`

Release the session.

Parameters:

  sessionID | RTP session number

virtual void OpalRTPConnection::ReplaceMediaSession | ( | unsigned | sessionId,
|  | OpalMediaSession * | mediaSession |
| ) |  |  | `[virtual]`

Replace existing session with new one, exchanging transports.

Parameters:

  sessionId | Session ID to replace
  mediaSession | New session

virtual PBoolean OpalRTPConnection::SendUserInputTone | ( | char | tone,
|  | unsigned | duration = `0` |
| ) |  |  | `[virtual]`

Send a user input indication to the remote endpoint. This sends DTMF emulation user input. If something more sophisticated than the simple tones that can be sent using the SendUserInput() function.

A duration of zero indicates that no duration is to be indicated. A non-zero logical channel indicates that the tone is to be syncronised with the logical channel at the rtpTimestamp value specified.

The tone parameter must be one of "0123456789#*ABCD!" where '!' indicates a hook flash. If tone is a ' ' character then a signalUpdate PDU is sent that updates the last tone indication sent. See the H.245 specifcation for more details on this.

The default behaviour sends the tone using RFC2833.

Parameters:

  tone | DTMF tone code
  duration | Duration of tone in milliseconds

Reimplemented from OpalConnection.

Reimplemented in H323Connection, and SIPConnection.

virtual bool OpalRTPConnection::SetSessionQoS | ( | OpalRTPSession * | session | ) | `[virtual]`

Set QoS on session.

virtual OpalMediaSession* OpalRTPConnection::UseMediaSession | ( | unsigned | sessionId,
|  | const OpalMediaType & | mediaType,
|  | const PString & | sessionType = `PString::Empty()` |
| ) |  |  | `[virtual]`

Use an RTP session for the specified ID. This will find a session of the specified ID and uses it if available.

If there is no session of the specified ID one is created.

The type of RTP session that is created will be compatible with the transport. At this time only IP (RTP over UDP) is supported.

Parameters:

  sessionId | Unique (in connection) session ID for session
  mediaType | Media type for session
  sessionType | Type of session to create

## Field Documentation

bool OpalRTPConnection::m_remoteBehindNAT `[protected]`

OpalRFC2833Proto* OpalRTPConnection::m_rfc2833Handler `[protected]`

PSimpleTimer OpalRTPConnection::m_rtcpIntraFrameRequestTimer `[protected]`

SessionMap OpalRTPConnection::m_sessions `[protected]`

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

- rtpconn.h