SIPConnection Class Reference

#include <sipcon.h>

Inheritance diagram for SIPConnection:

List of all members.


Public Member Functions
virtual BOOL	ForwardCall (const PString &forwardParty)
BOOL	SendPDU (SIP_PDU &, const OpalTransportAddress &)
unsigned	GetNextCSeq ()
BOOL	BuildSDP (SDPSessionDescription *&, RTP_SessionManager &rtpSessions, unsigned rtpSessionId)
SIPTransaction *	GetTransaction (PString transactionID)
void	AddTransaction (SIPTransaction *transaction)
void	RemoveTransaction (SIPTransaction *transaction)
OpalTransportAddress	GetLocalAddress (WORD port=0) const
OpalTransport &	GetTransport () const
PString	GetLocalPartyAddress () const
void	SetLocalPartyAddress ()
void	SetLocalPartyAddress (const PString &addr)
const PString	GetRemotePartyCallbackURL () const
PString	GetTag () const
SIPEndPoint &	GetEndPoint () const
const SIPURL &	GetTargetAddress () const
const PStringList &	GetRouteSet () const
const SIPAuthentication &	GetAuthenticator () const
Construction
	SIPConnection (OpalCall &call, SIPEndPoint &endpoint, const PString &token, const SIPURL &address, OpalTransport *transport)
	~SIPConnection ()
Overrides from OpalConnection
virtual BOOL	SetUpConnection ()
virtual void	TransferConnection (const PString &remoteParty, const PString &callIdentity=PString::Empty())
virtual void	HoldConnection ()
virtual void	RetrieveConnection ()
virtual BOOL	IsConnectionOnHold ()
virtual BOOL	SetAlerting (const PString &calleeName, BOOL withMedia)
virtual BOOL	SetConnected ()
virtual OpalMediaFormatList	GetMediaFormats () const
virtual BOOL	OpenSourceMediaStream (const OpalMediaFormatList &mediaFormats, unsigned sessionID)
virtual OpalMediaStream *	OpenSinkMediaStream (OpalMediaStream &source)
virtual OpalMediaStream *	CreateMediaStream (const OpalMediaFormat &mediaFormat, unsigned sessionID, BOOL isSource)
virtual OpalConnection::AnswerCallResponse	OnAnswerCall (const PString &callerName)
void	AnsweringCall (AnswerCallResponse response)
virtual void	OnConnected ()
virtual BOOL	IsMediaBypassPossible (unsigned sessionID) const
virtual void	OnReleased ()
Protocol handling functions
virtual void	OnTransactionFailed (SIPTransaction &transaction)
virtual void	OnReceivedPDU (SIP_PDU &pdu)
virtual void	OnReceivedINVITE (SIP_PDU &pdu)
virtual void	OnReceivedACK (SIP_PDU &pdu)
virtual void	OnReceivedOPTIONS (SIP_PDU &pdu)
virtual void	OnReceivedNOTIFY (SIP_PDU &pdu)
virtual void	OnReceivedREFER (SIP_PDU &pdu)
virtual void	OnReceivedBYE (SIP_PDU &pdu)
virtual void	OnReceivedCANCEL (SIP_PDU &pdu)
virtual void	OnReceivedResponse (SIPTransaction &transaction, SIP_PDU &response)
virtual void	OnReceivedTrying (SIP_PDU &pdu)
virtual void	OnReceivedRinging (SIP_PDU &pdu)
virtual void	OnReceivedSessionProgress (SIP_PDU &pdu)
virtual void	OnReceivedAuthenticationRequired (SIPTransaction &transaction, SIP_PDU &response)
virtual void	OnReceivedRedirection (SIP_PDU &pdu)
virtual void	OnReceivedOK (SIPTransaction &transaction, SIP_PDU &response)
void	QueuePDU (SIP_PDU *pdu)
virtual void	OnRTPStatistics (const RTP_Session &session) const
Protected Types
enum	{ ReleaseWithBYE, ReleaseWithCANCEL, ReleaseWithResponse, ReleaseWithNothing }
Protected Member Functions
	PDECLARE_NOTIFIER (PThread, SIPConnection, HandlePDUsThreadMain)
