SIPConnection Class Reference

#include <sipcon.h>

Inheritance diagram for SIPConnection:


Public Member Functions
unsigned	GetNextCSeq ()
OpalTransportAddress	GetLocalAddress (WORD port=0) const
OpalTransport &	GetTransport () const
SIPEndPoint &	GetEndPoint () const
const SIPURL &	GetRequestURI () const
const PString &	GetDialogFrom () const
const PString &	GetDialogTo () const
const PStringList &	GetRouteSet () const
SIPAuthentication *	GetAuthenticator () const
virtual void	OnMediaCommand (OpalMediaCommand &note, INT extra)
	PDECLARE_NOTIFIER (PTimer, SIPConnection, OnSessionTimeout)
Overrides from OpalConnection
virtual bool	IsNetworkConnection () const
virtual PString	GetPrefixName () const
virtual PString	GetRemotePartyURL () const
virtual PBoolean	SetUpConnection ()
virtual PString	GetDestinationAddress ()
virtual PString	GetCalledPartyURL ()
virtual bool	TransferConnection (const PString &remoteParty)
virtual bool	HoldConnection ()
virtual bool	RetrieveConnection ()
virtual PBoolean	IsConnectionOnHold ()
virtual PBoolean	SetAlerting (const PString &calleeName, PBoolean withMedia)
virtual PBoolean	SetConnected ()
virtual OpalMediaFormatList	GetMediaFormats () const
virtual OpalMediaStreamPtr	OpenMediaStream (const OpalMediaFormat &mediaFormat, unsigned sessionID, bool isSource)
virtual bool	CloseMediaStream (OpalMediaStream &stream)
virtual void	OnReleased ()
virtual PBoolean	ForwardCall (const PString &forwardParty)
virtual SendUserInputModes	GetRealSendUserInputMode () const
PBoolean	SendUserInputTone (char tone, unsigned duration)
virtual void	OnRTPStatistics (const RTP_Session &session) const
Protocol handling functions
virtual void	OnTransactionFailed (SIPTransaction &transaction)
virtual void	OnReceivedPDU (SIP_PDU &pdu)
virtual void	OnReceivedINVITE (SIP_PDU &pdu)
virtual void	OnReceivedReINVITE (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	OnReceivedINFO (SIP_PDU &pdu)
virtual void	OnReceivedPING (SIP_PDU &pdu)
virtual void	OnReceivedBYE (SIP_PDU &pdu)
virtual void	OnReceivedCANCEL (SIP_PDU &pdu)
virtual void	OnReceivedResponseToINVITE (SIPTransaction &transaction, SIP_PDU &response)
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 PBoolean	OnReceivedAuthenticationRequired (SIPTransaction &transaction, SIP_PDU &response)
virtual void	OnReceivedRedirection (SIP_PDU &pdu)
virtual void	OnReceivedOK (SIPTransaction &transaction, SIP_PDU &response)
virtual void	OnCreatingINVITE (SIP_PDU &pdu)
virtual PBoolean	SendInviteOK (const SDPSessionDescription &sdp)
virtual PBoolean	SendInviteResponse (SIP_PDU::StatusCodes code, const char contact=NULL, const char extra=NULL, const SDPSessionDescription *sdp=NULL)
Protected Types
enum	HoldState { eHoldOff, eRetrieveInProgress, eHoldOn, eHoldInProgress }
enum	{ ReleaseWithBYE, ReleaseWithCANCEL, ReleaseWithResponse, ReleaseWithNothing }
Protected Member Functions
	PDECLARE_NOTIFIER (PTimer, SIPConnection, OnInviteResponseRetry)
	PDECLARE_NOTIFIER (PTimer, SIPConnection, OnAckTimeout)
void	AdjustOutgoingINVITE ()
virtual RTP_UDP *	OnUseRTPSession (const unsigned rtpSessionId, const OpalMediaType &mediaType, const OpalTransportAddress &mediaAddress, OpalTransportAddress &localAddress)
virtual bool	OnSendSDP (bool isAnswerSDP, OpalRTPSessionManager &rtpSessions, SDPSessionDescription &sdpOut)
virtual bool	OfferSDPMediaDescription (const OpalMediaType &mediaType, unsigned sessionID, OpalRTPSessionManager &rtpSessions, SDPSessionDescription &sdpOut)
virtual bool	AnswerSDPMediaDescription (const SDPSessionDescription &sdpIn, unsigned sessionIndex, SDPSessionDescription &sdpOut)
virtual void	OnReceivedSDP (SIP_PDU &pdu)
virtual bool	OnReceivedSDPMediaDescription (SDPSessionDescription &sdp, unsigned sessionId)
OpalTransport *	CreateTransport (const OpalTransportAddress &address, PBoolean isLocalAddress=PFalse)
void	UpdateRemoteAddresses (const PString &addr)
Static Protected Member Functions
static PBoolean	WriteINVITE (OpalTransport &transport, void *param)
Protected Attributes
SIPEndPoint &	endpoint
OpalTransport *	transport
bool	deleteTransport
HoldState	m_holdToRemote
bool	m_holdFromRemote
PString	forwardParty
SIP_PDU *	originalInvite
PTime	originalInviteTime
bool	needReINVITE
PStringList	routeSet
SIPURL	m_requestURI
PString	m_dialogFrom
PString	m_dialogTo
SIPAuthentication *	authentication
std::map< SIP_PDU::Methods, unsigned >	m_lastRxCSeq
PTimer	ackTimer
PTimer	ackRetry
SIP_PDU	ackPacket
bool	ackReceived
PSafePtr< SIPTransaction >	referTransaction
PSafeList< SIPTransaction >	forkedInvitations
PAtomicInteger	lastSentCSeq
enum SIPConnection:: { ... }	releaseMethod
OpalMediaFormatList	remoteFormatList
PTimer	sessionTimer
Friends
class	SIPInvite

Detailed Description

Session Initiation Protocol connection.

Member Enumeration Documentation

enum SIPConnection::HoldState [protected]

Enumerator:

eHoldOff
eRetrieveInProgress
eHoldOn
eHoldInProgress

anonymous enum [protected]

Enumerator:

ReleaseWithBYE
ReleaseWithCANCEL
ReleaseWithResponse
ReleaseWithNothing

Constructor & Destructor Documentation

SIPConnection::SIPConnection	(	OpalCall &	call,
		SIPEndPoint &	endpoint,
		const PString &	token,
		const SIPURL &	address,
		OpalTransport *	transport,
		unsigned int	options = `0`,
		OpalConnection::StringOptions *	stringOptions = `NULL`
	)

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
options	Connection options
stringOptions	complex string options

SIPConnection::~SIPConnection ( )

Destroy connection.

SIPConnection::SIPConnection	(	OpalCall &	call,
		SIPEndPoint &	endpoint,
		const PString &	token,
		const SIPURL &	address,
		OpalTransport *	transport,
		unsigned int	options = `0`,
		OpalConnection::StringOptions *	stringOptions = `NULL`
	)

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
options	Connection options
stringOptions	complex string options

SIPConnection::~SIPConnection ( )

Destroy connection.

Member Function Documentation

virtual bool SIPConnection::IsNetworkConnection ( ) const [inline, virtual]

Get indication of connection being to a "network". This indicates the if the connection may be regarded as a "network" connection. The distinction is about if there is a concept of a "remote" party being connected to and is best described by example: sip, h323, iax and pstn are all "network" connections as they connect to something "remote". While pc, pots and ivr are not as the entity being connected to is intrinsically local.

Implements OpalConnection.

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

Get this connections protocol prefix for URLs.

Reimplemented from OpalConnection.

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

Get the remote party address as URL. This will return the "best guess" at an address to use in a to call the user again later. Note that under some circumstances this may be different to the value GetRemotePartyAddress() value returns. In particular if a gatekeeper is involved.

Reimplemented from OpalConnection.

virtual PBoolean 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 PString SIPConnection::GetDestinationAddress ( ) [virtual]

Get the destination address of an incoming connection. This will, for example, collect a phone number from a POTS line, or get the fields from the H.225 SETUP pdu in a H.323 connection.

The default behaviour for sip returns the request URI in the INVITE.

Reimplemented from OpalConnection.

virtual PString SIPConnection::GetCalledPartyURL ( ) [virtual]

Get the fulll URL being indicated by the remote for incoming calls. This may not have any relation to the local name of the endpoint.

The default behaviour returns GetDestinationAddress() normalised to a URL. The remote may provide a full URL, if it does not then the prefix for the endpoint is prepended to the destination address.

Reimplemented from OpalConnection.

virtual bool SIPConnection::TransferConnection ( const PString & remoteParty ) [virtual]

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

If remoteParty is a valid call token, then the remote party is transferred to that party (consultation transfer) and both calls are cleared.

Parameters:

remoteParty

Remote party to transfer the existing call to

Reimplemented from OpalConnection.

virtual bool SIPConnection::HoldConnection ( ) [virtual]

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

Reimplemented from OpalConnection.

virtual bool SIPConnection::RetrieveConnection ( ) [virtual]

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

Reimplemented from OpalConnection.

virtual PBoolean SIPConnection::IsConnectionOnHold ( ) [virtual]

Return PTrue if the current connection is on hold.

Reimplemented from OpalConnection.

virtual PBoolean SIPConnection::SetAlerting	(	const PString &	calleeName,
		PBoolean	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 PBoolean SIPConnection::SetConnected ( ) [virtual]

Indicate to remote endpoint we are connected.

The default behaviour does nothing.

Reimplemented from OpalConnection.

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

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

Reimplemented from OpalConnection.

virtual OpalMediaStreamPtr SIPConnection::OpenMediaStream	(	const OpalMediaFormat &	mediaFormat,
		unsigned	sessionID,
		bool	isSource
	)			`[virtual]`

Open source or sink media stream for session.

Parameters:

mediaFormat	Media format to open
sessionID	Session to start stream on
isSource	Stream is a source/sink

Reimplemented from OpalConnection.

virtual bool SIPConnection::CloseMediaStream ( OpalMediaStream & stream ) [virtual]

Request close of a specific media stream. Note that this is usually asymchronous, the OnClosedMediaStream() function is called when the stream is really closed.

Parameters:

stream

Stream to close

Reimplemented from OpalConnection.

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 PBoolean 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 PTrue if the call is to be forwarded, PFalse 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.

virtual SendUserInputModes SIPConnection::GetRealSendUserInputMode ( ) const [virtual]

Get the real user input indication transmission mode. This will return the user input mode that will actually be used for transmissions. It will be the value of GetSendUserInputMode() provided the remote endpoint is capable of that mode.

Reimplemented from OpalConnection.

PBoolean SIPConnection::SendUserInputTone	(	char	tone,
		unsigned	duration
	)			`[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.

Reimplemented from OpalRTPConnection.

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 void SIPConnection::OnTransactionFailed ( SIPTransaction & transaction ) [virtual]

Handle the fail of a transaction we initiated.

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

Handle an incoming SIP PDU that has been full decoded

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

Handle an incoming INVITE request

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

Handle an incoming Re-INVITE request

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

Handle an incoming ACK PDU

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

Handle an incoming OPTIONS PDU

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

Handle an incoming NOTIFY PDU

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

Handle an incoming REFER PDU

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

Handle an incoming INFO PDU

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

Handle an incoming PING 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::OnReceivedResponseToINVITE	(	SIPTransaction &	transaction,
		SIP_PDU &	response
	)			`[virtual]`

Handle an incoming response PDU to our INVITE. Note this is called before th ACK is sent and thus should do as little as possible. All the hard work (SDP processing etc) should be in the usual OnReceivedResponse().

virtual void SIPConnection::OnReceivedResponse	(	SIPTransaction &	transaction,
		SIP_PDU &	response
	)			`[virtual]`

Handle an incoming response PDU.

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

Handle an incoming Trying response PDU

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

Handle an incoming Ringing response PDU

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

Handle an incoming Session Progress response PDU

virtual PBoolean SIPConnection::OnReceivedAuthenticationRequired	(	SIPTransaction &	transaction,
		SIP_PDU &	response
	)			`[virtual]`

Handle an incoming Proxy Authentication Required response PDU Returns: PTrue if handled, if PFalse is returned connection is released.

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

Handle an incoming redirect response 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::OnCreatingINVITE ( SIP_PDU & pdu ) [virtual]

Handle a sending INVITE request

virtual PBoolean SIPConnection::SendInviteOK ( const SDPSessionDescription & sdp ) [virtual]

Send a "200 OK" response for the received INVITE message.

virtual PBoolean SIPConnection::SendInviteResponse	(	SIP_PDU::StatusCodes	code,
		const char *	contact = `NULL`,
		const char *	extra = `NULL`,
		const SDPSessionDescription *	sdp = `NULL`
	)			`[virtual]`

Send a response for the received INVITE message.

unsigned SIPConnection::GetNextCSeq ( ) [inline]

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

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

Reimplemented from OpalConnection.

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

Get the owner endpoint for this connection.

Reimplemented from OpalConnection.

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

const PString& SIPConnection::GetDialogFrom ( ) const [inline]

const PString& SIPConnection::GetDialogTo ( ) const [inline]

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

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

virtual void SIPConnection::OnMediaCommand	(	OpalMediaCommand &	note,
		INT	extra
	)			`[virtual]`

Reimplemented from OpalRTPConnection.

SIPConnection::PDECLARE_NOTIFIER	(	PTimer	,
		SIPConnection	,
		OnInviteResponseRetry
	)			`[protected]`

SIPConnection::PDECLARE_NOTIFIER	(	PTimer	,
		SIPConnection	,
		OnAckTimeout
	)			`[protected]`

void SIPConnection::AdjustOutgoingINVITE ( ) [protected]

virtual RTP_UDP* SIPConnection::OnUseRTPSession	(	const unsigned	rtpSessionId,
		const OpalMediaType &	mediaType,
		const OpalTransportAddress &	mediaAddress,
		OpalTransportAddress &	localAddress
	)			`[protected, virtual]`

virtual bool SIPConnection::OnSendSDP	(	bool	isAnswerSDP,
		OpalRTPSessionManager &	rtpSessions,
		SDPSessionDescription &	sdpOut
	)			`[protected, virtual]`

virtual bool SIPConnection::OfferSDPMediaDescription	(	const OpalMediaType &	mediaType,
		unsigned	sessionID,
		OpalRTPSessionManager &	rtpSessions,
		SDPSessionDescription &	sdpOut
	)			`[protected, virtual]`

virtual bool SIPConnection::AnswerSDPMediaDescription	(	const SDPSessionDescription &	sdpIn,
		unsigned	sessionIndex,
		SDPSessionDescription &	sdpOut
	)			`[protected, virtual]`