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

#include <TransactionUser.hxx>

Collaboration 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.
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
	Returns true iff this TransactionUser should be notified when transactions end.
bool	isRegisteredForConnectionTermination () const
	Returns true iff this TransactionUser should be notified when connections close.
bool	isRegisteredForKeepAlivePongs () const
CongestionManager::RejectionBehavior	getRejectionBehavior () const
virtual void	setCongestionManager (CongestionManager *manager)
virtual UInt16	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
Private Types
typedef std::set< Data >	DomainList
Private Member Functions
void	postToTransactionUser (Message *msg, TimeLimitFifo< Message >::DepthUsage usage)
unsigned int	size () const
bool	wouldAccept (TimeLimitFifo< Message >::DepthUsage usage) const
Private Attributes
MessageFilterRuleList	mRuleList
DomainList	mDomainList
bool	mRegisteredForTransactionTermination
bool	mRegisteredForConnectionTermination
bool	mRegisteredForKeepAlivePongs
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 48 of file TransactionUser.hxx.

Member Typedef Documentation

typedef std::set<Data> resip::TransactionUser::DomainList [private]

Definition at line 231 of file TransactionUser.hxx.

Member Enumeration Documentation

enum resip::TransactionUser::ConnectionTermination [protected]

Enumerator:

RegisterForConnectionTermination
DoNotRegisterForConnectionTermination

Definition at line 160 of file TransactionUser.hxx.

      {
         RegisterForConnectionTermination,
         DoNotRegisterForConnectionTermination
      };

enum resip::TransactionUser::KeepAlivePongs [protected]

Enumerator:

RegisterForKeepAlivePongs
DoNotRegisterForKeepAlivePongs

Definition at line 166 of file TransactionUser.hxx.

      {
         RegisterForKeepAlivePongs,
         DoNotRegisterForKeepAlivePongs
      };

enum resip::TransactionUser::TransactionTermination [protected]

Enumerator:

RegisterForTransactionTermination
DoNotRegisterForTransactionTermination

Definition at line 154 of file TransactionUser.hxx.

      {
         RegisterForTransactionTermination,
         DoNotRegisterForTransactionTermination
      };

Constructor & Destructor Documentation

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 10 of file TransactionUser.cxx.

References mFifo, mRuleList, and resip::FifoStatsInterface::setDescription().

                                                   : 
   mFifo(0, 0),
   mCongestionManager(0),
   mRuleList(),
   mDomainList(),
   mRegisteredForTransactionTermination(t == RegisterForTransactionTermination),
   mRegisteredForConnectionTermination(c == RegisterForConnectionTermination),
   mRegisteredForKeepAlivePongs(k == RegisterForKeepAlivePongs)
{
  // This creates a default message filter rule, which
  // handles all sip:, sips:, and tel: requests.
  mRuleList.push_back(MessageFilterRule());

  // Set a default Fifo description - should be modified by override class to be
  // more desriptive
   mFifo.setDescription("TransactionUser::mFifo");
}

Here is the call graph for this function:

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 30 of file TransactionUser.cxx.

References mFifo, and resip::FifoStatsInterface::setDescription().

                                                   : 
   mFifo(0, 0), 
   mCongestionManager(0),
   mRuleList(mfrl),
   mDomainList(),
   mRegisteredForTransactionTermination(t == RegisterForTransactionTermination),
   mRegisteredForConnectionTermination(c == RegisterForConnectionTermination),
   mRegisteredForKeepAlivePongs(k == RegisterForKeepAlivePongs)
{
  // Set a default Fifo description - should be modified by override class to be
  // more desriptive
   mFifo.setDescription("TransactionUser::mFifo");
}

Here is the call graph for this function:

TransactionUser::~TransactionUser ( ) [protected, pure virtual]

Definition at line 47 of file TransactionUser.cxx.

{
}

Member Function Documentation

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.

Definition at line 102 of file TransactionUser.cxx.

References mDomainList.

{
   // Domain search should be case insensitive - store in lowercase only
   mDomainList.insert(Data(domain).lowercase());  
}

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 109 of file TransactionUser.cxx.

References mFifo, name(), and resip::AbstractFifo< T >::size().

{
   strm << "TU: " << name() << " size=" << mFifo.size();
   return strm;
}

Here is the call graph for this function:

virtual UInt16 resip::TransactionUser::getExpectedWait ( ) const [inline, virtual]

Definition at line 140 of file TransactionUser.hxx.

References resip::AbstractFifo< T >::expectedWaitTimeMilliSec(), and mFifo.

Referenced by resip::TuSelector::getExpectedWait().

      {
         return (UInt16)mFifo.expectedWaitTimeMilliSec();
      }

