Yate
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes
SIPTransaction Class Reference

A class holding one SIP transaction. More...

#include <yatesip.h>

Inheritance diagram for SIPTransaction:
RefObject GenObject

List of all members.

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)
 SIPTransaction (const SIPTransaction &original, const String &tag)
virtual ~SIPTransaction ()
int getState () const
bool isActive () const
const SIPMessageinitialMessage () const
const SIPMessagelatestMessage () const
const SIPMessagerecentMessage () const
SIPEnginegetEngine () const
bool isOutgoing () const
bool isIncoming () const
bool isInvite () const
bool isReliable () const
const StringgetMethod () const
const StringgetURI () const
const StringgetBranch () const
const StringgetCallID () const
const StringgetDialogTag () const
void setDialogTag (const char *tag=0)
void setTransmit ()
void setCleared ()
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 SIPEventgetEvent (bool pendingOnly=false)
bool setResponse () const
bool setResponse (int code, const char *reason=0)
void setResponse (SIPMessage *message)
int getResponseCode () const
void setUserData (void *data)
void * getUserData () const

Static Public Member Functions

static const char * stateName (int state)

Protected Member Functions

 SIPTransaction (SIPTransaction &original, SIPMessage *answer)
virtual void destroyed ()
bool tryAutoAuth (SIPMessage *answer)
virtual SIPEventgetClientEvent (int state, int timeout)
virtual SIPEventgetServerEvent (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 Attributes

bool m_outgoing
bool m_invite
bool m_transmit
int m_state
int m_response
unsigned int m_timeouts
u_int64_t m_delay
u_int64_t m_timeout
SIPMessagem_firstMessage
SIPMessagem_lastMessage
SIPEventm_pending
SIPEnginem_engine
String m_branch
String m_callid
String m_tag
void * m_private

Detailed Description

A class holding one SIP transaction.

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


Member Enumeration Documentation

enum Processed

Possible return values from processMessage()

enum State

Current state of the transaction


Constructor & Destructor Documentation

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

Constructor from first message

Parameters:
messageA pointer to the initial message, should not be used afterwards as the transaction takes ownership
engineA pointer to the SIP engine this transaction belongs
outgoingTrue if this transaction is for an outgoing request
SIPTransaction ( const SIPTransaction original,
const String tag 
)

Copy constructor to be used with forked INVITEs

Parameters:
originalOriginal transaction that is to be copied
tagDialog tag for the new transaction
virtual ~SIPTransaction ( ) [virtual]

Destructor - clears all held objects

SIPTransaction ( SIPTransaction original,
SIPMessage answer 
) [protected]

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

Parameters:
originalOriginal transaction that failed authentication
answerSIP answer that creates the new transaction

Member Function Documentation

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

Detect the proper credentials for any user in the engine

Parameters:
userString to store the authenticated user name or user to look for (if not null on entry)
proxyTrue to authenticate as proxy, false as user agent
userDataPointer to an optional object that is passed back to SIPEngine::checkUser
Returns:
Age of the nonce if user matches, negative for a failure
bool changeState ( int  newstate) [protected]

Change the transaction state

Parameters:
newstateThe desired new state
Returns:
True if state change occured
virtual void destroyed ( ) [protected, virtual]

Pre-destruction notification used to clean up the transaction

Reimplemented from RefObject.

const String& getBranch ( ) const [inline]

The Via branch that may uniquely identify this transaction

Returns:
The branch parameter taken from the Via header
const String& getCallID ( ) const [inline]

The call ID may identify this transaction

Returns:
The Call-ID parameter taken from the message
virtual SIPEvent* getClientEvent ( int  state,
int  timeout 
) [protected, virtual]

Get an event only for client transactions

Parameters:
stateThe current state of the transaction
timeoutIf timeout occured, number of remaining timeouts, otherwise -1
Returns:
A newly allocated event or NULL if none is needed
const String& getDialogTag ( ) const [inline]

The dialog tag that may identify this transaction

Returns:
The dialog tag parameter
SIPEngine* getEngine ( ) const [inline]

The SIPEngine this transaction belongs to

virtual SIPEvent* getEvent ( bool  pendingOnly = false) [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:
pendingOnlyTrue to only return outgoing and pending events
Returns:
A newly allocated event or NULL if none is needed
const String& getMethod ( ) const [inline]

The SIP method this transaction handles

References String::empty().

int getResponseCode ( ) const [inline]

Retrieve the latest response code

Returns:
Code of most recent response, zero if none is known
virtual SIPEvent* getServerEvent ( int  state,
int  timeout 
) [protected, virtual]

Get an event only for server transactions.

Parameters:
stateThe current state of the transaction
timeoutIf timeout occured, number of remaining timeouts, otherwise -1
Returns:
A newly allocated event or NULL if none is needed
int getState ( ) const [inline]

The current state of the transaction

Returns:
The current state as one of the State enums
const String& getURI ( ) const [inline]

The SIP URI this transaction handles

References String::empty().

void* getUserData ( ) const [inline]

Return the opaque user data

const SIPMessage* initialMessage ( ) const [inline]

The first message that created this transaction

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
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
bool isInvite ( ) const [inline]

Check if this transaction is an INVITE transaction or not

Returns:
True if the transaction is an INVITE
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

Referenced by SIPEvent::isOutgoing().

bool isPendingEvent ( ) const [inline, protected]

Check if there is a pending event waiting

Returns:
True is there is a pending event
bool isReliable ( ) const [inline]

Check if this transaction is handled by a reliable protocol

Returns:
True if a reliable protocol (TCP, SCTP) is used
const SIPMessage* latestMessage ( ) const [inline]

The last message (re)sent by this transaction

virtual void processClientMessage ( SIPMessage message,
int  state 
) [protected, virtual]

Process only the messages for client transactions

Parameters:
messageA pointer to the message to process, should not be used afterwards if this method returned True
stateThe current state of the transaction
virtual Processed processMessage ( SIPMessage message,
const String branch 
) [virtual]

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

Parameters:
messageA pointer to the message to check, should not be used afterwards if this method returned Matched
branchThe 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
virtual void processMessage ( SIPMessage message) [virtual]

Process a message belonging to this transaction

Parameters:
messageA pointer to the message to process, the caller must make sure it belongs to this transaction
virtual void processServerMessage ( SIPMessage message,
int  state 
) [protected, virtual]

Process only the messages for server transactions

Parameters:
messageA pointer to the message to process, should not be used afterwards if this method returned True
stateThe current state of the transaction
const SIPMessage* recentMessage ( ) const [inline]

The most recent message handled by this transaction

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

Send back an authentication required response

Parameters:
realmAuthentication realm to send in the answer
domainDomain for which it will authenticate
staleTrue if the previous password is valid but nonce is too old
proxyTrue to authenticate as proxy, false as user agent
void setCleared ( ) [inline]

Change transaction status to Cleared This method is not thread safe

void setDialogTag ( const char *  tag = 0)

Set a new dialog tag, optionally build a random one

Parameters:
tagNew dialog tag, a null string will build a random tag
void setLatestMessage ( SIPMessage message = 0) [protected]

Set the latest message sent by this transaction

Parameters:
messagePointer to the latest message
void setPendingEvent ( SIPEvent event = 0,
bool  replace = false 
) [protected]

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

Parameters:
eventEvent to store
replaceTrue to replace any existing pending event
bool setResponse ( ) const

Checks if a response message can be sent

Returns:
True if the transaction can send a response message
bool setResponse ( int  code,
const char *  reason = 0 
)

Creates and transmits a final response message

Parameters:
codeResponse code to send
reasonHuman readable reason text (optional)
Returns:
True if the message was queued for transmission
void setResponse ( SIPMessage message)

Transmits a final response message

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

Set a repetitive timeout

Parameters:
delayHow often (in microseconds) to fire the timeout
countHow many times to keep firing the timeout
void setTransmit ( ) [inline]

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

void setUserData ( void *  data) [inline]

Set an arbitrary pointer as user specific data

static const char* stateName ( int  state) [static]

Get the name of a transaction state

bool tryAutoAuth ( SIPMessage answer) [protected]

Attempt to perform automatic client transaction authentication

Parameters:
answerSIP 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: