# class SIPTransaction | A class holding one SIP transaction. More...
Full name | `TelEngine::SIPTransaction`
Definition | `#include <libs/ysip/yatesip.h>`
Inherits | TelEngine::RefObject [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Types

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

#### Public Methods

- SIPTransaction (SIPMessage* message, SIPEngine* engine, bool outgoing = true)
- SIPTransaction (const SIPTransaction& original, const String& tag)
- virtual ~SIPTransaction ()
- inline int getState () const
- inline bool isActive () const
- inline const SIPMessage* initialMessage () const
- inline const SIPMessage* latestMessage () const
- inline const SIPMessage* recentMessage () const
- inline SIPEngine* getEngine () const
- inline bool isOutgoing () const
- inline bool isIncoming () const
- inline bool isInvite () const
- inline bool isReliable () const
- inline const String& getMethod () const
- inline const String& getURI () const
- inline const String& getBranch () const
- inline const String& getCallID () const
- inline const String& getDialogTag () const
- void setDialogTag (const char* tag = 0)
- inline void setTransmit ()
- inline 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 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)
- inline int getResponseCode () const
- void msgTransmitFailed (SIPMessage* msg)
- inline void setUserData (void* data)
- inline void* getUserData () const

#### Public Static Methods

- static const char* stateName (int state)

#### Protected Methods

- 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)
- inline bool isPendingEvent () const
- void setTimeout (u_int64_t delay = 0, unsigned int count = 1)

#### Protected Members

- 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
- SIPMessage* m_firstMessage
- SIPMessage* m_lastMessage
- SIPEvent* m_pending
- SIPEngine* m_engine
- String m_branch
- String m_callid
- String m_tag
- void *m_private

## Detailed Description

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

enum State { Invalid, Initial, Trying, Process, Retrans, Finish, Cleared } | ### State

Current state of the transaction

enum Processed { NoMatch, NoDialog, Matched } | ### Processed

Possible return values from processMessage()

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

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

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

Copy constructor to be used with forked INVITEs

Parameters:

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

~SIPTransaction () | ### ~SIPTransaction

[virtual]

Destructor - clears all held objects

const char* stateName (int state) | ### stateName

[static]

Get the name of a transaction state

inline int getState () | ### getState

[const]

The current state of the transaction

Returns: The current state as one of the State enums

inline bool isActive () | ### isActive

[const]

Check if the transaction is active for the upper layer

Returns: True if the transaction is active, false if it finished

inline const SIPMessage* initialMessage () | ### initialMessage

[const]

The first message that created this transaction

inline const SIPMessage* latestMessage () | ### latestMessage

[const]

The last message (re)sent by this transaction

inline const SIPMessage* recentMessage () | ### recentMessage

[const]

The most recent message handled by this transaction

inline SIPEngine* getEngine () | ### getEngine

[const]

The SIPEngine this transaction belongs to

inline bool isOutgoing () | ### isOutgoing

[const]

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

Returns: True if the transaction was created by an outgoing message

inline bool isIncoming () | ### isIncoming

[const]

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

Returns: True if the transaction was created by an incoming message

inline bool isInvite () | ### isInvite

[const]

Check if this transaction is an INVITE transaction or not

Returns: True if the transaction is an INVITE

inline bool isReliable () | ### isReliable

[const]

Check if this transaction is handled by a reliable protocol

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

inline const String& getMethod () | ### getMethod

[const]

The SIP method this transaction handles

inline const String& getURI () | ### getURI

[const]

The SIP URI this transaction handles

inline const String& getBranch () | ### getBranch

[const]

The Via branch that may uniquely identify this transaction

Returns: The branch parameter taken from the Via header

inline const String& getCallID () | ### getCallID

[const]

The call ID may identify this transaction

Returns: The Call-ID parameter taken from the message

inline const String& getDialogTag () | ### getDialogTag

[const]

The dialog tag that may identify this transaction

Returns: The dialog tag parameter

void setDialogTag (const char* tag = 0) | ### setDialogTag

Set a new dialog tag, optionally build a random one

Parameters:

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

inline void setTransmit () | ### setTransmit

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

inline void setCleared () | ### setCleared

Change transaction status to Cleared This method is not thread safe

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

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

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

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 SIPEngine::checkUser

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

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

[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

void processMessage (SIPMessage* message) | ### processMessage

[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

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

[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

bool setResponse () | ### 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) | ### setResponse

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

void setResponse (SIPMessage* message) | ### setResponse

Transmits a final response message

inline int getResponseCode () | ### getResponseCode

[const]

Retrieve the latest response code

Returns: Code of most recent response, zero if none is known

void msgTransmitFailed (SIPMessage* msg) | ### msgTransmitFailed

Message send failure notification

Parameters:

msg | Failed message

inline void setUserData (void* data) | ### setUserData

Set an arbitrary pointer as user specific data

inline void* getUserData () | ### getUserData

[const]

Return the opaque user data

SIPTransaction (SIPTransaction& original, SIPMessage* answer) | ### SIPTransaction

[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

void destroyed () | ### destroyed

[protected virtual]

Pre-destruction notification used to clean up the transaction

Reimplemented from RefObject.

bool tryAutoAuth (SIPMessage* answer) | ### tryAutoAuth

[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

SIPEvent* getClientEvent (int state, int timeout) | ### getClientEvent

[protected virtual]

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

SIPEvent* getServerEvent (int state, int timeout) | ### getServerEvent

[protected virtual]

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

void processClientMessage (SIPMessage* message, int state) | ### processClientMessage

[protected virtual]

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

void processServerMessage (SIPMessage* message, int state) | ### processServerMessage

[protected virtual]

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

bool changeState (int newstate) | ### changeState

[protected]

Change the transaction state

Parameters:

newstate | The desired new state

Returns: True if state change occured

void setLatestMessage (SIPMessage* message = 0) | ### setLatestMessage

[protected]

Set the latest message sent by this transaction

Parameters:

message | Pointer to the latest message

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

[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

inline bool isPendingEvent () | ### isPendingEvent

[protected const]

Check if there is a pending event waiting

Returns: True is there is a pending event

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

[protected]

Set a repetitive timeout

Parameters:

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

bool m_outgoing | ### m_outgoing

[protected]

bool m_invite | ### m_invite

[protected]

bool m_transmit | ### m_transmit

[protected]

int m_state | ### m_state

[protected]

int m_response | ### m_response

[protected]

unsigned int m_timeouts | ### m_timeouts

[protected]

u_int64_t m_delay | ### m_delay

[protected]

u_int64_t m_timeout | ### m_timeout

[protected]

SIPMessage* m_firstMessage | ### m_firstMessage

[protected]

SIPMessage* m_lastMessage | ### m_lastMessage

[protected]

SIPEvent* m_pending | ### m_pending

[protected]

SIPEngine* m_engine | ### m_engine

[protected]

String m_branch | ### m_branch

[protected]

String m_callid | ### m_callid

[protected]

String m_tag | ### m_tag

[protected]

void * m_private | ### m_private

[protected]

Generated by: paulc on bussard on Mon Feb 10 13:15:47 2014, using kdoc 2.0a54.