resip::TransactionUser Class Reference

The base-class for an RFC 3261 Transaction User. More...

#include <TransactionUser.hxx>

Inheritance diagram for resip::TransactionUser:

Public Member Functions
void	post (Message *msg)
	Posts a Message to this TransactionUser's fifo.
bool	isMyDomain (const Data &domain) const
	Returns true iff domain matches one of the domains that this TransactionUser is responsible for.
void	addDomain (const Data &domain)
	Adds a domain to the set of domains that this TransactionUser is responsible for.
void	removeDomain (const Data &domain)
	Removes a domain from the set of domains that this TransactionUser is responsible for.
void	setDomainMatcher (std::shared_ptr< DomainMatcher > domainMatcher) noexcept
	Replaces the default DomainMatcher.
virtual const Data &	name () const =0
	Return the name of this TransactionUser.
virtual EncodeStream &	encode (EncodeStream &strm) const
	Encodes the name of this TransactionUser (as specified by name()), and the current depth of its fifo.
void	setMessageFilterRuleList (MessageFilterRuleList &rules)
	Sets this TransactionUser's MessageFilterRuleList.
bool	isRegisteredForTransactionTermination () const
bool	isRegisteredForConnectionTermination () const
bool	isRegisteredForKeepAlivePongs () const
CongestionManager::RejectionBehavior	getRejectionBehavior () const
virtual void	setCongestionManager (CongestionManager *manager)
const TimeLimitFifo< Message > *	getFifo ()
virtual const uint16_t	getExpectedWait () const
virtual bool	responsesMandatory () const

Protected Types
enum	TransactionTermination { RegisterForTransactionTermination , DoNotRegisterForTransactionTermination }
enum	ConnectionTermination { RegisterForConnectionTermination , DoNotRegisterForConnectionTermination }
enum	KeepAlivePongs { RegisterForKeepAlivePongs , DoNotRegisterForKeepAlivePongs }

Protected Member Functions
	TransactionUser (TransactionTermination t=DoNotRegisterForTransactionTermination, ConnectionTermination c=DoNotRegisterForConnectionTermination, KeepAlivePongs k=DoNotRegisterForKeepAlivePongs)
	Constructor that specifies whether this TransactionUser needs to hear about the completion of transactions, and the closing of connections.
	TransactionUser (MessageFilterRuleList &rules, TransactionTermination t=DoNotRegisterForTransactionTermination, ConnectionTermination c=DoNotRegisterForConnectionTermination, KeepAlivePongs k=DoNotRegisterForKeepAlivePongs)
	Constructor that specifies the MessageFilterRuleList, whether this TransactionUser needs to hear about the completion of transactions, and the closing of connections.
virtual	~TransactionUser ()=0
virtual bool	isForMe (const SipMessage &msg) const
	Returns true iff this TransactionUser should process msg.

Protected Attributes
TimeLimitFifo< Message >	mFifo
	This TransactionUser's fifo.
CongestionManager *	mCongestionManager

Friends
class	TuSelector

Detailed Description

The base-class for an RFC 3261 Transaction User.

This is the "app-layer".

Subclasses of TransactionUser are expected to do the following things:

• Register itself by using SipStack::registerTransactionUser().
• Regularly pull messages out of mFifo, and process them.
  • Particularly, every received SIP request MUST be responded to, or the stack will leak transactions.
• Before the TransactionUser is destroyed, it should ensure that it has been unregistered from the stack using SipStack::unregisterTransactionUser(), and gotten a confirmation in the form of a TransactionUserMessage.

There is also a collection of things you can do to customize how the stack interacts with your TransactionUser:

• If you wish to restrict the types of SIP traffic your TransactionUser will receive from the stack, you can do so by setting the MessageFilterRuleList, either in the constructor, or with setMessageFilterRuleList() (see MessageFilterRule for more)
  • If you need more fine-grained control over what SIP messages your TransactionUser is willing/able to handle, you can override TransactionUser::isForMe().
• If you wish your TransactionUser to be notified whenever a transaction ends, just pass RegisterForTransactionTermination in the constructor.
• If you wish your TransactionUser to be notified when Connections are closed, pass RegisterForConnectionTermination in the constructor.

Definition at line 50 of file TransactionUser.hxx.

