This is the primary point of interaction between the app-layer and the stack. More...

#include <SipStack.hxx>

Inheritance diagram for resip::SipStack:

Classes
class	Exception
	thrown when the stack is unable to function. More...

Public Member Functions
	SipStack (const SipStackOptions &options)
	Constructor.

	SipStack (Security security=0, const DnsStub::NameserverList &additional=DnsStub::EmptyNameserverList, AsyncProcessHandler handler=0, bool stateless=false, AfterSocketCreationFuncPtr socketFunc=0, Compression compression=0, FdPollGrp pollGrp=0, bool useDnsVip=false)
	Constructor.

virtual	~SipStack ()

void	run ()
	Causes this SipStack object to create and run threads for carrying out processing.

void	shutdown ()
	perform orderly shutdown

void	shutdownAndJoinThreads ()
	Shutdown and join any threads that the SipStack is running.

void	onReload ()
	reload configuration

void	reloadCertificates ()
	reload the TLS X.509 certificates

void	setTransportSipMessageLoggingHandler (std::shared_ptr< Transport::SipMessageLoggingHandler > handler)
	Used by the application to provide a handler that will get called for all inbound and outbound SIP messages on transports that are added after calling this.

void	addTransportSipMessageLoggingHandler (std::shared_ptr< Transport::SipMessageLoggingHandler > handler)
	Used by the application to provide a handler that will get called for all inbound and outbound SIP messages on transports that are added after calling this.

Transport *	addTransport (TransportType protocol, int port, IpVersion version=V4, StunSetting stun=StunDisabled, const Data &ipInterface=Data::Empty, const Data &sipDomainname=Data::Empty, const Data &privateKeyPassPhrase=Data::Empty, SecurityTypes::SSLType sslType=SecurityTypes::DynamicTLS, unsigned transportFlags=0, const Data &certificateFilename="", const Data &privateKeyFilename="", SecurityTypes::TlsClientVerificationMode cvm=SecurityTypes::None, bool useEmailAsSIP=false, std::shared_ptr< WsConnectionValidator >=nullptr, std::shared_ptr< WsCookieContextFactory >=nullptr, const Data &netNs=Data::Empty)
	Used by the application to add in a new built-in transport.

void	addTransport (std::unique_ptr< Transport > transport)
	Used to plug-in custom transports.

void	removeTransport (unsigned int transportKey)
	Used to remove a previously added transport.

Fifo< TransactionMessage > &	stateMacFifo ()
	Returns the fifo that subclasses of Transport should use for the rxFifo cons.

void	addAlias (const Data &domain, int port)
	add an alias for this sip element

void	removeAlias (const Data &domain, int port)
	removes an alias from this sip element

bool	isMyDomain (const Data &domain, int port) const
	Returns true if domain is handled by this stack.

bool	isMyPort (int port) const
	Returns true if port is handled by this stack.

const Uri &	getUri () const
	Get one of the domains/ports that are handled by this stack in Uri form.

void	send (const SipMessage &msg, TransactionUser *tu=0)
	allows a TU to send a message

void	send (std::unique_ptr< SipMessage > msg, TransactionUser *tu=0)

void	sendTo (std::unique_ptr< SipMessage > msg, const Uri &uri, TransactionUser *tu=0)
	this is only if you want to send to a destination not in the route.

void	sendTo (std::unique_ptr< SipMessage > msg, const Tuple &tuple, TransactionUser *tu=0)
	this is only if you want to send to a destination not in the route.

void	sendTo (const SipMessage &msg, const Uri &uri, TransactionUser *tu=0)
	send a message to a destination not in the route

void	sendTo (const SipMessage &msg, const Tuple &tuple, TransactionUser *tu=0)
	send a message to a destination not in the route

void	sendOverExistingConnection (const SipMessage &msg, const Tuple &tuple, TransactionUser *tu=0)
	force the a message out over an existing connection

void	post (std::unique_ptr< ApplicationMessage > message, unsigned int secondsLater, TransactionUser *tu=0)
	Makes the message available to the TU at some later time, specified in seconds.

void	postMS (std::unique_ptr< ApplicationMessage > message, unsigned int ms, TransactionUser *tu=0)
	Makes the message available to the TU at some later time, specified in milli-seconds.

void	post (std::unique_ptr< ApplicationMessage > message, std::chrono::duration< double > interval, TransactionUser *tu=0)
	Makes the message available to the TU at some later time, specified as an interval.

void	post (std::unique_ptr< ApplicationMessage > message)
	Makes the message available to the TU later.

void	post (const ApplicationMessage &message)
	Makes the message available to the TU later.

void	post (const ApplicationMessage &message, unsigned int secondsLater, TransactionUser *tu=0)
	Makes the message available to the TU at some later time, specified in seconds.

void	postMS (const ApplicationMessage &message, unsigned int ms, TransactionUser *tu=0)
	Makes the message available to the TU at some later time, specified in milli-seconds.

void	post (const ApplicationMessage &message, std::chrono::duration< double > interval, TransactionUser *tu=0)
	Makes the message available to the TU at some later time, specified as an interval.

void	abandonServerTransaction (const Data &tid)
	Tells the stack that the TU has abandoned a server transaction.

void	cancelClientInviteTransaction (const Data &tid, const Tokens *reasons)
	Tells the stack that the TU wishes to CANCEL an INVITE request.

bool	hasMessage () const
	does the stack have new messages for the TU?

SipMessage *	receive ()
	retrieve a SipMessage off the old TuFifo

Message *	receiveAny ()
	retrieve a message off the old TuFifo

