The SIP engine and transaction list. More...

#include <yatesip.h>

Inheritance diagram for SIPEngine:

Public Member Functions
	SIPEngine (const char *userAgent=0)

virtual	~SIPEngine ()

virtual bool	buildParty (SIPMessage *message)=0

virtual void	allocTraceId (String &id)=0

virtual void	traceMsg (SIPMessage *message, bool incoming=true)=0

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, bool autoChangeParty=0)

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

unsigned int	getReqTransCount () const

unsigned int	getRspTransCount () const

unsigned int	getMaxForwards () const

const String &	getUserAgent () const

SIPSequence *	getSequence () const

int32_t	getNextCSeq ()

bool	lazyTrying () const

void	lazyTrying (bool lazy100)

int	flags () const

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)

const String &	getAllowed () const

void	remove (SIPTransaction *transaction)

void	append (SIPTransaction *transaction)

void	insert (SIPTransaction *transaction)

unsigned int	transactionCount ()

Public Member Functions inherited from DebugEnabler
	DebugEnabler (int level=TelEngine::debugLevel(), bool enabled=true)

int	debugLevel () const

int	debugLevel (int level)

bool	debugEnabled () const

void	debugEnabled (bool enable)

const char *	debugName () const

bool	debugAt (int level) const

bool	debugChained () const

void	debugChain (const DebugEnabler *chain=0)

void	debugCopy (const DebugEnabler *original=0)

Public Member Functions inherited from Mutex
	Mutex (bool recursive=false, const char *name=0)

	Mutex (const Mutex &original)

	~Mutex ()

Mutex &	operator= (const Mutex &original)

virtual bool	lock (long maxwait=-1)

virtual bool	unlock ()

virtual bool	locked () const

const char *	owner () const

bool	recursive () const

Public Member Functions inherited from Lockable
virtual	~Lockable ()

virtual bool	check (long maxwait=-1)

virtual bool	unlockAll ()

Static Public Member Functions
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)

Static Public Member Functions inherited from Mutex
static int	count ()

static int	locks ()

static bool	efficientTimedLock ()

Static Public Member Functions inherited from Lockable
static void	wait (unsigned long maxwait)

static unsigned long	wait ()

static void	startUsingNow ()

static void	enableSafety (bool safe=true)

static bool	safety ()

Protected Attributes
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_flags

bool	m_lazyTrying

String	m_userAgent

String	m_allowed

RefPointer< SIPSequence >	m_seq

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

Additional Inherited Members
Protected Member Functions inherited from DebugEnabler
void	debugName (const char *name)

Detailed Description

The SIP engine and transaction list.

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

Constructor & Destructor Documentation

◆ SIPEngine()

SIPEngine ( const char * userAgent = 0 )

Create the SIP Engine

◆ ~SIPEngine()

virtual ~SIPEngine ( )

virtual

Destroy the SIP Engine

Member Function Documentation

◆ addAllowed()

void addAllowed ( const char * method )

Add a method to the allowed methods list

Parameters

method Uppercase name of the method to add

◆ addMessage() [1/2]

SIPTransaction * addMessage	(	SIPMessage *	message,
		bool *	autoChangeParty = 0 )

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

Parameters

message	A parsed SIP message to add to the transactions
autoChangeParty	Optional auto change party to set in transaction if a new one is created

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

References autoChangeParty().

◆ addMessage() [2/2]

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

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

◆ allocTraceId()

virtual void allocTraceId ( String & id )

pure virtual

Allocate a new trace ID. If tracing is not active, string will not be modified

Parameters

id	String where to put allocated ID.

◆ append()

void append ( SIPTransaction * transaction )

inline

Append a transaction to the end of the list

Parameters

transaction Pointer to transaction to append

References Mutex::lock(), m_transList, and Mutex::unlock().

◆ authUser()

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

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

◆ autoChangeParty()

bool autoChangeParty ( ) const

inline

Check if message party should be changed from latest dialog party

Returns: Value of auto change party option

Referenced by addMessage().

◆ buildAuth() [1/2]

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

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

◆ buildAuth() [2/2]

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

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

References NamedList::empty().

◆ buildParty()

virtual bool buildParty ( SIPMessage * message )

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

