Overview of libsip

Applications that use SIP must initialize the Oracle Solaris SIP stack by registering certain mandatory and optional functions. These functions enable message exchanges and related functionalities between peers. If the application does not register any of the optional functions, the library uses the built-in equivalent when such an equivalent is available.

The SIP library is multithread-safe. Multiple threads can perform simultaneous operations on message headers. Each message maintains a reference count. The stack frees a message when the reference count is zero. The library does not protect messages against the case where an application thread reduces the reference count to 0. In this case, the stack can delete the message while other threads are using the message.

The SIP stack consists of the following operational components:

• Header management layer

• Transaction management layer

• Dialog management layer

• Message formatting layer

• Timer management layer

• Connection manager

Header Management Layer

The header management layer provides the interfaces that are required to build, parse, examine and validate SIP headers.

Transaction Management Layer

SIP is based on a request/response transaction model that is similar to the model that is used by HTTP. A transaction comprises a request that is sent by a client to a server and all of the responses to that request that are sent back from the server. The transaction management layer handles application-level retransmissions, matching responses to requests, and application-level timeouts. A User Agent Client (UAC) performs tasks by using a series of transactions.

Dialog Management Layer

A dialog is a persistent peer-to-peer SIP relationship between two user agents. A dialog facilitates the sequencing of messages and the proper routing of requests between the user agents. The use of dialogs is optional. Dialogs hold state information, which can be used to construct a request within a session. An application can implement its own dialog management layer instead of using the layer that the SIP stack provides. If the stack manages the dialog, it automatically creates and updates dialogs for incoming and outgoing SIP messages. The stack also delivers the matching dialog to the application with the incoming message.

Message Formatting Layer

The message formatting layer constructs a SIP message for an incoming message before delivering the message to the application. If the underlying transport protocol is TCP, this layer also breaks the byte stream at SIP message boundaries. The message formatting layer determines the SIP message boundaries by using the Content-Length header. If a transaction exists, the stack passes the message to the transaction layer for further processing, then passes the message to the application. If the dialog management layer is present, the stack passes the message to the dialog management layer, then passes the message to the application. If neither a transaction nor a dialog management layer are present, the stack passes the message to the application directly. For outbound messages, the message formatting layer adds a Content-Length header that is followed by an empty line, meeting the requirements of RFC 3261. The stack passes the message to the application's send function after passing the message to the transaction layer and dialog layer, if either is present. The stack sends the SIP message to the application's send routine after the stack copies all of the message's headers and contents into a contiguous buffer.

Timer Management Layer

The SIP stack uses several timers. The timer management layer provides timeout and un-timeout routines for these timers. The application can implement its own timeout/un-timeout routines and register them with the stack instead of using the routines that are provided by the library.

Connection Manager

The connection manager provides input/output functionality. The connection manager is not a part of the SIP library, but interacts with the library by using well defined interfaces. A connection is identified by two endpoints, one local and one remote, as well as by the transport protocol that the connection uses. A connection is represented within the stack by a connection object. The stack requires that the first member of the connection object be a void pointer. The stack uses this first member to store data that is related to the connection object. The application must initialize the connection object. The application is responsible for the following functions:

Compliance with RFC 3263

The library expects the application to supply the address of the next recipient of the SIP message and to handle network errors. The application must follow the procedures defined in RFC 3263 for locating SIP servers.

Sent-By and Received parameters

Section 18.1.1 of RFC 3261 states that the transport layer must add a “sent-by” parameter to the topmost VIA header in every request. The application must include this information when constructing the VIA header. The application must register all values it could use for the sent-by parameter with the stack to enable the stack to validate incoming responses as required by section 18.1.2 of RFC 3261. Section 18.2.1 of RFC 3261 lists the conditions under which the transport layer must add a “received” parameter to the top VIA header of incoming messages. This “received” header must indicate the source of the message. The stack does not add a “received” parameter.

TTL and maddr parameters

The application should add the TTL and maddr parameters in the VIA header when required.