CallTracker Class Reference

#include <CallTracker.h>

Inheritance diagram for CallTracker:

Detailed Description

Class used to track all the forks associated with a given call.

For each new fork encountered, this class will allocate a SessionContext that implements the state machine required to follow the media offers/ answers and intervene when required to allow NAT traversal.

Public Member Functions

CallTracker (const ssize_t handle, const NatTraversalRules *pNatRules, MediaRelay *pMediaRelayToUse, const RegistrationDB *pRegistrationDB, NatMaintainer *pNatMaintainer, UtlString instanceNameForRouteState)

virtual ~CallTracker ()

bool notifyIncomingDialogFormingInvite (SipMessage &request, RouteState &routeState, const EndpointDescriptor *&prCaller, const EndpointDescriptor *&prCallee)

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

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

bool handleCleanUpTimerTick (void)

bool getSessionContextHandle (const RouteState &routeState, UtlString &handle) const

UtlContainableType getContainableType (void) const

unsigned hash () const

int compareTo (UtlContainable const *rhsContainable) const

virtual void reportSessionContextReadyForDeletion (const UtlString &sessionContextHandle)

< Class type used for runtime checking

Static Public Attributes

static const UtlContainableType TYPE = "CallTracker"

Private Member Functions

bool generateSessionContextHandleFromRequest (UtlString &handle)

SessionContext * getSessionContextFromHandle (const UtlString &sessionContextHandle) const

SessionContext * createSessionContextAndSetHandle (const SipMessage &request, RouteState &routeState, bool bTrackBranchId, UtlString &sessionContextHandle)

bool setSessionContextHandle (RouteState &routeState, const UtlString &handle) const

bool unsetSessionContextHandle (RouteState &routeState) const

bool setSessionHandleInVia (SipMessage &message, int viaIndex, const UtlString &sessionHandle) const

bool getSessionHandleFromVia (const SipMessage &message, int viaIndex, UtlString &sessionHandle) const

SessionContext * getSessionContextFromVia (const SipMessage &message, int viaIndex) const

bool removeSessionHandleFromVias (SipMessage &message, const UtlString &sessionHandleToRemove) const

bool getBranchId (const SipMessage &message, int viaIndex, UtlString &branchId) const

void deleteSessionContextsReadyForDeletion (void)

Private Attributes

ssize_t mHandle

CallTracker handle.

const NatTraversalRules * mpNatTraversalRules

pointer to the NAT Traversal Rules object which holds the NAT traversal feature configuration information

MediaRelay * mpMediaRelayToUse

Pointer to object that abstracts the Media Relay.

const RegistrationDB * mpRegistrationDB

Pointer to registration DB used in some instances to resolve the location of certain endpoints.

UtlHashMap mSessionContextsMap

Map that holds the SessionContext objects allocated by the CallTracker. Map is indexed by SessionContextHandles.

UtlHashMap mBranchIdToSessionHandleMap

Map that maps BranchIds to the handle of the SessionContext that can handle the request or response that bears the branchId.

UtlHashMap mSdpLibrary

Map that holds original SDP bodies before they got modified by the NAT traveral feature. The map is indexed by SessionContext handles.

UtlString mInstanceNameForRouteState

Auth Plugin instance name to use when encoding parameters in a RouteStata.

ssize_t mNumberOfTicksWithoutActiveDialogs

Counts the number of times we received a call to handleCleanUpTimerTick() while not having any allocated SessionContexts.

NatMaintainer * mpNatMaintainer

Pointer to NatMaintainer instance. Will be used to report calls established by Remote NATed endpoints to ensure that pinholes to them are properly maintained.

TransportData * mpCallerPinholeInformation

remembers the public IP address and port number that we have asked the NatMaintainer to maintain open. Set to NULL if the caller's pinhole is not being maintained.

PID mPid

Id of currently running process.

SdpBody * mpSavedOriginalSdpOfferCopy

vector< UtlString > mListOfSessionContextsReadyForDeletion

Static Private Attributes

static ssize_t sNextAvailableSessionContextHandle = 0

Static used to generate process-wide session context handles.

Friends

class CallTrackerTest

class NatTraversalAgentTest

Constructor & Destructor Documentation

CallTracker	(	const ssize_t	handle,
		const NatTraversalRules *	pNatRules,
		MediaRelay *	pMediaRelayToUse,
		const RegistrationDB *	pRegistrationDB,
		NatMaintainer *	pNatMaintainer,
		UtlString	instanceNameForRouteState
	)

~CallTracker ( ) [virtual]

Member Function Documentation

bool notifyIncomingDialogFormingInvite	(	SipMessage &	request,
		RouteState &	routeState,
		const EndpointDescriptor *&	prCaller,
		const EndpointDescriptor *&	prCallee
	)