Member Enumeration Documentation

ConnectionTermination

enum resip::TransactionUser::ConnectionTermination

protected

Enumerator
RegisterForConnectionTermination
DoNotRegisterForConnectionTermination

Definition at line 192 of file TransactionUser.hxx.

KeepAlivePongs

enum resip::TransactionUser::KeepAlivePongs

protected

Enumerator
RegisterForKeepAlivePongs
DoNotRegisterForKeepAlivePongs

Definition at line 198 of file TransactionUser.hxx.

TransactionTermination

enum resip::TransactionUser::TransactionTermination

protected

Enumerator
RegisterForTransactionTermination
DoNotRegisterForTransactionTermination

Definition at line 186 of file TransactionUser.hxx.

Constructor & Destructor Documentation

TransactionUser() [1/2]

TransactionUser::TransactionUser ( TransactionTermination  t = DoNotRegisterForTransactionTermination, ConnectionTermination  c = DoNotRegisterForConnectionTermination, KeepAlivePongs  k = DoNotRegisterForKeepAlivePongs  )

protected

Constructor that specifies whether this TransactionUser needs to hear about the completion of transactions, and the closing of connections.

Parameters

t	Whether or not the TransactionUser should be informed when transactions end (disabled by default).
c	Whether or not the TransactionUser should be informed when connections close (disabled by default).

Note

The default MessageFilterRuleList used will accept all SIP requests with either sip: or sips: in the Request-Uri.

This is protected to ensure than no-one constructs the base-class. (Subclasses call this in their constructor)

Definition at line 13 of file TransactionUser.cxx.

TransactionUser() [2/2]

TransactionUser::TransactionUser ( MessageFilterRuleList &  rules, TransactionTermination  t = DoNotRegisterForTransactionTermination, ConnectionTermination  c = DoNotRegisterForConnectionTermination, KeepAlivePongs  k = DoNotRegisterForKeepAlivePongs  )

protected

Constructor that specifies the MessageFilterRuleList, whether this TransactionUser needs to hear about the completion of transactions, and the closing of connections.

Parameters

rules	The MessageFilterRuleList to use. (A copy is made)
t	Whether or not the TransactionUser should be informed when transactions end (disabled by default).
c	Whether or not the TransactionUser should be informed when connections close (disabled by default).

Note

This is protected to ensure than no-one constructs the base-class. (Subclasses call this in their constructor)

Definition at line 33 of file TransactionUser.cxx.

~TransactionUser()

TransactionUser::~TransactionUser ( )

protectedpure virtual

Definition at line 50 of file TransactionUser.cxx.

Member Function Documentation

addDomain()

void TransactionUser::addDomain

(

const Data &

domain

)

Adds a domain to the set of domains that this TransactionUser is responsible for.

Note

The comparison performed is case-sensitive; make sure you lower-case everything you put in here.

Todo:

Make this case-insensitive.

Warning

This method is NOT thread-safe. mDomainList is accessed from both the thread that queues to the TU (iff a DomainIsMe MessageFilterRule is used) and from within the TU itself. The only way calling this is safe, is if you can ensure both of these threads are not calling isMyDomain when you call this method. For example an application that does NOT use a DomainIsMe MessageFilterRule and that posts the addDomain call to the TU processing thread for execution there, will be thread safe. This API is also safe to call before any of the processing threads have been started.

Definition at line 104 of file TransactionUser.cxx.

encode()

EncodeStream & TransactionUser::encode ( EncodeStream &  strm ) const

virtual

Encodes the name of this TransactionUser (as specified by name()), and the current depth of its fifo.

Parameters

strm	The ostream to encode to.

Returns

strm

Definition at line 122 of file TransactionUser.cxx.

getExpectedWait()

virtual const uint16_t resip::TransactionUser::getExpectedWait ( ) const

inlinevirtual

Definition at line 172 of file TransactionUser.hxx.

getFifo()

const TimeLimitFifo< Message > * resip::TransactionUser::getFifo ( )

inline

Definition at line 170 of file TransactionUser.hxx.

getRejectionBehavior()

CongestionManager::RejectionBehavior resip::TransactionUser::getRejectionBehavior ( ) const

inline

Definition at line 148 of file TransactionUser.hxx.

isForMe()

