# class SIPEngine | The SIP engine and transaction list. More...
Contains pure virtuals
Full name | `TelEngine::SIPEngine`
Definition | `#include <libs/ysip/yatesip.h>`
Inherits | TelEngine::DebugEnabler [public ], TelEngine::Mutex [public ]
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- SIPEngine (const char* userAgent = 0)
- virtual ~SIPEngine ()
- virtual bool buildParty (SIPMessage* message)
- virtual bool checkUser (String& username, const String& realm, const String& nonce, const String& method, const String& uri, const String& response, const SIPMessage* message, const MimeHeaderLine* authLine, GenObject* userData)
- virtual bool checkAuth (bool noUser, String& username, const SIPMessage* message, const MimeHeaderLine* authLine, GenObject* userData)
- int authUser (const SIPMessage* message, String& user, bool proxy = false, GenObject* userData = 0)
- SIPTransaction* addMessage (SIPParty* ep, const char* buf, int len = -1)
- SIPTransaction* addMessage (SIPMessage* message)
- SIPEvent * getEvent ()
- bool process ()
- virtual void processEvent (SIPEvent *event)
- virtual SIPTransaction* forkInvite (SIPMessage* answer, SIPTransaction* trans)
- virtual u_int64_t getUserTimeout () const
- u_int64_t getTimer (char which, bool reliable = false) const
- inline unsigned int getReqTransCount () const
- inline unsigned int getRspTransCount () const
- inline unsigned int getMaxForwards () const
- inline const String& getUserAgent () const
- inline int getNextCSeq ()
- inline bool lazyTrying () const
- inline void lazyTrying (bool lazy100)
- inline int flags () const
- inline bool autoChangeParty () const
- void nonceGet (String& nonce)
- long nonceAge (const String& nonce)
- void ncGet (String& nc)
- bool isAllowed (const char* method) const
- void addAllowed (const char* method)
- inline const String& getAllowed () const
- inline void remove (SIPTransaction* transaction)
- inline void append (SIPTransaction* transaction)
- inline void insert (SIPTransaction* transaction)
- inline unsigned int transactionCount ()

#### Public Static Methods

- static void buildAuth (const String& username, const String& realm, const String& passwd, const String& nonce, const String& method, const String& uri, String& response, const NamedList& qop = NamedList::empty())
- static void buildAuth (const String& hash_a1, const String& nonce, const String& hash_a2, String& response)

#### Protected Members

- ObjList m_transList
- u_int64_t m_t1
- u_int64_t m_t4
- int m_reqTransCount
- int m_rspTransCount
- unsigned int m_maxForwards
- int m_cseq
- int m_flags
- bool m_lazyTrying
- String m_userAgent
- String m_allowed
- u_int32_t m_nc
- String m_nonce
- String m_nonce_secret
- u_int32_t m_nonce_time
- Mutex m_nonce_mutex
- bool m_autoChangeParty

## Detailed Description

The SIP engine holds common methods and the list of current transactions

SIPEngine (const char* userAgent = 0) | ### SIPEngine

Create the SIP Engine

~SIPEngine () | ### ~SIPEngine

[virtual]

Destroy the SIP Engine

bool buildParty (SIPMessage* message) | ### buildParty

[pure virtual]

Build a new SIPParty for a message

Parameters:

message | Pointer to the message to build the party

Returns: True on success, false if party could not be built

bool checkUser (String& username, const String& realm, const String& nonce, const String& method, const String& uri, const String& response, const SIPMessage* message, const MimeHeaderLine* authLine, GenObject* userData) | ### checkUser

[virtual]

Check user credentials for validity

Parameters:

username | User account name
realm | Authentication realm
nonce | Authentication opaque nonce generated by the server
method | Method of the SIP message that is being authenticated
uri | URI of the SIP message that is being authenticated
response | Response computed by the authenticated entity
message | Message that is to be authenticated
authLine | Extra credentials line to validate
userData | Pointer to an optional object passed from authUser

Returns: True if valid user/password, false if verification failed

bool checkAuth (bool noUser, String& username, const SIPMessage* message, const MimeHeaderLine* authLine, GenObject* userData) | ### checkAuth

[virtual]

Authenticate a message by other means than user credentials. By default it calls checkUser with empty user credential fields

Parameters:

noUser | No plausible user credentials were detected so far
username | User account name
message | Message that is to be authenticated
authLine | Extra credentials line to validate
userData | Pointer to an optional object passed from authUser

Returns: True if message is authenticated, false if verification failed

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

Detect the proper credentials for any user in the engine

Parameters:

message | Pointer to the message to check
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

SIPTransaction* addMessage (SIPParty* ep, const char* buf, int len = -1) | ### addMessage

Add a message into the transaction list

Parameters:

ep | Party of the received message
buf | A buffer containing the SIP message text
len | The length of the message or -1 to interpret as C string

Returns: Pointer to the transaction or NULL if message was invalid

SIPTransaction* addMessage (SIPMessage* message) | ### addMessage

Add a message into the transaction list This method is thread safe

Parameters:

message | A parsed SIP message to add to the transactions

Returns: Pointer to the transaction or NULL if message was invalid

SIPEvent * getEvent () | ### getEvent

Get a SIPEvent from the queue. This method mainly looks into the transaction list and get all kind of events, like an incoming request (INVITE, REGISTRATION), a timer, an outgoing message. This method is thread safe

bool process () | ### process

This method should be called very often to get the events from the list and to send them to processEvent method.

Returns: True if some events were processed this turn

void processEvent (SIPEvent *event) | ### processEvent

[virtual]

Default handling for events. This method should be overriden for what you need and at the end you should call this default one This method is thread safe

