SIPTransaction Class Reference

A class holding one SIP transaction. More...

#include <yatesip.h>

Inheritance diagram for SIPTransaction:

Public Types
enum	State {   Invalid , Initial , Trying , Process ,   Retrans , Finish , Cleared }
enum	Processed { NoMatch , NoDialog , Matched }

Public Member Functions
	SIPTransaction (SIPMessage *message, SIPEngine *engine, bool outgoing=true, bool *autoChangeParty=0)
	SIPTransaction (const SIPTransaction &original, const String &tag)
virtual	~SIPTransaction ()
int	getState () const
bool	isActive () const
const SIPMessage *	initialMessage () const
const SIPMessage *	latestMessage () const
const SIPMessage *	recentMessage () const
SIPEngine *	getEngine () const
bool	isOutgoing () const
bool	isIncoming () const
bool	isInvite () const
bool	isReliable () const
const String &	getMethod () const
const String &	getURI () const
const String &	getBranch () const
const String &	getCallID () const
const String &	getDialogTag () const
void	setDialogTag (const char *tag=0)
void	setTransmit ()
void	setCleared ()
unsigned int	getTransCount () const
void	setTransCount (int count)
bool	autoAck () const
void	autoAck (bool setAuto)
void	requestAuth (const String &realm, const String &domain, bool stale, bool proxy=false)
int	authUser (String &user, bool proxy=false, GenObject *userData=0)
virtual Processed	processMessage (SIPMessage *message, const String &branch)
virtual void	processMessage (SIPMessage *message)
virtual SIPEvent *	getEvent (bool pendingOnly=false, u_int64_t time=0)
bool	setResponse () const
bool	setResponse (int code, const char *reason=0)
void	setResponse (SIPMessage *message)
int	getResponseCode () const
bool	setAcknowledge (MimeBody *ackBody=0)
void	msgTransmitFailed (SIPMessage *msg)
void	setUserData (void *data)
void *	getUserData () const
void	setSilent ()
const String &	traceId () const
Public Member Functions inherited from RefObject
	RefObject ()
virtual	~RefObject ()
virtual void *	getObject (const String &name) const
virtual bool	alive () const
bool	ref ()
bool	deref ()
int	refcount () const
virtual void	destruct ()
Public Member Functions inherited from GenObject
	GenObject ()
virtual	~GenObject ()
virtual const String &	toString () const
NamedCounter *	getObjCounter () const
NamedCounter *	setObjCounter (NamedCounter *counter)

Static Public Member Functions
static const char *	stateName (int state)
Static Public Member Functions inherited from RefObject
static bool	alive (const RefObject *obj)
static bool	efficientIncDec ()
Static Public Member Functions inherited from GenObject
static void *	getObject (const String &name, const GenObject *obj)
static bool	getObjCounting ()
static void	setObjCounting (bool enable)
static NamedCounter *	getObjCounter (const String &name, bool create=true)
static ObjList &	getObjCounters ()

Protected Member Functions
	SIPTransaction (SIPTransaction &original, SIPMessage *answer)
virtual void	destroyed ()
bool	tryAutoAuth (SIPMessage *answer)
virtual SIPEvent *	getClientEvent (int state, int timeout)
virtual SIPEvent *	getServerEvent (int state, int timeout)
virtual void	processClientMessage (SIPMessage *message, int state)
virtual void	processServerMessage (SIPMessage *message, int state)
bool	changeState (int newstate)
void	setLatestMessage (SIPMessage *message=0)
void	setPendingEvent (SIPEvent *event=0, bool replace=false)
bool	isPendingEvent () const
void	setTimeout (u_int64_t delay=0, unsigned int count=1)
Protected Member Functions inherited from RefObject
virtual void	zeroRefs ()
bool	resurrect ()

Protected Attributes
bool	m_outgoing
bool	m_invite
bool	m_transmit
int	m_state
int	m_response
unsigned int	m_transCount
unsigned int	m_timeouts
u_int64_t	m_delay
u_int64_t	m_timeout
SIPMessage *	m_firstMessage
SIPMessage *	m_lastMessage
SIPEvent *	m_pending
SIPEngine *	m_engine
String	m_branch
String	m_callid
String	m_tag
void *	m_private
bool	m_autoChangeParty
bool	m_autoAck
bool	m_silent
String	m_traceId

Detailed Description

A class holding one SIP transaction.

All informaton related to a SIP transaction, starting with 1st message

Member Enumeration Documentation

Processed

enum Processed

Possible return values from processMessage()

State

enum State

Current state of the transaction

Constructor & Destructor Documentation

SIPTransaction() [1/3]

SIPTransaction	(	SIPMessage *	message,
		SIPEngine *	engine,
		bool	outgoing = true,
		bool *	autoChangeParty = 0 )

Constructor from first message

Parameters