bool TransactionUser::isForMe ( const SipMessage &  msg ) const

protectedvirtual

Returns true iff this TransactionUser should process msg.

Parameters

msg	The SipMessage we received.

Returns

True iff this TransactionUser should process msg.

Note

By default, this uses the MessageFilterRuleList. It can be overridden for more flexibility.

Definition at line 80 of file TransactionUser.cxx.

isMyDomain()

bool TransactionUser::isMyDomain

(

const Data &

domain

)

const

Returns true iff domain matches one of the domains that this TransactionUser is responsible for.

(added with addDomain).

Parameters

domain

The domain name to check.

Returns

True iff this TransactionUser is responsible for domain.

Note

The comparison performed is case-sensitive; make sure you lower-case everything you put in here.

Definition at line 98 of file TransactionUser.cxx.

isRegisteredForConnectionTermination()

bool TransactionUser::isRegisteredForConnectionTermination

(

)

const

Definition at line 146 of file TransactionUser.cxx.

isRegisteredForKeepAlivePongs()

bool TransactionUser::isRegisteredForKeepAlivePongs

(

)

const

Definition at line 152 of file TransactionUser.cxx.

isRegisteredForTransactionTermination()

bool TransactionUser::isRegisteredForTransactionTermination

(

)

const

Definition at line 140 of file TransactionUser.cxx.

name()

virtual const Data & resip::TransactionUser::name ( ) const

pure virtual

Return the name of this TransactionUser.

Used in encode().

Returns

The name of this TransactionUser, as a Data.

Implemented in repro::Proxy, and resip::DialogUsageManager.

post()

void TransactionUser::post

(

Message *

msg

)

Posts a Message to this TransactionUser's fifo.

Ownership of msg is taken.

Parameters

msg	The Message to add to mFifo. (This takes ownership of msg)

Definition at line 55 of file TransactionUser.cxx.

removeDomain()

void TransactionUser::removeDomain

(

const Data &

domain

)

Removes a domain from the set of domains that this TransactionUser is responsible for.

Note

This API will lowercase the domain when searching for the domain to remove

Warning

This method is NOT thread-safe. mDomainList is accessed from both the thread that queues to the TU (iff a DomainIsMe MessageFilterRule is used) and from within the TU itself. The only way calling this is safe, is if you can ensure both of these threads are not calling isMyDomain when you call this method. For example an application that does NOT use a DomainIsMe MessageFilterRule and that posts the removeDomain call to the TU processing thread (ie: DUMThread) for execution there, will be thread safe.

Definition at line 110 of file TransactionUser.cxx.

responsesMandatory()

virtual bool resip::TransactionUser::responsesMandatory ( ) const

inlinevirtual

Definition at line 183 of file TransactionUser.hxx.

setCongestionManager()

virtual void resip::TransactionUser::setCongestionManager ( CongestionManager *  manager )

inlinevirtual

Definition at line 157 of file TransactionUser.hxx.

setDomainMatcher()

void TransactionUser::setDomainMatcher ( std::shared_ptr< DomainMatcher >  domainMatcher )

noexcept

Replaces the default DomainMatcher.

Definition at line 116 of file TransactionUser.cxx.

setMessageFilterRuleList()

void TransactionUser::setMessageFilterRuleList

(

MessageFilterRuleList &

rules

)

Sets this TransactionUser's MessageFilterRuleList.

This tells the stack which SIP messages this TransactionUser is interested in, and which ones it is not. This allows multiple TransactionUsers to run on top of the same SipStack.

Parameters

rules

The MessageFilterRuleList to use.

See also

MessageFilterRule

Definition at line 129 of file TransactionUser.cxx.

Friends And Related Symbol Documentation

TuSelector

friend class TuSelector

friend

Definition at line 267 of file TransactionUser.hxx.

Member Data Documentation

mCongestionManager

CongestionManager* resip::TransactionUser::mCongestionManager

protected

Definition at line 254 of file TransactionUser.hxx.

mFifo

TimeLimitFifo<Message> resip::TransactionUser::mFifo

protected

This TransactionUser's fifo.

All communication with the TransactionUser goes through here.

Definition at line 253 of file TransactionUser.hxx.

---

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

• resip/stack/TransactionUser.hxx
• resip/stack/TransactionUser.cxx