virtual RTP_UDP *	OnUseRTPSession (const unsigned rtpSessionId, const OpalTransportAddress &mediaAddress, OpalTransportAddress &localAddress)
virtual void	OnReceivedSDP (SIP_PDU &pdu)
virtual BOOL	OnReceivedSDPMediaDescription (SDPSessionDescription &sdp, SDPMediaDescription::MediaType mediaType, unsigned sessionId)
virtual BOOL	OnSendSDPMediaDescription (const SDPSessionDescription &sdpIn, SDPMediaDescription::MediaType mediaType, unsigned sessionId, SDPSessionDescription &sdpOut)
virtual BOOL	OnOpenSourceMediaStreams (const OpalMediaFormatList &remoteFormatList, unsigned sessionId, SDPMediaDescription *localMedia)
SDPMediaDescription::Direction	GetDirection (unsigned sessionId)
void	InitRFC2833Handler ()
Static Protected Member Functions
static BOOL	WriteINVITE (OpalTransport &transport, void *param)
Protected Attributes
SIPEndPoint &	endpoint
OpalTransport *	transport
OpalTransportAddress	lastTransportAddress
PMutex	transportMutex
PMutex	streamsMutex
BOOL	local_hold
BOOL	remote_hold
PString	localPartyAddress
PString	forwardParty
SIP_PDU *	originalInvite
SDPSessionDescription	remoteSDP
PStringList	routeSet
SIPURL	targetAddress
SIPAuthentication	authentication
SIP_PDU_Queue	pduQueue
PSemaphore	pduSemaphore
PThread *	pduHandler
SIPTransaction *	referTransaction
SIPTransactionList	invitations
SIPTransactionDict	transactions
unsigned	lastSentCSeq
enum SIPConnection:: { ... }	releaseMethod
OpalMediaFormatList	remoteFormatList

Detailed Description

Session Initiation Protocol connection.

Member Enumeration Documentation

anonymous enum [protected]

Enumeration values:

ReleaseWithBYE

ReleaseWithCANCEL

ReleaseWithResponse

ReleaseWithNothing

Constructor & Destructor Documentation

SIPConnection::SIPConnection ( OpalCall & call,

SIPEndPoint & endpoint,

const PString & token,

const SIPURL & address,

OpalTransport * transport

)

Create a new connection.
Parameters:

call Owner call for connection

endpoint Owner endpoint for connection

token token to identify the connection

address Destination address for outgoing call

transport Transport INVITE came in on

SIPConnection::~SIPConnection ( )

Destroy connection.

Member Function Documentation

void SIPConnection::AddTransaction ( SIPTransaction * transaction ) [inline]

void SIPConnection::AnsweringCall ( AnswerCallResponse response ) [virtual]

Indicate the result of answering an incoming call. This should only be called if the OnAnswerCall() callback function has returned a AnswerCallPending or AnswerCallDeferred response.
Note sending further AnswerCallPending responses via this function will have the result of an 180 PDU being sent to the remote endpoint. In this way multiple Alerting PDUs may be sent.
Sending a AnswerCallDeferred response would have no effect.
Parameters:

response Answer response to incoming call

Reimplemented from OpalConnection.

BOOL SIPConnection::BuildSDP ( SDPSessionDescription *& ,

RTP_SessionManager & rtpSessions,

unsigned rtpSessionId

)

virtual OpalMediaStream* SIPConnection::CreateMediaStream ( const OpalMediaFormat & mediaFormat,

unsigned sessionID,

BOOL isSource

) [virtual]

Open 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.
The default behaviour is pure.
Parameters:

mediaFormat Media format for stream

sessionID Session number for stream

isSource Is a source stream

Reimplemented from OpalConnection.

virtual BOOL SIPConnection::ForwardCall ( const PString & forwardParty ) [virtual]

Forward incoming connection to the specified address. This would typically be called from within the OnIncomingConnection() function when an application wishes to redirect an unwanted incoming call.
The return value is TRUE if the call is to be forwarded, FALSE otherwise. Note that if the call is forwarded, the current connection is cleared with the ended call code set to EndedByCallForwarded.
Parameters:

forwardParty Party to forward call to.

Reimplemented from OpalConnection.

const SIPAuthentication& SIPConnection::GetAuthenticator ( ) const [inline]

SDPMediaDescription::Direction SIPConnection::GetDirection ( unsigned sessionId ) [protected]

SIPEndPoint& SIPConnection::GetEndPoint ( ) const [inline]

Get the owner endpoint for this connection.
Reimplemented from OpalConnection.

OpalTransportAddress SIPConnection::GetLocalAddress ( WORD port = 0 ) const

PString SIPConnection::GetLocalPartyAddress ( ) const [inline]

virtual OpalMediaFormatList SIPConnection::GetMediaFormats ( ) const [virtual]