SIPTransaction* forkInvite (SIPMessage* answer, SIPTransaction* trans) | ### forkInvite

[virtual]

Handle answers that create new dialogs for an outgoing INVITE

Parameters:

answer | The message that creates the INVITE fork
trans | One of the transactions part of the same INVITE

Returns: Pointer to new transaction or NULL if message is ignored

u_int64_t getUserTimeout () | ### getUserTimeout

[const virtual]

Get the timeout to be used for transactions involving human interaction. The default implementation returns the proxy INVITE timeout (timer C = 3 minutes) minus the INVITE response retransmit interval (timer T2 = 4 seconds)

Returns: Duration of the timeout in microseconds

u_int64_t getTimer (char which, bool reliable = false) | ### getTimer

[const]

Get the length of a timer

Parameters:

which | A one-character constant that selects which timer to return
reliable | Whether we request the timer value for a reliable protocol

Returns: Duration of the selected timer or 0 if invalid

inline unsigned int getReqTransCount () | ### getReqTransCount

[const]

Get the number of times to send a SIP request. This value applies only when retransmission is required

Returns: The number of times to send a SIP request

inline unsigned int getRspTransCount () | ### getRspTransCount

[const]

Get the number of times to send a response to a SIP request. This value applies only when retransmission is required

Returns: The number of times to send a response to a SIP request

inline unsigned int getMaxForwards () | ### getMaxForwards

[const]

Get the default value of the Max-Forwards header for this engine

Returns: The maximum number of hops the request is allowed to pass

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

[const]

Get the User agent for this SIP engine

inline int getNextCSeq () | ### getNextCSeq

Get a CSeq value suitable for use in a new request

inline bool lazyTrying () | ### lazyTrying

[const]

Check if the engine is set up for lazy "100 Trying" messages

Returns: True if the first 100 message is to be skipped for non-INVITE

inline void lazyTrying (bool lazy100) | ### lazyTrying

Set the lazy "100 Trying" messages flag

Parameters:

lazy100 | True to not send the 1st 100 message for non-INVITE

inline int flags () | ### flags

[const]

Retrieve various flags for this engine

Returns: Value of flags ORed together

inline bool autoChangeParty () | ### autoChangeParty

[const]

Check if message party should be changed from latest dialog party

Returns: Value of auto change party option

void nonceGet (String& nonce) | ### nonceGet

Get an authentication nonce

Parameters:

nonce | String reference to fill with the current nonce

long nonceAge (const String& nonce) | ### nonceAge

Get the age of an authentication nonce

Parameters:

nonce | String nonce to check for validity and age

Returns: Age of the nonce in seconds, negative for invalid

void ncGet (String& nc) | ### ncGet

Get a nonce count

Parameters:

nc | String reference to fill with new nonce count

void buildAuth (const String& username, const String& realm, const String& passwd, const String& nonce, const String& method, const String& uri, String& response, const NamedList& qop = NamedList::empty()) | ### buildAuth

[static]

Build an authentication response

Parameters:

username | User account name
realm | Authentication realm
passwd | Account password
nonce | Authentication opaque nonce generated by the server
method | Method of the SIP message that is being authenticated
uri | URI of the SIP message that is being authenticated
response | String to store the computed response
qop | Optional quality of protection type (set in list name) and parameters

void buildAuth (const String& hash_a1, const String& nonce, const String& hash_a2, String& response) | ### buildAuth

[static]

Build an authentication response from already hashed components

Parameters:

hash_a1 | MD5 digest of username:realm:password
nonce | Authentication opaque nonce generated by the server
hash_a2 | MD5 digest of method:uri
response | String to store the computed response

bool isAllowed (const char* method) | ### isAllowed

[const]

Check if a method is in the allowed methods list

Parameters:

method | Uppercase name of the method to check

Returns: True if the method should be allowed processing

void addAllowed (const char* method) | ### addAllowed

Add a method to the allowed methods list

Parameters:

method | Uppercase name of the method to add

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

[const]

Get all the allowed methods

Returns: Comma separated list of allowed methods

inline void remove (SIPTransaction* transaction) | ### remove

Remove a transaction from the list without dereferencing it

Parameters:

transaction | Pointer to transaction to remove

inline void append (SIPTransaction* transaction) | ### append

Append a transaction to the end of the list

Parameters:

transaction | Pointer to transaction to append

inline void insert (SIPTransaction* transaction) | ### insert

Insert a transaction at the start of the list

Parameters:

transaction | Pointer to transaction to insert

inline unsigned int transactionCount () | ### transactionCount

Get the number of active SIP transactions

Returns: Count of transactions in the list

ObjList m_transList | ### m_transList

[protected]

u_int64_t m_t1 | ### m_t1

[protected]

u_int64_t m_t4 | ### m_t4

[protected]

int m_reqTransCount | ### m_reqTransCount

[protected]

int m_rspTransCount | ### m_rspTransCount

[protected]

unsigned int m_maxForwards | ### m_maxForwards

[protected]

int m_cseq | ### m_cseq

[protected]

int m_flags | ### m_flags

[protected]

bool m_lazyTrying | ### m_lazyTrying

[protected]

String m_userAgent | ### m_userAgent

[protected]

String m_allowed | ### m_allowed

[protected]

u_int32_t m_nc | ### m_nc

[protected]

String m_nonce | ### m_nonce

[protected]

String m_nonce_secret | ### m_nonce_secret

[protected]

u_int32_t m_nonce_time | ### m_nonce_time

[protected]

Mutex m_nonce_mutex | ### m_nonce_mutex

[protected]

bool m_autoChangeParty | ### m_autoChangeParty

[protected]

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