Method to be called to notify the CallTracker that a dialog forming-request has been seen. This method allows the CallTracker to initialize internal data structures to be ready to track that fork of the call. It also returns EndpointDescriptors for both the Caller and the Callee back to the the method's caller.

Note:: This method is used to let the CallTracker prepare itself to track a fork but this method does not affect the CallTracker's state machine. The handleRequest() still needs to be called for that request.

Parameters:

`[in]`	request	- dialog-forming request
`[in]`	routeState	- route state information associated with the request
`[out]`	prCaller	- will hold a pointer to caller's EndpointDescriptor
`[out]`	prCallee	- will hold a pointer to callee's EndpointDescriptor

Returns:: - true if request was processed properly.

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

Method to be called to notify the CallTracker that a request belonging to the call being tracked has arrived. This method must be called by the owner for *each and every* request of the tracked call. The CallTracker will run the request through its state machines and adjust it for NAT traversal as required.

Parameters:

`[in]`	message	- request to process
`[in]`	address	- ip address to which request will be sent
`[in]`	port	- port to which request will be sent

Returns:: - true if request was processed properly.

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

Method to be called to notify the CallTracker that a response belonging to the call being tracked by the CallTracker has arrived. This method must be called by the owner for *each and every* response of the tracked call. The CallTracker will run the response through its state machines and adjust it for NAT traversal as required.

Parameters:

`[in]`	message	- response to process
`[in]`	address	- ip address to which response will be sent
`[in]`	port	- port to which response will be sent

bool handleCleanUpTimerTick ( void )

Method to notify that CallTracker that a cleanup timer has just ticked. The CallTracker will clean up stale resources if they have not been utilized for a while.

Returns:: - true when the CallTracker has finished its job and can be deleted.

bool getSessionContextHandle	(	const RouteState &	routeState,
		UtlString &	handle
	)			const

Method used to get the handle to a SessionContext based on the supplied route state.

Parameters:

`[in]`	routeState	- route state to use to derive SessionContext handle
`[out]`	handle	- string that will receive handle if found

Returns:: - true if a handle was found

UtlContainableType getContainableType ( void ) const [virtual]

Implements UtlContainable.

unsigned hash ( ) const [virtual]

Implements UtlContainable.

int compareTo ( UtlContainable const * rhsContainable ) const [virtual]

Implements UtlContainable.

void reportSessionContextReadyForDeletion ( const UtlString & sessionContextHandle ) [virtual]

< Class type used for runtime checking

note: see class CallTrackerInterfaceForSessionContext for details

Implements CallTrackerInterfaceForSessionContext.

bool generateSessionContextHandleFromRequest ( UtlString & handle ) [private]

Generates a process-wide unique SessionContext handle

Parameters:

[out] handle - generated handle

Returns:: - true if handle was generated successfully; otherwise false

SessionContext * getSessionContextFromHandle ( const UtlString & sessionContextHandle ) const [private]

Retrieves the SessionContext object, provided its handle

Parameters:

[in] sessionContextHandle - handle of SessionContext object to retrieve

Returns:: - SessionContext pointer if found, otherwise 0

SessionContext * createSessionContextAndSetHandle	(	const SipMessage &	request,
		RouteState &	routeState,
		bool	bTrackBranchId,
		UtlString &	sessionContextHandle
	)			`[private]`

Instantiates a new SessionContext handle to track a new call fork and encode its handle in the provided routeState.

Parameters:

`[in]`	request	- request that mandates the creation of the SessionContext
`[in]`	routeState	- route state in which to encode the SessionContext handle
`[in]`	bTrackBranchId	- indicates whether the branch Id of the request should be tracked -see not
`[out]`	sessionContextHandle	- handle given to newly created SessionContext

Returns:: - SessionContext pointer if created successfully, otherwise 0

Note: Normally, the CallTracker dispatches an incoming response to the correct SessionContext handle by extracting the SessionContext handle it carries in its topmost Via. Unfortunately, in some cases where the sipXproxy forks the dialog-forming INVITE and waits for the best response and that 'best response' ends up being a final failure response, sipXproxy strips the SessionContext handle contained in the Via which leaves CallTracker without the information it needs to dispatch it to the correct SessionContext. One such scenario is as follows: UserA calls UserB. UserA hangs up before UserB had a chance to answer. The final failure response sent to UserA to terminate the INVITE transaction will not carry the SessionContext handle in the Via. The root cause of this behavior is still unknown but is suspected to be a bug inside SipTransaction. To get around the problem, the CallTracker maintains a list that maps branch Id of dialog-forming requests to Session Context handles that it will fallback to whenever it cannot find SessionContext handles in the topmost Via. The mapping of branch Ids to SessionContext handles is governed by the bTrackBranchId flag.