Get the data formats this endpoint is capable of operating in.
Implements OpalConnection.

unsigned SIPConnection::GetNextCSeq ( ) [inline]

const PString SIPConnection::GetRemotePartyCallbackURL ( ) const [virtual]

Get the remote party address. This will return the "best guess" at an address to use in a to call the user again later.
Reimplemented from OpalConnection.

const PStringList& SIPConnection::GetRouteSet ( ) const [inline]

PString SIPConnection::GetTag ( ) const [inline]

const SIPURL& SIPConnection::GetTargetAddress ( ) const [inline]

SIPTransaction* SIPConnection::GetTransaction ( PString transactionID ) [inline]

OpalTransport& SIPConnection::GetTransport ( ) const [inline, virtual]

Reimplemented from OpalConnection.

virtual void SIPConnection::HoldConnection ( ) [virtual]

Put the current connection on hold, suspending all media streams.
Reimplemented from OpalConnection.

void SIPConnection::InitRFC2833Handler ( ) [protected]

virtual BOOL SIPConnection::IsConnectionOnHold ( ) [virtual]

Return TRUE if the current connection is on hold.
Reimplemented from OpalConnection.

virtual BOOL SIPConnection::IsMediaBypassPossible ( unsigned sessionID ) const [virtual]

See if the media can bypass the local host.
The default behaviour returns FALSE indicating that media bypass is not possible.
Parameters:

sessionID Session ID for media channel

Reimplemented from OpalConnection.

virtual OpalConnection::AnswerCallResponse SIPConnection::OnAnswerCall ( const PString & callerName ) [virtual]

Call back for answering an incoming call. This function is called from the OnReceivedSignalSetup() function before it sends the 200 OK response.
It also gives an 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 a 200 OK is sent. If AnswerCallNow is returned then the SIP protocol proceeds. Finally if AnswerCallPending is returned then the protocol negotiations are paused until the AnsweringCall() function is called.
The default behaviour simply returns AnswerNow.
Parameters:

callerName Name of caller

Reimplemented from OpalConnection.