void	setFallbackPostNotify (AsyncProcessHandler *handler)

virtual void	buildFdSet (FdSet &fdset)
	Build the FD set to use in a select to find out when process(FdSet&) must be called again.

virtual void	process (FdSet &fdset)
	This allows the executive to give processing time to stack components.

bool	process (unsigned int timeoutMs)
	Give processing time to the SipStack components, when operating in single-threaded mode.

FdPollGrp *	getPollGrp ()

virtual unsigned int	getTimeTillNextProcessMS ()
	Returns time in milliseconds when process next needs to be called.

virtual void	processTimers ()
	Check all timers.

void	setStatisticsInterval (unsigned long seconds)
	Sets the interval that determines the time between Statistics messages.

void	zeroOutStatistics ()
	Resets all of the cumulative statistics counters.

bool	pollStatistics ()
	Immediately polls for statistics to be logged and sent to external handlers, instead of waiting for next statistics interval.

void	setExternalStatsHandler (ExternalStatsHandler *handler)
	Installs a handler for the stacks internal StatisticsManager.

const StatisticsManager *	getStatisticsManager ()
	get statistics manager

EncodeStream &	dump (EncodeStream &strm) const
	output current state of the stack - for debug

Security *	getSecurity () const
	Returns a pointer to the embedded Security object, 0 if not set.

void	registerTransactionUser (TransactionUser &, const bool front=false)
	add a TU to the TU selection chain

void	requestTransactionUserShutdown (TransactionUser &)
	Queue a shutdown request to the specified TU.

void	unregisterTransactionUser (TransactionUser &)
	Removes a TU from the TU selection chain.

void	registerMarkListener (MarkListener *listener)
	Register a handler with the DNS Interface for notifications of when a Dns Resource Record has been blacklisted.

void	unregisterMarkListener (MarkListener *listener)
	Removed a registered BlacklistListener handler from the DNS Interface for a particualr Resource Record type and handler pointer.

DnsStub &	getDnsStub () const

void	setEnumSuffixes (const std::vector< Data > &suffixes)
	Specify which enum domains will be searched when sending.

void	setEnumDomains (const std::map< Data, Data > &domains)
	Specify which domains in the To: Uri will be subject to ENUM.

void	clearDnsCache ()
	Clear the DNS Cache.

void	logDnsCache ()
	Log the DNS Cache to WarningLog for Debugging.

void	getDnsCacheDump (std::pair< unsigned long, unsigned long > key, GetDnsCacheDumpHandler *handler)
	Get a string representation of the DNS Cache.

void	reloadDnsServers ()
	Check if DnsServers list has changed, and if so reinitializes the DNS resolver (ares).

volatile bool &	statisticsManagerEnabled ()
	Enable Statistics Manager.

const bool	statisticsManagerEnabled () const

bool	getFixBadDialogIdentifiers () const
	Returns whether the stack is fixing corrupted/changed dialog identifiers (ie, Call-Id and tags) in responses from the wire.

void	setFixBadDialogIdentifiers (bool pFixBadDialogIdentifiers)
	Specify whether the stack should fix corrupted/changed dialog identifiers (ie, Call-Id and tags) in responses from the wire.

bool	getFixBadCSeqNumbers () const

void	setFixBadCSeqNumbers (bool pFixBadCSeqNumbers)

bool	setUdpOnlyOnNumeric (bool value)

bool	getUdpOnlyOnNumeric () const

void	setContentLengthChecking (bool check)
	Used to enable/disable content-length checking on datagram-based transports.

void	setCongestionManager (CongestionManager *manager)
	Sets the CongestionManager used by the stack.

CongestionManager *	getCongestionManager ()
	Accessor for the CongestionManager object the stack is using.

Compression &	getCompression ()
	Accessor for the Compression object the stack is using.

void	terminateFlow (const resip::Tuple &flow)

void	enableFlowTimer (const resip::Tuple &flow)

void	invokeAfterSocketCreationFunc (TransportType type=UNKNOWN_TRANSPORT)

Public Member Functions inherited from resip::FdSetIOObserver
	FdSetIOObserver ()

virtual	~FdSetIOObserver ()

Static Public Member Functions
static Data	getHostname ()
	Get one of the names for this host (calls through to gethostbyname) and is not threadsafe.

static Data	getHostAddress ()
	Get one of the IP address for this host (calls through to gethostbyname) and is not threadsafe.

Friends
class	Executive

class	StatelessHandler

class	StatisticsManager

class	TestDnsResolver

class	TestFSM

class	TransactionState

class	TransactionController

class	TuSelector

Detailed Description

This is the primary point of interaction between the app-layer and the stack.

For a SipStack to be usable, transports must be added by calling the addTransport() method.

The useful work done by SipStack occurs when SipStack::process(unsigned int) is called. A separate thread (such as EventStackThread) can be dedicated to this task, or it can be called from within a loop in the main thread of the executable.

Graceful shutdown is accomplished by advising the SipStack to begin shutdown procedures via the shutdown() method. The SipStack should continue to be serviced through the process(unsigned int) method until the Transaction User is informed by receiving a ShutdownMessage that the requested shutdown is complete.

Note: Previously, buildFdSet(FdSet&), FdSet::select(), and process(FdSet&) were the canonical way of giving the SipStack cycles. Because of shortcomings of the fd_set approach, these have been deprecated.

Definition at line 159 of file SipStack.hxx.

Constructor & Destructor Documentation

◆ SipStack() [1/2]

SipStack::SipStack ( const SipStackOptions & options )

Constructor.

