DialogTracker Class Reference

#include <DialogTracker.h>

Inheritance diagram for DialogTracker:

List of all members.

---

Detailed Description

The DialogTracker class implements the state machine that knows how to track a dialog's answer/offer and intervene when necessary to facilitatre NAT traversal.

This includes adjusting SDP and configuring the Media Relay when needed.

Public Member Functions
	DialogTracker (const UtlString &handle, const UtlString &systemIdentificationString, SessionContextInterfaceForDialogTracker *pOwningSessionContext)
	DialogTracker (const DialogTracker &referenceDialogTracker, const UtlString &newHandle)
virtual	~DialogTracker ()
virtual UtlContainableType	getContainableType (void) const
virtual unsigned	hash () const
virtual int	compareTo (UtlContainable const *rhsContainable) const
bool	handleRequest (SipMessage &message, const char *address, int port, bool bFromCallerToCallee)
void	handleResponse (SipMessage &message, const char *address, int port)
void	handleCleanUpTimerTick (void)
const UtlString &	getHandle (void) const
void	setHandle (const UtlString &newHandle)
const DialogTrackerState *	GetCurrentState () const
	Returns the current state, as required by UtlFsm's StateAlg.
void	SetCurrentState (const DialogTrackerState *pState)
	Sets the current state, as required by UtlFsm's StateAlg.
const char *	name (void) const
void	resetTimerTickCounter (void)
ssize_t	incrementTimerTickCounter (void)
ssize_t	getTimerTickCounter (void) const
bool	getDialogEstablishedFlag (void) const
void	setDialogEstablishedFlag (void)
void	clearDialogEstablishedFlag (void)
bool	getMediaRelayRequiredFlag (void) const
void	setMediaRelayRequiredFlag (void)
void	clearMediaRelayRequiredFlag (void)
bool	getNonIntialOfferAnswerExchangeDoneFlag (void) const
void	modifyNonIntialOfferAnswerExchangeDoneFlag (bool newValue)
size_t	getNumberOfMediaDescriptors (void) const
MediaDescriptor *	getModifiableMediaDescriptor (size_t descriptorIndex)
const MediaDescriptor *	getReadOnlyMediaDescriptor (size_t descriptorIndex)
void	appendMediaDescriptor (MediaDescriptor *pMediaDescriptor)
bool	allocateMediaRelaySession (tMediaRelayHandle &relayHandle, int &callerRelayRtpPort, int &calleeRelayRtpPort)
tMediaRelayHandle	cloneMediaRelaySession (tMediaRelayHandle &relayHandleToClone, bool doSwapCallerAndCallee)
bool	deallocateMediaRelaySession (const tMediaRelayHandle &relayHandle)
void	deallocateAndClearAllMediaRelaySessions (bool bDeallocateTentativeInitialRelays=true, bool bDeallocateTentativeNonInitialRelays=true, bool bDeallocateCurrentRelays=true)
bool	wasMediaTrafficSeenInLastNSeconds (unsigned long numberOfSeconds)
tMediaRelayHandle	getOurMediaRelayHandleEncodedInSdp (const SdpBody *pSdpBody, int mediaIndex) const
bool	hasSdpAlreadyBeenPatchedByUs (SipMessage &message, int mediaIndex) const
bool	hasSdpAlreadyBeenPatchedByUs (const SdpBody *pSdpBody, int mediaIndex) const
void	setTransactionDirectionality (TransactionDirectionality directionality)
TransactionDirectionality	getTransactionDirectionality (void) const
void	markRequestAsHandledByUs (SipMessage &request)
bool	isRequestAlreadyHandledByUs (const SipMessage &request) const
bool	isRequestAlreadyHandledByOther (const SipMessage &request) const
bool	isRequestAlreadyHandledByAnyone (const SipMessage &request) const
bool	isARetransmittedRequest (const SipMessage &request)
bool	isARetransmittedResponse (const SipMessage &response)
void	restoreSdpBodyOfRetransmittedRequest (SipMessage &request)
void	restoreSdpBodyOfRetransmittedResponse (SipMessage &response)
bool	doesEndpointsLocationImposeMediaRelay (void) const
void	ProcessMediaOffer (SipMessage &message, OfferAnswerPattern offerAnswerPattern)
	Performs the necessary actions and modifications to ensure that SDP Offer produces a media session that can traverse NATs.
void	ProcessMediaAnswer (SipMessage &message, OfferAnswerPattern offerAnswerPattern)
	Performs the necessary actions and modifications to ensure that SDP Answer produces a media session that can traverse NATs.
void	promoteTentativeMediaRelaySessionsToCurrent (void)
	The processing of Offers and Answers haas caused the allocation of tentative MediaRelaySessions to be used if the INVITE proves to be successful (accepted with 200 OK).