virtual void SIPConnection::OnConnected ( ) [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 OpalConnection function of the same name after having connected the RFC2833 handler to the OpalPatch.
Reimplemented from OpalConnection.

virtual BOOL SIPConnection::OnOpenSourceMediaStreams ( const OpalMediaFormatList & remoteFormatList,

unsigned sessionId,

SDPMediaDescription * localMedia

) [protected, virtual]

virtual void SIPConnection::OnReceivedACK ( SIP_PDU & pdu ) [virtual]

Handle an incoming ACK PDU

virtual void SIPConnection::OnReceivedAuthenticationRequired ( SIPTransaction & transaction,

SIP_PDU & response

) [virtual]

Handle an incoming Proxy Authentication Required response PDU

virtual void SIPConnection::OnReceivedBYE ( SIP_PDU & pdu ) [virtual]

Handle an incoming BYE PDU

virtual void SIPConnection::OnReceivedCANCEL ( SIP_PDU & pdu ) [virtual]

Handle an incoming CANCEL PDU

virtual void SIPConnection::OnReceivedINVITE ( SIP_PDU & pdu ) [virtual]

Handle an incoming INVITE request

virtual void SIPConnection::OnReceivedNOTIFY ( SIP_PDU & pdu ) [virtual]

Handle an incoming NOTIFY PDU

virtual void SIPConnection::OnReceivedOK ( SIPTransaction & transaction,

SIP_PDU & response

) [virtual]

Handle an incoming OK response PDU. This actually gets any PDU of the class 2xx not just 200.

virtual void SIPConnection::OnReceivedOPTIONS ( SIP_PDU & pdu ) [virtual]

Handle an incoming OPTIONS PDU

virtual void SIPConnection::OnReceivedPDU ( SIP_PDU & pdu ) [virtual]

Handle an incoming SIP PDU that has been full decoded

virtual void SIPConnection::OnReceivedRedirection ( SIP_PDU & pdu ) [virtual]

Handle an incoming redirect response PDU

virtual void SIPConnection::OnReceivedREFER ( SIP_PDU & pdu ) [virtual]

Handle an incoming REFER PDU

virtual void SIPConnection::OnReceivedResponse ( SIPTransaction & transaction,

SIP_PDU & response

) [virtual]

Handle an incoming response PDU.

virtual void SIPConnection::OnReceivedRinging ( SIP_PDU & pdu ) [virtual]

Handle an incoming Ringing response PDU

virtual void SIPConnection::OnReceivedSDP ( SIP_PDU & pdu ) [protected, virtual]

virtual BOOL SIPConnection::OnReceivedSDPMediaDescription ( SDPSessionDescription & sdp,

SDPMediaDescription::MediaType mediaType,

unsigned sessionId

) [protected, virtual]

virtual void SIPConnection::OnReceivedSessionProgress ( SIP_PDU & pdu ) [virtual]

Handle an incoming Session Progress response PDU

virtual void SIPConnection::OnReceivedTrying ( SIP_PDU & pdu ) [virtual]

Handle an incoming Trying response PDU

virtual void SIPConnection::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.

virtual void SIPConnection::OnRTPStatistics ( const RTP_Session & session ) const [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:

session Session with statistics

virtual BOOL SIPConnection::OnSendSDPMediaDescription ( const SDPSessionDescription & sdpIn,

SDPMediaDescription::MediaType mediaType,

unsigned sessionId,

SDPSessionDescription & sdpOut

) [protected, virtual]

virtual void SIPConnection::OnTransactionFailed ( SIPTransaction & transaction ) [virtual]

Handle the fail of a transaction we initiated.

virtual RTP_UDP* SIPConnection::OnUseRTPSession ( const unsigned rtpSessionId,

const OpalTransportAddress & mediaAddress,

OpalTransportAddress & localAddress

) [protected, virtual]

virtual OpalMediaStream* SIPConnection::OpenSinkMediaStream ( OpalMediaStream & source ) [virtual]

Open source transmitter media stream for session.
Parameters:

source Source media sink format to open to

Reimplemented from OpalConnection.

virtual BOOL SIPConnection::OpenSourceMediaStream ( const OpalMediaFormatList & mediaFormats,

unsigned sessionID

) [virtual]

Open source transmitter media stream for session.
Parameters:

mediaFormats Optional media format to open

sessionID Session to start stream on

Reimplemented from OpalConnection.

SIPConnection::PDECLARE_NOTIFIER ( PThread ,

SIPConnection ,

HandlePDUsThreadMain

) [protected]

void SIPConnection::QueuePDU ( SIP_PDU * pdu )

Queue a PDU for the PDU handler thread to handle. Any listener threads on the endpoint upon receiving a PDU and determining the SIPConnection to use from the Call-ID field queues up the PDU so that it can get back to getting PDU's as quickly as possible. All time consuming operations on the PDU are done in the separate thread.

void SIPConnection::RemoveTransaction ( SIPTransaction * transaction ) [inline]

virtual void SIPConnection::RetrieveConnection ( ) [virtual]

Retrieve the current connection from hold, activating all media streams.
Reimplemented from OpalConnection.

BOOL SIPConnection::SendPDU ( SIP_PDU & ,

const OpalTransportAddress &

)

Send a PDU using the connection transport. The PDU is sent to the address given as argument.

virtual BOOL SIPConnection::SetAlerting ( const PString & calleeName,

BOOL withMedia

) [virtual]

Indicate to remote endpoint an alert is in progress. If this is an incoming connection and the AnswerCallResponse is in a AnswerCallDeferred or AnswerCallPending state, then this function is used to indicate to that endpoint that an alert is in progress. This is usually due to another connection which is in the call (the B party) has received an OnAlerting() indicating that its remote endpoint is "ringing".
The default behaviour does nothing.
Parameters:

calleeName Name of endpoint being alerted.

Implements OpalConnection.

virtual BOOL SIPConnection::SetConnected ( ) [virtual]

Indicate to remote endpoint we are connected.
The default behaviour does nothing.
Implements OpalConnection.

void SIPConnection::SetLocalPartyAddress ( const PString & addr ) [inline]

void SIPConnection::SetLocalPartyAddress ( )

Create full SIPURI - with display name, URL in <> and tag, suitable for From:

virtual BOOL SIPConnection::SetUpConnection ( ) [virtual]

Start an outgoing connection. This function will initiate the connection to the remote entity, for example in H.323 it sends a SETUP, in SIP it sends an INVITE etc.
The default behaviour is .
Implements OpalConnection.

virtual void SIPConnection::TransferConnection ( const PString & remoteParty,

const PString & callIdentity = PString::Empty()

) [virtual]

Initiate the transfer of an existing call (connection) to a new remote party.
Parameters:

remoteParty Remote party to transfer the existing call to

callIdentity Call Identity of secondary call if present

Reimplemented from OpalConnection.