◆ checkAuth()

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

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

◆ checkUser()

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

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

◆ flags()

int flags ( ) const

inline

Retrieve various flags for this engine

Returns: Value of flags ORed together

◆ forkInvite()

virtual SIPTransaction * forkInvite	(	SIPMessage *	answer,
		SIPTransaction *	trans )

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

◆ getAllowed()

const String & getAllowed ( ) const

inline

Get all the allowed methods

Returns: Comma separated list of allowed methods

◆ getEvent()

SIPEvent * 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

◆ getMaxForwards()

unsigned int getMaxForwards ( ) const

inline

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

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

◆ getNextCSeq()

int32_t getNextCSeq ( )

inline

Get a CSeq value suitable for use in a new request

Returns: New CSeq value

◆ getReqTransCount()

unsigned int getReqTransCount ( ) const

inline

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

◆ getRspTransCount()

unsigned int getRspTransCount ( ) const

inline

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

◆ getSequence()

SIPSequence * getSequence ( ) const

inline

Get the Command Sequence Number generator

Returns: Pointer to the CSeq generator of this engine

◆ getTimer()

u_int64_t getTimer	(	char	which,
		bool	reliable = false ) 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

◆ getUserAgent()

const String & getUserAgent ( ) const

inline

Get the User agent for this SIP engine

◆ getUserTimeout()

virtual u_int64_t 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

◆ insert()

void insert ( SIPTransaction * transaction )

inline

Insert a transaction at the start of the list

Parameters

transaction Pointer to transaction to insert

References Mutex::lock(), m_transList, and Mutex::unlock().

◆ isAllowed()

bool isAllowed ( const char * method ) 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

◆ lazyTrying() [1/2]

bool lazyTrying ( ) const

inline

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

◆ lazyTrying() [2/2]

void lazyTrying ( bool lazy100 )

inline

Set the lazy "100 Trying" messages flag

Parameters

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

◆ ncGet()

void ncGet ( String & nc )

Get a nonce count

Parameters

nc	String reference to fill with new nonce count

◆ nonceAge()

long nonceAge ( const String & nonce )

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

◆ nonceGet()

void nonceGet ( String & nonce )

Get an authentication nonce

Parameters

nonce String reference to fill with the current nonce

◆ process()

bool 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

◆ processEvent()

virtual void processEvent ( SIPEvent * event )

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

◆ remove()

void remove ( SIPTransaction * transaction )

inline

Remove a transaction from the list without dereferencing it

Parameters

transaction Pointer to transaction to remove

References Mutex::lock(), m_transList, and Mutex::unlock().

◆ traceMsg()

virtual void traceMsg	(	SIPMessage *	message,
		bool	incoming = true )

pure virtual

Print a SIP message only if it has a trace ID

Parameters

message	The message to print
incoming	True if the message is incoming

◆ transactionCount()

unsigned int transactionCount ( )

inline

Get the number of active SIP transactions

Returns: Count of transactions in the list

References m_transList.

Member Data Documentation

◆ m_transList

ObjList m_transList

protected

The list that holds all the SIP transactions.

Referenced by append(), insert(), remove(), and transactionCount().

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

yatesip.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SIPEngine()

◆ ~SIPEngine()

Member Function Documentation

◆ addAllowed()

◆ addMessage() [1/2]

◆ addMessage() [2/2]

◆ allocTraceId()

◆ append()

◆ authUser()

◆ autoChangeParty()

◆ buildAuth() [1/2]

◆ buildAuth() [2/2]

◆ buildParty()

◆ checkAuth()

◆ checkUser()

◆ flags()

◆ forkInvite()

◆ getAllowed()

◆ getEvent()

◆ getMaxForwards()

◆ getNextCSeq()

◆ getReqTransCount()

◆ getRspTransCount()

◆ getSequence()

◆ getTimer()

◆ getUserAgent()

◆ getUserTimeout()

◆ insert()

◆ isAllowed()

◆ lazyTrying() [1/2]

◆ lazyTrying() [2/2]

◆ ncGet()

◆ nonceAge()

◆ nonceGet()

◆ process()

◆ processEvent()

◆ remove()

◆ traceMsg()

◆ transactionCount()

Member Data Documentation

◆ m_transList