EndpointRole	EstablishEndpointRole (TransactionDirectionality directionality, bool bMessageIsResponse) const
	Returns the role (CALLER or CALLEE of the originator the message currently being processed.
void	reportDialogCompleted (void)
	Notification from the state machine that the dialog is completed and that it can delete itself.
bool	setMediaRelayDirectionMode (const tMediaRelayHandle &relayHandle, MediaDirectionality mediaRelayDirectionMode, EndpointRole endpointRole)
	Configures the directionality of the media relay.
bool	linkFarEndMediaRelayPortToRequester (const tMediaRelayHandle &relayHandle, const MediaDescriptor *pMediaDescriptor, EndpointRole endpointRoleOfRequester)
	Establishes the requester as the media destination for the far-end's media relay port.
bool	getMediaRelayAddressToUseInSdp (UtlString &mediaRelayAddressToUse, EndpointRole endpointRole) const
	Computes the media relay IP address to use when patching SDP originating from endpoint designated by endpointRole param.
bool	patchSdp (SdpBody *pSdpBody, int mediaIndex, int rtpPort, tMediaRelayHandle relayHandle, const UtlString &mediaRelayAddressToUse)
	Modifies the supplied SDP body's media description section as specified by the 'mediaIndex' parameter with the media connection information provided.
void	savePatchedSdpPreview (SipMessage &sipMessage)
	Saves a copy of the SDP body contained in the supplied message.
void	applyPatchedSdpPreview (SipMessage &sipMessage)
	Applies the patched SDP preview previously saved by the savePatchedSdpPreview() method to the supplied message.
Static Public Member Functions
static void	removeUnwantedElements (SipMessage &request)
	Removes all the elements that may impair NAT traversal from the message.
Static Public Attributes
static const UtlContainableType	TYPE = "DialogTracker"
static WaitingForInvite *	pWaitingForInvite = 0
	< Class type used for runtime checking
static WaitingForAckForInvite *	pWaitingForAckForInvite = 0
static TimeBoundState *	pTimeBoundState = 0
static Moribund *	pMoribund = 0
static Negotiating *	pNegotiating = 0
static WaitingForMediaOffer *	pWaitingForMediaOffer = 0
static WaitingFor200OkWithMediaOffer *	pWaitingFor200OkWithMediaOffer = 0
static WaitingForMediaAnswer *	pWaitingForMediaAnswer = 0
static WaitingForAckWithAnswerForInvite *	pWaitingForAckWithAnswerForInvite = 0
static WaitingForPrackWithMediaAnswer *	pWaitingForPrackWithMediaAnswer = 0
static WaitingFor200OkForSlowStartPrack *	pWaitingFor200OkForSlowStartPrack = 0
static ProcessingPrack *	pProcessingPrack = 0
static WaitingForPrack *	pWaitingForPrack = 0
static WaitingFor200OkForPrack *	pWaitingFor200OkForPrack = 0
static WaitingFor200OkWithAnswerForPrack *	pWaitingFor200OkWithAnswerForPrack = 0
static ProcessingPrackWaitingForAckforInvite *	pProcessingPrackWaitingForAckforInvite = 0
Private Member Functions
void	initializeStatePointers (void)
Private Attributes
UtlString	mHandle
UtlString	mSystemIdentificationString
bool	mbMediaRelayRequired
TransactionDirectionality	mCurrentTransactionDirectionality
bool	mbDialogEstablished
bool	mbInitialDialogEstablished
const DialogTrackerState *	mpCurrentState
vector< MediaDescriptor * >	mMediaDescriptors
ssize_t	mTimerTickCounter
SessionContextInterfaceForDialogTracker *	pOwningSessionContext
RequestRetransmissionDescriptor	mRequestRetransmissionDescriptor
ResponseRetransmissionDescriptor	mResponseRetransmissionDescriptor
bool	mbNonIntialOfferAnswerExchangeDoneFlag
SdpBody *	mpCopyOfPatchedSdpBody
Friends
class	DialogTrackerTest
Classes
class	RequestRetransmissionDescriptor
class	ResponseRetransmissionDescriptor
class	RetransmissionDescriptor

---

Constructor & Destructor Documentation

DialogTracker	(	const UtlString &	handle,
		const UtlString &	systemIdentificationString,
		SessionContextInterfaceForDialogTracker *	pOwningSessionContext
	)

DialogTracker	(	const DialogTracker &	referenceDialogTracker,
		const UtlString &	newHandle
	)

~DialogTracker

(

)

[virtual]

---

Member Function Documentation

UtlContainableType getContainableType

(

void

)

const [virtual]

Implements UtlContainable.

unsigned hash

(

)

const [virtual]

Implements UtlContainable.

int compareTo

(

UtlContainable const *

rhsContainable

)

const [virtual]

Implements UtlContainable.

bool handleRequest	(	SipMessage &	message,
		const char *	address,
		int	port,
		bool	bFromCallerToCallee
	)

void handleResponse	(	SipMessage &	message,
		const char *	address,
		int	port
	)

void handleCleanUpTimerTick

(

void

)

const UtlString& getHandle

(

void

)

const [inline]

void setHandle

(

const UtlString &

newHandle

)

[inline]

const DialogTrackerState * GetCurrentState

(

)

const

Returns the current state, as required by UtlFsm's StateAlg.

void SetCurrentState

(

const DialogTrackerState *

pState

)

Sets the current state, as required by UtlFsm's StateAlg.

const char * name

(

void

)

const

void resetTimerTickCounter

(

void

)

ssize_t incrementTimerTickCounter

(

void

)

ssize_t getTimerTickCounter

(

void

)

const

bool getDialogEstablishedFlag

(

void

)

const

void setDialogEstablishedFlag

(

void

)

void clearDialogEstablishedFlag

(

void

)

bool getMediaRelayRequiredFlag

(

void

)

const

void setMediaRelayRequiredFlag

(

void

)

void clearMediaRelayRequiredFlag

(

void

)

bool getNonIntialOfferAnswerExchangeDoneFlag

(

void

)

const

void modifyNonIntialOfferAnswerExchangeDoneFlag

(

bool

newValue

)

size_t getNumberOfMediaDescriptors

(

void

)

const

MediaDescriptor * getModifiableMediaDescriptor

(

size_t

descriptorIndex

)

const MediaDescriptor * getReadOnlyMediaDescriptor

(

size_t

descriptorIndex

)

void appendMediaDescriptor

(

MediaDescriptor *

pMediaDescriptor

)

bool allocateMediaRelaySession	(	tMediaRelayHandle &	relayHandle,
		int &	callerRelayRtpPort,
		int &	calleeRelayRtpPort
	)

tMediaRelayHandle cloneMediaRelaySession	(	tMediaRelayHandle &	relayHandleToClone,
		bool	doSwapCallerAndCallee
	)

bool deallocateMediaRelaySession

(

const tMediaRelayHandle &

relayHandle

)

void deallocateAndClearAllMediaRelaySessions	(	bool	bDeallocateTentativeInitialRelays = true,
		bool	bDeallocateTentativeNonInitialRelays = true,
		bool	bDeallocateCurrentRelays = true
	)

bool wasMediaTrafficSeenInLastNSeconds

(

unsigned long

numberOfSeconds

)

tMediaRelayHandle getOurMediaRelayHandleEncodedInSdp	(	const SdpBody *	pSdpBody,
		int	mediaIndex
	)			const

bool hasSdpAlreadyBeenPatchedByUs	(	SipMessage &	message,
		int	mediaIndex
	)			const

bool hasSdpAlreadyBeenPatchedByUs	(	const SdpBody *	pSdpBody,
		int	mediaIndex
	)			const

void setTransactionDirectionality

(

TransactionDirectionality

directionality

)

TransactionDirectionality getTransactionDirectionality

(

void

)

const

void markRequestAsHandledByUs

(

SipMessage &

request

)

bool isRequestAlreadyHandledByUs

(

const SipMessage &

request

)

const

bool isRequestAlreadyHandledByOther

(

const SipMessage &

request

)

const

bool isRequestAlreadyHandledByAnyone

(

const SipMessage &

request

)

const

bool isARetransmittedRequest

(

const SipMessage &

request

)

bool isARetransmittedResponse

(

const SipMessage &

response

)

void restoreSdpBodyOfRetransmittedRequest

(

SipMessage &

request

)

void restoreSdpBodyOfRetransmittedResponse

(

SipMessage &

response

)

bool doesEndpointsLocationImposeMediaRelay

(

void

)

const

void ProcessMediaOffer	(	SipMessage &	message,
		OfferAnswerPattern	offerAnswerPattern
	)

Performs the necessary actions and modifications to ensure that SDP Offer produces a media session that can traverse NATs.

void ProcessMediaAnswer	(	SipMessage &	message,
		OfferAnswerPattern	offerAnswerPattern
	)

Performs the necessary actions and modifications to ensure that SDP Answer produces a media session that can traverse NATs.

void promoteTentativeMediaRelaySessionsToCurrent

(

void

)

The processing of Offers and Answers haas caused the allocation of tentative MediaRelaySessions to be used if the INVITE proves to be successful (accepted with 200 OK).

This method is called after an INVITE succeeds to promote the tentatively allcoated MediaRelaySessions into the obes that actually get used to relay the newly negotiated media session.

EndpointRole EstablishEndpointRole	(	TransactionDirectionality	directionality,
		bool	bMessageIsResponse
	)			const

Returns the role (CALLER or CALLEE of the originator the message currently being processed.

void reportDialogCompleted

(

void

)

Notification from the state machine that the dialog is completed and that it can delete itself.

The caller of this method MUST NOT invoke and further methods on this DialogTracker after having called this method.

bool setMediaRelayDirectionMode	(	const tMediaRelayHandle &	relayHandle,
		MediaDirectionality	mediaRelayDirectionMode,
		EndpointRole	endpointRole
	)

Configures the directionality of the media relay.

Note that the directionality specified in the 'mediaRelayDirectionMode' parameter is referenced from the caller.

bool linkFarEndMediaRelayPortToRequester	(	const tMediaRelayHandle &	relayHandle,
		const MediaDescriptor *	pMediaDescriptor,
		EndpointRole	endpointRoleOfRequester
	)

Establishes the requester as the media destination for the far-end's media relay port.

bool getMediaRelayAddressToUseInSdp	(	UtlString &	mediaRelayAddressToUse,
		EndpointRole	endpointRole
	)			const

Computes the media relay IP address to use when patching SDP originating from endpoint designated by endpointRole param.

Returns:

true if media relay's native IP address is to be used. false if media relay's public IP address is to be used

bool patchSdp	(	SdpBody *	pSdpBody,
		int	mediaIndex,
		int	rtpPort,
		tMediaRelayHandle	relayHandle,
		const UtlString &	mediaRelayAddressToUse
	)

Modifies the supplied SDP body's media description section as specified by the 'mediaIndex' parameter with the media connection information provided.

void savePatchedSdpPreview

(

SipMessage &

sipMessage

)

Saves a copy of the SDP body contained in the supplied message.

This method is intended to be used to save the content of an SDP body patched by the NAT traversal feature so that it can be re-applied to any subsequent message that carries same SDP as the supplied message. This helps meet the standards requirement that states that all SDP previews be identical.

void applyPatchedSdpPreview

(

SipMessage &

sipMessage

)

Applies the patched SDP preview previously saved by the savePatchedSdpPreview() method to the supplied message.

void removeUnwantedElements

(

SipMessage &

request

)

[static]

Removes all the elements that may impair NAT traversal from the message.

void initializeStatePointers

(

void

)

[private]

---

Friends And Related Function Documentation

friend class DialogTrackerTest [friend]

---

Member Data Documentation

const UtlContainableType TYPE = "DialogTracker" [static]

Reimplemented from UtlContainable.

WaitingForInvite * pWaitingForInvite = 0 [static]

< Class type used for runtime checking

WaitingForAckForInvite * pWaitingForAckForInvite = 0 [static]

TimeBoundState * pTimeBoundState = 0 [static]

Moribund * pMoribund = 0 [static]

Negotiating * pNegotiating = 0 [static]

WaitingForMediaOffer * pWaitingForMediaOffer = 0 [static]

WaitingFor200OkWithMediaOffer * pWaitingFor200OkWithMediaOffer = 0 [static]

WaitingForMediaAnswer * pWaitingForMediaAnswer = 0 [static]

WaitingForAckWithAnswerForInvite * pWaitingForAckWithAnswerForInvite = 0 [static]

WaitingForPrackWithMediaAnswer * pWaitingForPrackWithMediaAnswer = 0 [static]

WaitingFor200OkForSlowStartPrack * pWaitingFor200OkForSlowStartPrack = 0 [static]

ProcessingPrack * pProcessingPrack = 0 [static]

WaitingForPrack * pWaitingForPrack = 0 [static]

WaitingFor200OkForPrack * pWaitingFor200OkForPrack = 0 [static]

WaitingFor200OkWithAnswerForPrack * pWaitingFor200OkWithAnswerForPrack = 0 [static]

ProcessingPrackWaitingForAckforInvite * pProcessingPrackWaitingForAckforInvite = 0 [static]

UtlString mHandle [private]

UtlString mSystemIdentificationString [private]

bool mbMediaRelayRequired [private]

TransactionDirectionality mCurrentTransactionDirectionality [private]

bool mbDialogEstablished [private]

bool mbInitialDialogEstablished [private]

const DialogTrackerState* mpCurrentState [private]

vector<MediaDescriptor*> mMediaDescriptors [private]

ssize_t mTimerTickCounter [private]

SessionContextInterfaceForDialogTracker* pOwningSessionContext [private]

RequestRetransmissionDescriptor mRequestRetransmissionDescriptor [private]

ResponseRetransmissionDescriptor mResponseRetransmissionDescriptor [private]

bool mbNonIntialOfferAnswerExchangeDoneFlag [private]

SdpBody* mpCopyOfPatchedSdpBody [private]