First instantiate SipStackOptions, then set any values special to your application, then call this constructor. The {options} instance is not referenced after construction (i.e., the SipStack doesn't keep a reference to it). However, it does copy each individual value, and takes ownership of several of the objects.

Definition at line 73 of file SipStack.cxx.

◆ SipStack() [2/2]

SipStack::SipStack	(	Security *	security = `0`,
		const DnsStub::NameserverList &	additional = `DnsStub::EmptyNameserverList`,
		AsyncProcessHandler *	handler = `0`,
		bool	stateless = `false`,
		AfterSocketCreationFuncPtr	socketFunc = `0`,
		Compression *	compression = `0`,
		FdPollGrp *	pollGrp = `0`,
		bool	useDnsVip = `false`
	)

Constructor.

This constructor is obsolete. The SipStackOptions-based constructor should be used instead.

Parameters

security	Security Object required by the stack for TLS, DTLS, SMIME and Identity-draft compliance. If 0 is passed in the stack will not support these advanced security features. The compile flag USE_SSL is also required. The security object will be owned by the SipStack and deleted in the SipStack destructor. Default is 0.
handler	AsyncProcessHandler that will be invoked when Messages are posted to the stack. For example: SelectInterruptor. Default is 0.
stateless	This parameter does not appear to be used.
socketFunc	A pointer to a function that will be called after a socket in the DNS or SIP transport layers of the stack has been created. This callback can be used to control low level socket options, such as Quality-of-Service/DSCP. Note: For SIP TCP sockets there is one call for the listen socket, and one (or two) calls for each connection created afterwards. For each inbound TCP connection the first callback is called immediately before the socket is connected, and if configured it is called again after the connect call has completed and before the first data is sent out. On some OS's you cannot set QOS until the socket is successfully connected. To enable this behavior call: Connection::setEnablePostConnectSocketFuncCall(); DNS sockets get one call each. With c-ares it comes before the socket connects, and the setting above adds a second call once it is connected; the bundled ares makes its one call after connecting.
compression	Compression configuration object required for SigComp. If set to 0, then SigComp compression will be disabled.
pollGrp	Polling group to support file-io callbacks; if one is not passed, one will be created. Ownership is not taken.
useDnsVip	Set to true to enable Whitelisting of DNS entries. A feature that usually desired by UA's that want to stick to a known good server / dns result.

Definition at line 87 of file SipStack.cxx.

◆ ~SipStack()

SipStack::~SipStack ( )

virtual

Definition at line 224 of file SipStack.cxx.

Member Function Documentation

◆ abandonServerTransaction()

void SipStack::abandonServerTransaction ( const Data & tid )

Tells the stack that the TU has abandoned a server transaction.

This is provided to allow better behavior in cases where an exception is thrown due to garbage in the request, and the code catching the exception has no way of telling whether the original request is still around. This frees the TU of the obligation to respond to the request.

Parameters

tid	The transaction identifier for the server transaction.

Note: This function is distinct from cancelClientInviteTransaction().

Definition at line 1040 of file SipStack.cxx.

◆ addTransport() [1/2]

void SipStack::addTransport ( std::unique_ptr< Transport > transport )

Used to plug-in custom transports.

Adds the transport to the Transport Selector.

Parameters

transport Pointer to an externally created transport. SipStack assumes ownership.

Definition at line 523 of file SipStack.cxx.

◆ addTransport() [2/2]

Transport * SipStack::addTransport	(	TransportType	protocol,
		int	port,
		IpVersion	version = `V4`,
		StunSetting	stun = `StunDisabled`,
		const Data &	ipInterface = `Data::Empty`,
		const Data &	sipDomainname = `Data::Empty`,
		const Data &	privateKeyPassPhrase = `Data::Empty`,
		SecurityTypes::SSLType	sslType = `SecurityTypes::DynamicTLS`,
		unsigned	transportFlags = `0`,
		const Data &	certificateFilename = `""`,
		const Data &	privateKeyFilename = `""`,
		SecurityTypes::TlsClientVerificationMode	cvm = `SecurityTypes::None`,
		bool	useEmailAsSIP = `false`,
		std::shared_ptr< WsConnectionValidator >	wsConnectionValidator = `nullptr`,
		std::shared_ptr< WsCookieContextFactory >	wsCookieContextFactory = `nullptr`,
		const Data &	netNs = `Data::Empty`
	)

Used by the application to add in a new built-in transport.

The transport is created and then added to the Transport Selector.

Exceptions

Transport::Exception If the transport couldn't be added, usually because the port was already bound.

Parameters

protocol	TCP, UDP, TLS, DTLS, etc.
port	Specifies which port to bind to.
version	Protocol Version: V4 or V6
stun	Specifies whether STUN is enabled.
ipInterface	Specifies which ethernet interface to bind to. If set to Data::Empty, bind to all interfaces. Binding to all interfaces can impose a performance penalty, however, so it is recommended that you bind to specific interfaces when using in high-throughput deployments. Note: Interfaces must be identified via IP address.
sipDomainname	Only allow messages to be sent as the specified domain. For default case, you can pass in domainname = DnsUtil::getLocalDomainName().
privateKeyPassPhrase	Private key pass phrase used to decrypt private key certificates. Note: For now this parameter is not used we are loading PKCS7 keys, so a pass phrase is not required.
sslType	Version of the TLS specification to use: DynamicTLS or TLSv1
transportFlags	Bit-mask of TransportFlags to control transport behavior. All flags default to "off" (0) to preserve traditional behavior. Available flags (see Transport.hxx for details): RESIP_TRANSPORT_FLAG_NOBIND: No inbound connections (TCP/TLS) RESIP_TRANSPORT_FLAG_RXALL: Read all messages before returning to event loop RESIP_TRANSPORT_FLAG_TXALL: Write all messages before returning to event loop RESIP_TRANSPORT_FLAG_TXNOW: Immediately try sending when message posted RESIP_TRANSPORT_FLAG_OWNTHREAD: Transport has its own thread RESIP_TRANSPORT_FLAG_SYMMETRIC_CONNECTIONS: Bind client connections to same port as listening socket (TCP/TLS) for connection reuse
certificateFilename	Path to the host domain TLS certificate file (PEM format). Used for TLS/DTLS transports. If empty, uses certificates from Security object.
privateKeyFilename	Path to the host domain TLS private key file (PEM format). Used for TLS/DTLS transports. If empty, uses private key from Security object.
cvm	SSL verify mode for the peer (whether we accept and/or insist on a client certificate from the peer)
useEmailAsSIP	If true, we will accept the email address in a client's subjectAltName as if it were a SIP URI. This is convenient because many commercial CAs offer email certificates but not sip: certificates. For reasons of standards compliance, it is disabled by default.
netNs	Set the network namespace (netns) in which the Transport is to bind the the given address and port.

Definition at line 362 of file SipStack.cxx.

◆ addTransportSipMessageLoggingHandler()

void SipStack::addTransportSipMessageLoggingHandler ( std::shared_ptr< Transport::SipMessageLoggingHandler > handler )

Used by the application to provide a handler that will get called for all inbound and outbound SIP messages on transports that are added after calling this.

Multiple handlers can be added with this method.

Note: If you want a custom handler per transport then you can call setSipMessageLoggingHandler on the Transport pointer returned from addTransport

Parameters

handler std::shared_ptr to a handler to call for inbound and outbound SIP messages for all transports added after calling this.

Definition at line 343 of file SipStack.cxx.

◆ buildFdSet()

void SipStack::buildFdSet ( FdSet & fdset )

virtual

Build the FD set to use in a select to find out when process(FdSet&) must be called again.

Parameters

fdset an empty or partially populated fdset, fd's are added to the fdset on return

Note: This must be called prior to calling process.; select() must also be called on the fdset prior to process.

Deprecated:: Because of serious shortcomings in fd_set (most notably the inability to store FDs whose value exceeds a relatively small number; ~1000), we are deprecating the FdSet-based process loop.

See also: EventStackThread for an alternative, or if you wish to drive the SipStack yourself,; process(unsigned int). On platforms that do not support epoll, fd_set ends up being used anyway since there is no other choice, but this is hidden from the app.

Implements resip::FdSetIOObserver.

Definition at line 1179 of file SipStack.cxx.

◆ cancelClientInviteTransaction()

void SipStack::cancelClientInviteTransaction	(	const Data &	tid,
		const Tokens *	reasons
	)

Tells the stack that the TU wishes to CANCEL an INVITE request.

This frees the TU of the obligation to keep state on whether a 1xx has come in yet before actually sending a CANCEL request, and also the obligation of forming the CANCEL request itself. This does not free the TU of the obligation to handle any INVITE/200 that come in (usually by sending an ACK to the 200, and then a BYE).

Parameters

tid	The transaction identifier of the INVITE request sent.
reasons	Optional reason headers to be added to any resulting CANCEL request.

Definition at line 1046 of file SipStack.cxx.

◆ clearDnsCache()

void SipStack::clearDnsCache ( )

Clear the DNS Cache.

Definition at line 1267 of file SipStack.cxx.

◆ dump()

EncodeStream & SipStack::dump ( EncodeStream & strm ) const

output current state of the stack - for debug

Definition at line 1303 of file SipStack.cxx.

◆ enableFlowTimer()

void SipStack::enableFlowTimer ( const resip::Tuple & flow )

Definition at line 1340 of file SipStack.cxx.

◆ getDnsCacheDump()

void SipStack::getDnsCacheDump	(	std::pair< unsigned long, unsigned long >	key,
		GetDnsCacheDumpHandler *	handler
	)

Get a string representation of the DNS Cache.

Parameters

key	- a pair representing the request key, can be used by the callback handler to identify the originating request
handler	- pointer to a class that implements the handler method: onDnsCacheRetrieved

Definition at line 1279 of file SipStack.cxx.

◆ getDnsStub()

DnsStub & SipStack::getDnsStub ( ) const

Definition at line 1249 of file SipStack.cxx.

◆ getFixBadCSeqNumbers()

bool resip::SipStack::getFixBadCSeqNumbers ( ) const

inline

Definition at line 1045 of file SipStack.hxx.

◆ getHostAddress()

Data SipStack::getHostAddress ( )

static

Get one of the IP address for this host (calls through to gethostbyname) and is not threadsafe.

Definition at line 794 of file SipStack.cxx.

◆ getHostname()

Data SipStack::getHostname ( )

static

Get one of the names for this host (calls through to gethostbyname) and is not threadsafe.

Definition at line 763 of file SipStack.cxx.

◆ getPollGrp()

FdPollGrp * resip::SipStack::getPollGrp ( )

inline

Definition at line 854 of file SipStack.hxx.

◆ getSecurity()

Security * SipStack::getSecurity ( ) const

Returns a pointer to the embedded Security object, 0 if not set.

Definition at line 1185 of file SipStack.cxx.

◆ getStatisticsManager()

const StatisticsManager * resip::SipStack::getStatisticsManager ( )

inline

get statistics manager

Definition at line 908 of file SipStack.hxx.

◆ getTimeTillNextProcessMS()

unsigned int SipStack::getTimeTillNextProcessMS ( )

virtual

Returns time in milliseconds when process next needs to be called.

returns time in milliseconds when process next needs to be called

Returns: The maximum time in ms that whatever is giving the SipStack processing cycles should wait before calling either process(unsigned int) or process(FdSet&). In most circumstances, this is simply when the next timer (either an app timer, or a SIP transaction timer) is scheduled to fire. However, in cases where there is processing work to be done (in the form of messages in a fifo somewhere), this will return 0.

Implements resip::FdSetIOObserver.

Definition at line 1160 of file SipStack.cxx.

◆ getUdpOnlyOnNumeric()

bool resip::SipStack::getUdpOnlyOnNumeric ( ) const

inline

Definition at line 1060 of file SipStack.hxx.

◆ getUri()

const Uri & SipStack::getUri ( ) const

Get one of the domains/ports that are handled by this stack in Uri form.

"sip:" scheme is assumed.

Definition at line 854 of file SipStack.cxx.

◆ hasMessage()

bool SipStack::hasMessage ( ) const

does the stack have new messages for the TU?

Returns: return true if the stack has new messages for the TU.

Deprecated:: Since the addition of TransactionUsers, this method is deprecated. This only looks into the old TuFifo that is not associated with any TransactionUser.

Definition at line 1052 of file SipStack.cxx.

◆ invokeAfterSocketCreationFunc()

void SipStack::invokeAfterSocketCreationFunc ( TransportType type = UNKNOWN_TRANSPORT )

Definition at line 1346 of file SipStack.cxx.

◆ isMyDomain()

bool SipStack::isMyDomain	(	const Data &	domain,
		int	port
	)		const

Returns true if domain is handled by this stack.

Convenience for Transaction Users.

Parameters

domain	Domain name to check.
port	Port number to check.

Definition at line 837 of file SipStack.cxx.

◆ isMyPort()

bool SipStack::isMyPort ( int port ) const

Returns true if port is handled by this stack.

Convenience for Transaction Users.

Parameters

port	Port number to check.

Definition at line 847 of file SipStack.cxx.

◆ logDnsCache()

void SipStack::logDnsCache ( )

Log the DNS Cache to WarningLog for Debugging.

Definition at line 1273 of file SipStack.cxx.

◆ onReload()

void SipStack::onReload ( )

reload configuration

Perform actions typically associated with the HUP signal, for example, reloading certificate files from disk.

Note: If an application never calls this method, for example, because it is on a platform without signal support, the SipStack still works anyway.

Definition at line 317 of file SipStack.cxx.

◆ pollStatistics()

bool SipStack::pollStatistics ( )

Immediately polls for statistics to be logged and sent to external handlers, instead of waiting for next statistics interval.

Returns false if statistics manager is not enabled.

Definition at line 1206 of file SipStack.cxx.

◆ post() [1/6]

void SipStack::post ( const ApplicationMessage & message )

Makes the message available to the TU later.

Note: Makes a copy of the Message. Caller is responsible for deleting the memory and may do so as soon as it returns.; TranasctionUser subclasses can just post to themselves.

Parameters

message ApplicationMessage to post

Definition at line 966 of file SipStack.cxx.

◆ post() [2/6]

void SipStack::post	(	const ApplicationMessage &	message,
		std::chrono::duration< double >	interval,
		TransactionUser *	tu = `0`
	)

Makes the message available to the TU at some later time, specified as an interval.

Note: TransactionUser subclasses can just post to themselves.

Parameters

message	ApplicationMessage to post
interval	Delay before message is to be posted.
tu	TransactionUser to post to.

Definition at line 990 of file SipStack.cxx.

◆ post() [3/6]

void SipStack::post	(	const ApplicationMessage &	message,
		unsigned int	secondsLater,
		TransactionUser *	tu = `0`
	)

Makes the message available to the TU at some later time, specified in seconds.

Note: Makes a copy of the ApplicationMessage. Caller is responsible for deleting the memory and may do so as soon as it returns.; TranasctionUser subclasses can just post to themselves.

Parameters

message	ApplicationMessage to post.
secondsLater	Number of seconds before message is to be posted.
tu	TransactionUser to post to.

Definition at line 974 of file SipStack.cxx.

◆ post() [4/6]

void SipStack::post ( std::unique_ptr< ApplicationMessage > message )

Makes the message available to the TU later.

Note: TranasctionUser subclasses can just post to themselves.

Parameters

message ApplicationMessage to post

Definition at line 959 of file SipStack.cxx.

◆ post() [5/6]

void SipStack::post	(	std::unique_ptr< ApplicationMessage >	message,
		std::chrono::duration< double >	interval,
		TransactionUser *	tu = `0`
	)

Makes the message available to the TU at some later time, specified as an interval.

Note: TransactionUser subclasses can just post to themselves.

Parameters

message	ApplicationMessage to post
interval	Delay before message is to be posted.
tu	TransactionUser to post to.

Definition at line 1024 of file SipStack.cxx.

◆ post() [6/6]

void SipStack::post	(	std::unique_ptr< ApplicationMessage >	message,
		unsigned int	secondsLater,
		TransactionUser *	tu = `0`
	)

Makes the message available to the TU at some later time, specified in seconds.

Note: TransactionUser subclasses can just post to themselves.

Parameters

message	ApplicationMessage to post
secondsLater	Number of seconds before message is to be posted.
tu	TransactionUser to post to.

Definition at line 1007 of file SipStack.cxx.

◆ postMS() [1/2]

void SipStack::postMS	(	const ApplicationMessage &	message,
		unsigned int	ms,
		TransactionUser *	tu = `0`
	)

Makes the message available to the TU at some later time, specified in milli-seconds.

Note: Makes a copy of the ApplicationMessage. Caller is responsible for deleting the memory and may do so as soon as it returns.; TranasctionUser subclasses can just post to themselves.

Parameters

message	ApplicationMessage to post
ms	Number of milli-seconds before message is to be posted.
tu	TransactionUser to post to.

Definition at line 982 of file SipStack.cxx.

◆ postMS() [2/2]

void SipStack::postMS	(	std::unique_ptr< ApplicationMessage >	message,
		unsigned int	ms,
		TransactionUser *	tu = `0`
	)

Makes the message available to the TU at some later time, specified in milli-seconds.

Note: TransactionUser subclasses can just post to themselves.

Parameters

message	ApplicationMessage to post
ms	Number of milli-seconds before message is to be posted.
tu	TransactionUser to post to.

Definition at line 1016 of file SipStack.cxx.

◆ process() [1/2]

void SipStack::process ( FdSet & fdset )

virtual

This allows the executive to give processing time to stack components.

Note: Must call buildFdSet and select before calling this.; The transports are serviced, and then timers are serviced.

Parameters

fdset a populated and 'select'ed fdset

Deprecated:: Because of serious shortcomings in fd_set (most notably the inability to store FDs whose value exceeds a relatively small number; ~1000), we are deprecating the FdSet-based process loop.

See also: EventStackThread for an alternative, or if you wish to drive the SipStack yourself,; process(unsigned int). On platforms that do not support epoll, fd_set ends up being used anyway since there is no other choice, but this is hidden from the app.

Implements resip::FdSetIOObserver.

Definition at line 1141 of file SipStack.cxx.

◆ process() [2/2]

bool SipStack::process ( unsigned int timeoutMs )

Give processing time to the SipStack components, when operating in single-threaded mode.

This call will allow all the components in the SipStack a chance to perform processing. This includes:

Transaction processing (handling of SIP messages and timers)
DNS processing (includes DNS network IO and 3263 logic)
Transport processing (network IO for raw SIP traffic)
Application timers

To give the SipStack cycles, it is sufficient to simply call this function repeatedly.

Parameters

timeoutMs The maximum time, in milliseconds, we will wait for IO in this call. We will not necessarily wait this long if no IO occurs; if timers are scheduled to fire before this duration elapses, our timeout value will be adjusted accordingly. Similarly, if there is work waiting in fifos when this call is made, no timeout will be used. Lower values will cause higher CPU utilization when idle, higher values may result in processing delays of messages from the TU sent during the call to process(unsigned int) (eg; you call process(50), then immediately schedule an app timer to fire in 25ms, or send a SipMessage to the stack, it could be 50ms before either of these are processed). You can work around these caveats by creating a SelectInterruptor, adding its FD to the SipStack's FdPollGrp, and calling SelectInterruptor::interrupt() to cause process(unsigned int) to be interrupted. The best approach will vary, based on your performance needs.

Note: If you wish to add an FD that will interrupt this call if it becomes ready (either because it has IO you are interested in, or merely to interrupt this call to carry out some unrelated task, see getPollGrp())

Returns: Whether any work was done as a result of this call.

Definition at line 1148 of file SipStack.cxx.

◆ processTimers()

void SipStack::processTimers ( )

virtual

Check all timers.

Note: If you are driving this SipStack's IO using its FdPollGrp directly (because you have more than one stack sharing the FdPollGrp, for example), you need to call this periodically (see impl of EventStackThread for an example of this). process(unsigned int) does this for you.

Definition at line 1117 of file SipStack.cxx.

◆ receive()

SipMessage * SipStack::receive ( )

retrieve a SipMessage off the old TuFifo

Retrieve a SipMessage off the old TuFifo. Caller now owns the memory. Returns 0 if nothing there. Since the addition of TransactionUsers, this method is deprecated. This only looks into the old TuFifo that is not associated with any TransactionUser.

Note: Applications posting non-sip messages must use receive any. If non SipMessages are on the Fifo, then they are just deleted.

Deprecated:

Returns: pointer to received SipMessage, 0 if nothing there.

Definition at line 1058 of file SipStack.cxx.

◆ receiveAny()

Message * SipStack::receiveAny ( )

retrieve a message off the old TuFifo

Retrieve a Message off the old TuFifo. Caller now owns the memory. Returns 0 if nothing there. Since the addition of TransactionUsers, this method is deprecated. This only looks into the old TuFifo that is not associated with any TransactionUser.

Note: Applications posting non-sip messages must use receive any. If non SipMessages are on the Fifo, then they are just deleted.

Deprecated:

Returns: pointer to received Message, 0 if nothing there. May return TransactionTerminated*, TimerMessage*, SipMessage* or derived ApplicationMessage*

Definition at line 1088 of file SipStack.cxx.

◆ registerTransactionUser()

void SipStack::registerTransactionUser	(	TransactionUser &	tu,
		const bool	front = `false`
	)

add a TU to the TU selection chain

Adds a TU to the TU selection chain. Tu's do not call receive or receiveAny, the SipStack will call postToTu on the appropriate Tu. Messages not associated with a registered TU go into SipStack::mTuFifo.

Definition at line 1217 of file SipStack.cxx.

◆ reloadCertificates()

void SipStack::reloadCertificates ( )

reload the TLS X.509 certificates

reloads the X.509 certificate for each transport.

Definition at line 323 of file SipStack.cxx.

◆ reloadDnsServers()

void SipStack::reloadDnsServers ( )

Check if DnsServers list has changed, and if so reinitializes the DNS resolver (ares).

Any lookups currenlty in progress will fail.

Definition at line 1285 of file SipStack.cxx.

◆ removeTransport()

void SipStack::removeTransport ( unsigned int transportKey )

Used to remove a previously added transport.

Parameters

transportKey The key for the transpor to remove. Use Transport::getKey to get the key of a transport after it is added to the stack.

Definition at line 620 of file SipStack.cxx.

◆ requestTransactionUserShutdown()

void SipStack::requestTransactionUserShutdown ( TransactionUser & tu )

Queue a shutdown request to the specified TU.

Definition at line 1223 of file SipStack.cxx.

◆ run()

void SipStack::run ( )

Causes this SipStack object to create and run threads for carrying out processing.

This includes a thread for DNS lookups, a thread for transaction processing, and a thread for transport processing (individual Transport objects may be registered as having their own thread; these are not serviced by the thread spawned by this call). This function is intended to be used in addition to the normal method/s of giving the SipStack cycles (eg; EventStackThread, StackThread, etc); these are still necessary to give the SipStack cycles for handling application timers, statistics logging, and shutdown logic.

Definition at line 258 of file SipStack.cxx.

◆ send() [1/2]

void SipStack::send	(	const SipMessage &	msg,
		TransactionUser *	tu = `0`
	)

allows a TU to send a message

Interface for the TU to send a message. Makes a copy of the SipMessage. Caller is responsible for deleting the memory and may do so as soon as it returns. Loose Routing processing as per RFC3261 must be done before calling send by the TU. See Helper::processStrictRoute

Parameters

msg	SipMessage to send.
tu	TransactionUser to send from.

See also: TransactionUser

Definition at line 867 of file SipStack.cxx.

◆ send() [2/2]

void SipStack::send	(	std::unique_ptr< SipMessage >	msg,
		TransactionUser *	tu = `0`
	)

Definition at line 884 of file SipStack.cxx.

◆ sendOverExistingConnection()

void resip::SipStack::sendOverExistingConnection	(	const SipMessage &	msg,
		const Tuple &	tuple,
		TransactionUser *	tu = `0`
	)

inline

force the a message out over an existing connection

This is only if you want to force send to only send over an existing connection. If there is no connection, then it will try the next tuple.
If there are no more Tuples to try, then a 503 is sent to the TU. Makes a copy of the SipMessage. Caller is responsible for deleting the memory and may do so as soon as it returns.

Parameters

msg	SipMessage to send.
tuple	Destination to send to, specified as a Tuple. A connection to this destination must exist.
tu	TransactionUser to send from.

Definition at line 1284 of file SipStack.hxx.

◆ sendTo() [1/4]

void SipStack::sendTo	(	const SipMessage &	msg,
		const Tuple &	tuple,
		TransactionUser *	tu = `0`
	)

send a message to a destination not in the route

This is only if you want to send to a destination not in the route. Useful for implementing Outbound Proxy use. Makes a copy of the SipMessage. Caller is responsible for deleting the memory and may do so as soon as it returns.

Parameters

msg	SipMessage to send.
tuple	Destination to send to, specified as a Tuple.
tu	TransactionUser to send from.

Definition at line 937 of file SipStack.cxx.

◆ sendTo() [2/4]

void SipStack::sendTo	(	const SipMessage &	msg,
		const Uri &	uri,
		TransactionUser *	tu = `0`
	)

send a message to a destination not in the route

This is only if you want to send to a destination not in the route. Useful for implementing Outbound Proxy use. Makes a copy of the SipMessage. Caller is responsible for deleting the memory and may do so as soon as it returns.

Parameters

msg	SipMessage to send.
uri	Destination to send to, specified as a Uri.
tu	TransactionUser to send from.

Definition at line 922 of file SipStack.cxx.

◆ sendTo() [3/4]

void SipStack::sendTo	(	std::unique_ptr< SipMessage >	msg,
		const Tuple &	tuple,
		TransactionUser *	tu = `0`
	)

this is only if you want to send to a destination not in the route.

Note: You probably don't want to use it.

Definition at line 908 of file SipStack.cxx.

◆ sendTo() [4/4]

void SipStack::sendTo	(	std::unique_ptr< SipMessage >	msg,
		const Uri &	uri,
		TransactionUser *	tu = `0`
	)

this is only if you want to send to a destination not in the route.

Note: You probably don't want to use it.

Definition at line 898 of file SipStack.cxx.

◆ setExternalStatsHandler()

void resip::SipStack::setExternalStatsHandler ( ExternalStatsHandler * handler )

inline

Installs a handler for the stacks internal StatisticsManager.

This handler is called before the default behavior.

Definition at line 902 of file SipStack.hxx.

◆ setFallbackPostNotify()

void SipStack::setFallbackPostNotify ( AsyncProcessHandler * handler )

Definition at line 1110 of file SipStack.cxx.

◆ setFixBadCSeqNumbers()

void resip::SipStack::setFixBadCSeqNumbers ( bool pFixBadCSeqNumbers )

inline

Definition at line 1050 of file SipStack.hxx.

◆ setTransportSipMessageLoggingHandler()

void SipStack::setTransportSipMessageLoggingHandler ( std::shared_ptr< Transport::SipMessageLoggingHandler > handler )

Used by the application to provide a handler that will get called for all inbound and outbound SIP messages on transports that are added after calling this.

Clears any handlers that have been added previously.

Note: If you want a custom handler per transport then you can call setSipMessageLoggingHandler on the Transport pointer returned from addTransport

Parameters

handler std::shared_ptr to a handler to call for inbound and outbound SIP messages for all transports added after calling this.

Definition at line 332 of file SipStack.cxx.

◆ setUdpOnlyOnNumeric()

bool resip::SipStack::setUdpOnlyOnNumeric ( bool value )

inline

Definition at line 1055 of file SipStack.hxx.

◆ shutdown()

void SipStack::shutdown ( )

perform orderly shutdown

Inform the transaction state machine processor that it should not create any new transactions and to perform an orderly shutdown. When the transactions are all terminated, return a ShutdownMessage to the TU.

Note: If the SipStack is running in multithreaded mode, this function DOES NOT shut down the threads. This is what shutdownAndJoinThreads() is for. (Shutting down threads in this call would prevent orderly shutdown from working; outstanding transactions would be dropped on the floor)

Definition at line 280 of file SipStack.cxx.

◆ shutdownAndJoinThreads()

void SipStack::shutdownAndJoinThreads ( )

Shutdown and join any threads that the SipStack is running.

Definition at line 294 of file SipStack.cxx.

◆ stateMacFifo()

Fifo< TransactionMessage > & SipStack::stateMacFifo ( )

Returns the fifo that subclasses of Transport should use for the rxFifo cons.

param.

Returns: A fifo of TransactionMessage's

Definition at line 716 of file SipStack.cxx.

◆ statisticsManagerEnabled()

const bool SipStack::statisticsManagerEnabled ( ) const

Definition at line 1297 of file SipStack.cxx.

◆ terminateFlow()

void SipStack::terminateFlow ( const resip::Tuple & flow )

Definition at line 1334 of file SipStack.cxx.

◆ unregisterTransactionUser()

void SipStack::unregisterTransactionUser ( TransactionUser & tu )

Removes a TU from the TU selection chain.

Definition at line 1230 of file SipStack.cxx.

◆ zeroOutStatistics()

void SipStack::zeroOutStatistics ( )

Resets all of the cumulative statistics counters.

Definition at line 1197 of file SipStack.cxx.

Friends And Related Symbol Documentation

◆ Executive

friend class Executive

friend

Definition at line 1271 of file SipStack.hxx.

◆ StatelessHandler

friend class StatelessHandler

friend

Definition at line 1272 of file SipStack.hxx.

◆ StatisticsManager

friend class StatisticsManager

friend

Definition at line 1273 of file SipStack.hxx.

◆ TestDnsResolver

friend class TestDnsResolver

friend

Definition at line 1274 of file SipStack.hxx.

◆ TestFSM

friend class TestFSM

friend

Definition at line 1275 of file SipStack.hxx.

◆ TransactionController

friend class TransactionController

friend

Definition at line 1277 of file SipStack.hxx.

◆ TransactionState

friend class TransactionState

friend

Definition at line 1276 of file SipStack.hxx.

◆ TuSelector

friend class TuSelector

friend

Definition at line 1278 of file SipStack.hxx.

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

resip/stack/SipStack.hxx
resip/stack/SipStack.cxx

Classes

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ SipStack() [1/2]

◆ SipStack() [2/2]

◆ ~SipStack()

Member Function Documentation

◆ abandonServerTransaction()

◆ addTransport() [1/2]

◆ addTransport() [2/2]

◆ addTransportSipMessageLoggingHandler()

◆ buildFdSet()

◆ cancelClientInviteTransaction()

◆ clearDnsCache()

◆ dump()

◆ enableFlowTimer()

◆ getDnsCacheDump()

◆ getDnsStub()

◆ getFixBadCSeqNumbers()

◆ getHostAddress()

◆ getHostname()

◆ getPollGrp()

◆ getSecurity()

◆ getStatisticsManager()

◆ getTimeTillNextProcessMS()

◆ getUdpOnlyOnNumeric()

◆ getUri()

◆ hasMessage()

◆ invokeAfterSocketCreationFunc()

◆ isMyDomain()

◆ isMyPort()

◆ logDnsCache()

◆ onReload()

◆ pollStatistics()

◆ post() [1/6]

◆ post() [2/6]

◆ post() [3/6]

◆ post() [4/6]

◆ post() [5/6]

◆ post() [6/6]

◆ postMS() [1/2]

◆ postMS() [2/2]

◆ process() [1/2]

◆ process() [2/2]

◆ processTimers()

◆ receive()

◆ receiveAny()

◆ registerTransactionUser()

◆ reloadCertificates()

◆ reloadDnsServers()

◆ removeTransport()

◆ requestTransactionUserShutdown()

◆ run()

◆ send() [1/2]

◆ send() [2/2]

◆ sendOverExistingConnection()

◆ sendTo() [1/4]

◆ sendTo() [2/4]

◆ sendTo() [3/4]

◆ sendTo() [4/4]

◆ setExternalStatsHandler()

◆ setFallbackPostNotify()

◆ setFixBadCSeqNumbers()

◆ setTransportSipMessageLoggingHandler()

◆ setUdpOnlyOnNumeric()

◆ shutdown()

◆ shutdownAndJoinThreads()

◆ stateMacFifo()

◆ statisticsManagerEnabled()

◆ terminateFlow()

◆ unregisterTransactionUser()

◆ zeroOutStatistics()

Friends And Related Symbol Documentation

◆ Executive

◆ StatelessHandler

◆ StatisticsManager

◆ TestDnsResolver