bool setSessionContextHandle	(	RouteState &	routeState,
		const UtlString &	handle
	)			const `[private]`

Encodes SessionContext handle in the provided RouteState object

Parameters:

`[in]`	routeState	- RouteState object in which to encode the handle
`[in]`	handle	- handle to encode in RouteState

Returns:: - true if operation succeeded

bool unsetSessionContextHandle ( RouteState & routeState ) const [private]

Removes an encoded SessionContext handle from a route state. This method essentially undoes setSessionContextHandle().

Parameters:

[in] routeState - RouteState object from which to remove handle

Returns:: - true if operation succeeded

bool setSessionHandleInVia	(	SipMessage &	message,
		int	viaIndex,
		const UtlString &	sessionHandle
	)			const `[private]`

Adds an 'id' tag to the specified Via subfield containing the sessionHandle as a value

Parameters:

`[in]`	message	- message that contains Via to add 'id' tag to.
`[in]`	viaIndex	- index of Via subfield that will receive tag
`[in]`	sessionHandle-	handle to use as value for 'id' tag.

Returns:: - true if tag was added; false otherwise.

bool getSessionHandleFromVia	(	const SipMessage &	message,
		int	viaIndex,
		UtlString &	sessionHandle
	)			const `[private]`

Gets the 'id' tag containing a sessionHandle from the specified Via subfield

Parameters:

`[in]`	message	- message that contains Via
`[in]`	viaIndex	- index of Via subfield from which 'id' tag will be taken
`[out]`	sessionHandle	- will be set to handle value contained in Via's 'id' tag

Returns:: - true if sessionHandle was found; false otherwise.

SessionContext * getSessionContextFromVia	(	const SipMessage &	message,
		int	viaIndex
	)			const `[private]`

Gets the SessionContext instance mapped to the sessionHandle contained in the specified Via's 'id' tag.

Parameters:

`[in]`	message	- message that contains Via
`[in]`	viaIndex	- index of Via subfield from which 'id' tag willbe taken

Returns:: - NULL if SessionContext instance could not be determined; pointer to instance otherwise.

bool removeSessionHandleFromVias	(	SipMessage &	message,
		const UtlString &	sessionHandleToRemove
	)			const `[private]`

Removes the first encountered 'id' via tag conataining the specified session context handle. VIa's 'id' tag.

Parameters:

`[in]`	message	- message that contains Vias
`[in]`	sessionHandleToRemove	- as name says

Returns:: - true if Session Context handle could be removed.

bool getBranchId	(	const SipMessage &	message,
		int	viaIndex,
		UtlString &	branchId
	)			const `[private]`

Extracts the branch Id from a Via

Parameters:

`[in]`	message	- message that contains Via from which to extract branch Id
`[in]`	index	- index of Via to extract branch Id from (0 means top Via)
`[out]`	branchId	- string that will receive the branch Id if found

Returns:: - true if branch Id was found; false otherwise.

void deleteSessionContextsReadyForDeletion ( void ) [private]

Enforces the deletion of the SessionContext objects whose handles are found in mListOfSessionContextsReadyForDeletion.

Friends And Related Function Documentation

friend class CallTrackerTest [friend]

friend class NatTraversalAgentTest [friend]

Member Data Documentation

const UtlContainableType TYPE = "CallTracker" [static]

Reimplemented from UtlContainable.

ssize_t mHandle [private]

CallTracker handle.

const NatTraversalRules* mpNatTraversalRules [private]

pointer to the NAT Traversal Rules object which holds the NAT traversal feature configuration information

MediaRelay* mpMediaRelayToUse [private]

Pointer to object that abstracts the Media Relay.

const RegistrationDB* mpRegistrationDB [private]

Pointer to registration DB used in some instances to resolve the location of certain endpoints.

UtlHashMap mSessionContextsMap [private]

Map that holds the SessionContext objects allocated by the CallTracker. Map is indexed by SessionContextHandles.

UtlHashMap mBranchIdToSessionHandleMap [private]

Map that maps BranchIds to the handle of the SessionContext that can handle the request or response that bears the branchId.

UtlHashMap mSdpLibrary [private]

Map that holds original SDP bodies before they got modified by the NAT traveral feature. The map is indexed by SessionContext handles.

UtlString mInstanceNameForRouteState [private]

Auth Plugin instance name to use when encoding parameters in a RouteStata.

ssize_t mNumberOfTicksWithoutActiveDialogs [private]

Counts the number of times we received a call to handleCleanUpTimerTick() while not having any allocated SessionContexts.

ssize_t sNextAvailableSessionContextHandle = 0 [static, private]

Static used to generate process-wide session context handles.