Here is the call graph for this function:

CongestionManager::RejectionBehavior resip::TransactionUser::getRejectionBehavior ( ) const [inline]

Definition at line 118 of file TransactionUser.hxx.

References resip::CongestionManager::getRejectionBehavior(), mCongestionManager, mFifo, and resip::CongestionManager::NORMAL.

Referenced by resip::TuSelector::getRejectionBehavior().

      {
         if(mCongestionManager)
         {
            return mCongestionManager->getRejectionBehavior(&mFifo);
         }
         return CongestionManager::NORMAL;
      }

Here is the call graph for this function:

bool TransactionUser::isForMe ( const SipMessage & msg ) const [protected, virtual]

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 77 of file TransactionUser.cxx.

References resip::Message::brief(), DebugLog, and mRuleList.

{
   DebugLog (<< "Checking if " << msg.brief() << " is for me");
   // do this for each MessageFilterRule
   for (MessageFilterRuleList::const_iterator i = mRuleList.begin() ; 
        i != mRuleList.end() ; ++i)
   {
       DebugLog (<< "Checking rule...");
       if (i->matches(msg))
       {
          DebugLog (<< "Match!");
          return true;
       }       
   }
   DebugLog (<< "No matching rule found");
   return false;
}

Here is the call graph for this function:

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 96 of file TransactionUser.cxx.

References mDomainList.

Referenced by resip::MessageFilterRule::hostIsInList().

{
   // Domain search should be case insensitive - search in lowercase only
   return mDomainList.count(Data(domain).lowercase()) > 0;
}

bool TransactionUser::isRegisteredForConnectionTermination ( ) const

Returns true iff this TransactionUser should be notified when connections close.

Definition at line 133 of file TransactionUser.cxx.

References mRegisteredForConnectionTermination.

{
   return mRegisteredForConnectionTermination;
}

bool TransactionUser::isRegisteredForKeepAlivePongs ( ) const

Definition at line 139 of file TransactionUser.cxx.

References mRegisteredForKeepAlivePongs.

{
   return mRegisteredForKeepAlivePongs;
}

bool TransactionUser::isRegisteredForTransactionTermination ( ) const

Returns true iff this TransactionUser should be notified when transactions end.

Definition at line 127 of file TransactionUser.cxx.

References mRegisteredForTransactionTermination.

Referenced by resip::TransactionState::terminateClientTransaction(), and resip::TransactionState::terminateServerTransaction().

{
   return mRegisteredForTransactionTermination;
}

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.

Referenced by encode().

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 52 of file TransactionUser.cxx.

References resip::TimeLimitFifo< Msg >::add(), and mFifo.

Referenced by resip::TuSelector::remove().

{
  mFifo.add(msg, TimeLimitFifo<Message>::InternalElement);
}

Here is the call graph for this function:

void TransactionUser::postToTransactionUser	(	Message *	msg,
		TimeLimitFifo< Message >::DepthUsage	usage
	)		`[private]`

Definition at line 58 of file TransactionUser.cxx.

References resip::TimeLimitFifo< Msg >::add(), and mFifo.

Referenced by resip::TuSelector::add().

{
   mFifo.add(msg, usage);
   //DebugLog (<< "TransactionUser::postToTransactionUser " << msg->brief() << " &=" << &mFifo << " size=" << mFifo.size());
}

Here is the call graph for this function:

virtual bool resip::TransactionUser::responsesMandatory ( ) const [inline, virtual]

Definition at line 151 of file TransactionUser.hxx.

Referenced by resip::TransactionState::sendToTU().

{return true;}

virtual void resip::TransactionUser::setCongestionManager ( CongestionManager * manager ) [inline, virtual]

Definition at line 127 of file TransactionUser.hxx.

References mCongestionManager, mFifo, resip::CongestionManager::registerFifo(), and resip::CongestionManager::unregisterFifo().

      {
         if(mCongestionManager)
         {
            mCongestionManager->unregisterFifo(&mFifo);
         }
         mCongestionManager=manager;
         if(mCongestionManager)
         {
            mCongestionManager->registerFifo(&mFifo);
         }
      }

Here is the call graph for this function:

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 116 of file TransactionUser.cxx.

References mRuleList.

{
   mRuleList = rules;
   MessageFilterRuleList::iterator it = mRuleList.begin();
   for(;it!=mRuleList.end();it++)
   {
      it->setTransactionUser(this);
   }
}

unsigned int TransactionUser::size ( ) const [private]

Definition at line 65 of file TransactionUser.cxx.

References mFifo, and resip::AbstractFifo< T >::size().