message	A pointer to the initial message, should not be used afterwards as the transaction takes ownership
engine	A pointer to the SIP engine this transaction belongs
outgoing	True if this transaction is for an outgoing request
autoChangeParty	Optional pointer to auto change party flag (use engine's flag if missing)

Referenced by SIPTransaction(), and SIPTransaction().

SIPTransaction() [2/3]

SIPTransaction	(	const SIPTransaction &	original,
		const String &	tag )

Copy constructor to be used with forked INVITEs

Parameters

original	Original transaction that is to be copied
tag	Dialog tag for the new transaction

References SIPTransaction().

~SIPTransaction()

virtual ~SIPTransaction ( )

virtual

Destructor - clears all held objects

SIPTransaction() [3/3]

SIPTransaction ( SIPTransaction & original, SIPMessage * answer )

protected

Constructor from previous auto authenticated transaction. This is used only internally

Parameters

original	Original transaction that failed authentication
answer	SIP answer that creates the new transaction

References SIPTransaction().

Member Function Documentation

authUser()

int authUser	(	String &	user,
		bool	proxy = false,
		GenObject *	userData = 0 )

Detect the proper credentials for any user in the engine

Parameters

user	String to store the authenticated user name or user to look for (if not null on entry)
proxy	True to authenticate as proxy, false as user agent
userData	Pointer to an optional object that is passed back to checkUser

Returns

Age of the nonce if user matches, negative for a failure

References GenObject::GenObject().

autoAck() [1/2]

bool autoAck ( ) const

inline

Get the automatic UAC 2xx ACK generation flag

Returns

True if an ACK will be generated automatically for 2xx answers

autoAck() [2/2]

void autoAck ( bool setAuto )

inline

Set the automatic UAC 2xx ACK generation flag

Parameters

setAuto

True to automatically generate the ACK when receiving a 2xx answer

changeState()

bool changeState ( int newstate )

protected

Change the transaction state

Parameters

newstate

The desired new state

Returns

True if state change occured

Referenced by setCleared().

destroyed()

virtual void destroyed ( )

protectedvirtual

Pre-destruction notification used to clean up the transaction

Reimplemented from RefObject.

getBranch()

const String & getBranch ( ) const

inline

The Via branch that may uniquely identify this transaction

Returns

The branch parameter taken from the Via header

getCallID()

const String & getCallID ( ) const

inline

The call ID may identify this transaction

Returns

The Call-ID parameter taken from the message

getClientEvent()

virtual SIPEvent * getClientEvent ( int state, int timeout )

protectedvirtual

Get an event only for client transactions

Parameters

state	The current state of the transaction
timeout	If timeout occured, number of remaining timeouts, otherwise -1

Returns

A newly allocated event or NULL if none is needed

getDialogTag()

const String & getDialogTag ( ) const

inline

The dialog tag that may identify this transaction

Returns

The dialog tag parameter

getEngine()

SIPEngine * getEngine ( ) const

inline

The SIPEngine this transaction belongs to

getEvent()

virtual SIPEvent * getEvent ( bool pendingOnly = false, u_int64_t time = 0 )

virtual

Get an event for this transaction if any is available. It provides default handling for invalid states, otherwise calls the more specific protected version. You may override this method if you need processing of invalid states.

Parameters

pendingOnly	True to only return outgoing and pending events
time	Time to use in timeouts, zero to use system time

Returns

A newly allocated event or NULL if none is needed

getMethod()

const String & getMethod ( ) const

inline

The SIP method this transaction handles

References String::empty().

getResponseCode()

int getResponseCode ( ) const

inline

Retrieve the latest response code

Returns

Code of most recent response, zero if none is known

getServerEvent()

virtual SIPEvent * getServerEvent ( int state, int timeout )

protectedvirtual

Get an event only for server transactions.

Parameters

state	The current state of the transaction
timeout	If timeout occured, number of remaining timeouts, otherwise -1

Returns

A newly allocated event or NULL if none is needed

getState()

int getState ( ) const

inline

The current state of the transaction

Returns

The current state as one of the State enums

getTransCount()

unsigned int getTransCount ( ) const

inline

Get the transmission attempts count for non-reliable transports

Returns

Current number of transmission attempts

getURI()

const String & getURI ( ) const

inline

The SIP URI this transaction handles

References String::empty().

getUserData()

void * getUserData ( ) const

inline

Return the opaque user data

initialMessage()

const SIPMessage * initialMessage ( ) const

inline

The first message that created this transaction

isActive()

bool isActive ( ) const

inline

Check if the transaction is active for the upper layer

Returns

True if the transaction is active, false if it finished

isIncoming()

bool isIncoming ( ) const

inline

Check if this transaction was initiated locally or by the remote peer

Returns

True if the transaction was created by an incoming message

isInvite()

bool isInvite ( ) const

inline

Check if this transaction is an INVITE transaction or not

Returns

True if the transaction is an INVITE

isOutgoing()

bool isOutgoing ( ) const

inline

Check if this transaction was initiated by the remote peer or locally

Returns

True if the transaction was created by an outgoing message

isPendingEvent()

bool isPendingEvent ( ) const

inlineprotected

Check if there is a pending event waiting

Returns

True is there is a pending event

isReliable()

bool isReliable ( ) const

inline

Check if this transaction is handled by a reliable protocol

Returns

True if a reliable protocol (TCP, SCTP) is used

latestMessage()

const SIPMessage * latestMessage ( ) const

inline

The last message (re)sent by this transaction

msgTransmitFailed()

void msgTransmitFailed

(

SIPMessage *

msg

)

Message send failure notification

Parameters

msg	Failed message

processClientMessage()

virtual void processClientMessage ( SIPMessage * message, int state )

protectedvirtual

Process only the messages for client transactions

Parameters

message	A pointer to the message to process, should not be used afterwards if this method returned True
state	The current state of the transaction

processMessage() [1/2]

virtual void processMessage ( SIPMessage * message )

virtual

Process a message belonging to this transaction

Parameters

message

A pointer to the message to process, the caller must make sure it belongs to this transaction

processMessage() [2/2]

virtual Processed processMessage ( SIPMessage * message, const String & branch )

virtual

Check if a message belongs to this transaction and process it if so

Parameters

message	A pointer to the message to check, should not be used afterwards if this method returned Matched
branch	The branch parameter extracted from first Via header

Returns

Matched if the message was handled by this transaction, in which case it takes ownership over the message

processServerMessage()

virtual void processServerMessage ( SIPMessage * message, int state )

protectedvirtual

Process only the messages for server transactions

Parameters

message	A pointer to the message to process, should not be used afterwards if this method returned True
state	The current state of the transaction

recentMessage()

const SIPMessage * recentMessage ( ) const

inline

The most recent message handled by this transaction

requestAuth()

void requestAuth	(	const String &	realm,
		const String &	domain,
		bool	stale,
		bool	proxy = false )

Send back an authentication required response

Parameters

realm	Authentication realm to send in the answer
domain	Domain for which it will authenticate
stale	True if the previous password is valid but nonce is too old
proxy	True to authenticate as proxy, false as user agent

setAcknowledge()

bool setAcknowledge

(

MimeBody *

ackBody = 0

)

Transmit an ACK message in UAC mode

Parameters

ackBody

Optional ACK message body, consumed by the method

Returns

True if state was correct and the message was queued for transmission

setCleared()

void setCleared ( )

inline

Change transaction status to Cleared This method is not thread safe

References changeState().

setDialogTag()

void setDialogTag

(

const char *

tag = 0

)

Set a new dialog tag, optionally build a random one

Parameters

tag	New dialog tag, a null string will build a random tag

setLatestMessage()

void setLatestMessage ( SIPMessage * message = 0 )

protected

Set the latest message sent by this transaction

Parameters

message

Pointer to the latest message

setPendingEvent()

void setPendingEvent ( SIPEvent * event = 0, bool replace = false )

protected

Store a pending event to be picked up at the next getEvent() call

Parameters

event	Event to store
replace	True to replace any existing pending event

setResponse() [1/3]

bool setResponse

(

)

const

Checks if a response message can be sent

Returns

True if the transaction can send a response message

setResponse() [2/3]

bool setResponse	(	int	code,
		const char *	reason = 0 )

Creates and transmits a final response message

Parameters

code	Response code to send
reason	Human readable reason text (optional)

Returns

True if the message was queued for transmission

setResponse() [3/3]

void setResponse

(

SIPMessage *

message

)

Transmits a final response message

setSilent()

void setSilent

(

)

Silent this transaction

setTimeout()

void setTimeout ( u_int64_t delay = 0, unsigned int count = 1 )

protected

Set a repetitive timeout

Parameters

delay	How often (in microseconds) to fire the timeout
count	How many times to keep firing the timeout

setTransCount()

void setTransCount

(

int

count

)

Set the number of transmission attempts for non-reliable transports

Parameters

count

Transmission attempts, clamped between 2 and 10, negative values ignored

setTransmit()

void setTransmit ( )

inline

Set the (re)transmission flag that allows the latest outgoing message to be send over the wire

setUserData()

void setUserData ( void * data )

inline

Set an arbitrary pointer as user specific data

stateName()

static const char * stateName ( int state )

static

Get the name of a transaction state

traceId()

const String & traceId ( ) const

inlinevirtual

Trace ID of the transaction

Returns

Trace ID associated with this transaction

Reimplemented from GenObject.

tryAutoAuth()

bool tryAutoAuth ( SIPMessage * answer )

protected

Attempt to perform automatic client transaction authentication

Parameters

answer

SIP answer that creates the new transaction

Returns

True if current client processing must be abandoned

---

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

• yatesip.h