NatMaintainer* mpNatMaintainer [private]

Pointer to NatMaintainer instance. Will be used to report calls established by Remote NATed endpoints to ensure that pinholes to them are properly maintained.

TransportData* mpCallerPinholeInformation [private]

remembers the public IP address and port number that we have asked the NatMaintainer to maintain open. Set to NULL if the caller's pinhole is not being maintained.

PID mPid [private]

Id of currently running process.

SdpBody* mpSavedOriginalSdpOfferCopy [private]

vector<UtlString> mListOfSessionContextsReadyForDeletion [private]

CallTracker Class Reference

Detailed Description

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Friends

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

Online Library Docs

sipXecs home page


Public Member Functions
	CallTracker (const ssize_t handle, const NatTraversalRules pNatRules, MediaRelay pMediaRelayToUse, const RegistrationDB pRegistrationDB, NatMaintainer pNatMaintainer, UtlString instanceNameForRouteState)
virtual	~CallTracker ()
bool	notifyIncomingDialogFormingInvite (SipMessage &request, RouteState &routeState, const EndpointDescriptor &prCaller, const EndpointDescriptor &prCallee)
bool	handleRequest (SipMessage &message, const char *address, int port)
void	handleResponse (SipMessage &message, const char *address, int port)
bool	handleCleanUpTimerTick (void)
bool	getSessionContextHandle (const RouteState &routeState, UtlString &handle) const
UtlContainableType	getContainableType (void) const
unsigned	hash () const
int	compareTo (UtlContainable const *rhsContainable) const
virtual void	reportSessionContextReadyForDeletion (const UtlString &sessionContextHandle)
	< Class type used for runtime checking
Static Public Attributes
static const UtlContainableType	TYPE = "CallTracker"
Private Member Functions
bool	generateSessionContextHandleFromRequest (UtlString &handle)
SessionContext *	getSessionContextFromHandle (const UtlString &sessionContextHandle) const
SessionContext *	createSessionContextAndSetHandle (const SipMessage &request, RouteState &routeState, bool bTrackBranchId, UtlString &sessionContextHandle)
bool	setSessionContextHandle (RouteState &routeState, const UtlString &handle) const
bool	unsetSessionContextHandle (RouteState &routeState) const
bool	setSessionHandleInVia (SipMessage &message, int viaIndex, const UtlString &sessionHandle) const
bool	getSessionHandleFromVia (const SipMessage &message, int viaIndex, UtlString &sessionHandle) const
SessionContext *	getSessionContextFromVia (const SipMessage &message, int viaIndex) const
bool	removeSessionHandleFromVias (SipMessage &message, const UtlString &sessionHandleToRemove) const
bool	getBranchId (const SipMessage &message, int viaIndex, UtlString &branchId) const
void	deleteSessionContextsReadyForDeletion (void)
Private Attributes
ssize_t	mHandle
	CallTracker handle.
const NatTraversalRules *	mpNatTraversalRules
	pointer to the NAT Traversal Rules object which holds the NAT traversal feature configuration information
MediaRelay *	mpMediaRelayToUse
	Pointer to object that abstracts the Media Relay.
const RegistrationDB *	mpRegistrationDB
	Pointer to registration DB used in some instances to resolve the location of certain endpoints.
UtlHashMap	mSessionContextsMap
	Map that holds the SessionContext objects allocated by the CallTracker. Map is indexed by SessionContextHandles.
UtlHashMap	mBranchIdToSessionHandleMap
	Map that maps BranchIds to the handle of the SessionContext that can handle the request or response that bears the branchId.
UtlHashMap	mSdpLibrary
	Map that holds original SDP bodies before they got modified by the NAT traveral feature. The map is indexed by SessionContext handles.
UtlString	mInstanceNameForRouteState
	Auth Plugin instance name to use when encoding parameters in a RouteStata.
ssize_t	mNumberOfTicksWithoutActiveDialogs
	Counts the number of times we received a call to handleCleanUpTimerTick() while not having any allocated SessionContexts.
NatMaintainer *	mpNatMaintainer
	Pointer to NatMaintainer instance. Will be used to report calls established by Remote NATed endpoints to ensure that pinholes to them are properly maintained.
TransportData *	mpCallerPinholeInformation
	remembers the public IP address and port number that we have asked the NatMaintainer to maintain open. Set to NULL if the caller's pinhole is not being maintained.
PID	mPid
	Id of currently running process.
SdpBody *	mpSavedOriginalSdpOfferCopy
vector< UtlString >	mListOfSessionContextsReadyForDeletion
Static Private Attributes
static ssize_t	sNextAvailableSessionContextHandle = 0
	Static used to generate process-wide session context handles.
Friends
class	CallTrackerTest
class	NatTraversalAgentTest