Transaction Management Layer

The transaction management layer creates and maintains transaction states for both clients and servers. The transaction management layer complies with Section 17 of RFC 3261.

The stack maintains a hash table of transactions. The index of this hash table is an MD5 hash. For messages that comply with RFC 3261, the MD5 hash is the hash of the branch ID. For messages that comply with RFC 2543, the MD5 hash is of a combination of the branch ID, Call-ID, From, To, and Cseq fields. The stack uses the branch ID in the topmost VIA header to identify the RFC that a message complies with. Messages that comply with RFC 3261 prefix their branch ID with the string z9hG4bK.

The library initializes the transaction layer as part of the stack initialization. The library also initializes the transaction error and state transition callback functions if the application provides them.

Transaction Creation And Maintenance

The stack scans the transaction hash table for an existing transaction when the stack receives incoming requests and responses. If a transaction that matches an incoming response does not exist, the stack handles the transaction statelessly. When an incoming request requires the stack to create a transaction, the application notifies the stack of the need to create a transaction when the application sends the response. In both cases, the stack passes the message to the application. If a request matches a transaction, the stack considers the request a retransmission and the transaction layer retransmits the last response. The stack drops the incoming request and does not pass the request to the application. The CANCEL request and an ACK for a non-2xx response are exceptions to this behavior. A CANCEL request matches the INVITE transaction that it is cancelling. An ACK for a non-2xx response also matches the INVITE request whose response the ACK is acknowledging. In these two cases, the request is not a retransmission and the stack sends the request sent to the application. If a response matches a transaction, the stack processes the response and statefully passes the message to the application.

The stack only creates a transaction for an outgoing response when the application requests the transaction creation by using the sip_sendmsg() function. The stack only creates a transaction for outgoing requests if the application requests the transaction creation by using the sip_sendmsg() function. The stack caches the transaction creating message and the last message that was sent on a transaction. This cache facilitates retransmissions and the processing of retransmitted requests. The stack initializes timers A, B, D, E, F, G, H, I, J and K for new transactions. See Appendix A for more information about timers.

When a message causes a transaction to change states, the stack invokes a callback function if the application registered a callback function with the stack.

Transaction Creation and ACK Signal Generation

A SIP entity must send an ACK signal for each final response that the SIP entity receives to an INVITE request. The procedure for sending the ACK signal depends on the type of response. For final responses between 300 and 699, the transaction layer handles the ACK signal processing. For 2xx responses, the application generates the ACK signal. In all cases, the application receives the response.

Transaction Deletion

The MD5 hash that is stored in the transaction is used to look up and delete the transaction from the hash table. When a transaction enters a terminated state, the transaction management layer destroys the transaction if the reference count drops to zero. If the application registered a callback function during initialization, that callback function notifies the application when the transaction changes state. If the application needs to use the transaction in the future, it must hold a reference to the transaction by using the sip_hold_trans() function to prevent the stack from destroying the transaction. After using the transaction the application must release the reference by using the sip_release_trans() function.

The four terminated states for transactions are listed below:

• Client invite terminated

• Client non-invite terminated

• Server invite terminated

• Server non-invite terminated

Transaction Lookup

An application can look up a transaction for a SIP message by using the sip_get_trans() function. A successful lookup returns the transaction and increments the transaction's reference count. The application must release the transaction by using the sip_release_trans() function after use.

Transaction Timers

The transaction layer maintains a set of timers for timing out transactions or sending retransmissions. Appendix A lists these timers. If the application initializes timeout reporting, the transaction layer notifies the application when a transaction times out.

Transaction And Network Errors

The transaction layer uses a cached connection object to send messages. In the event of a network error, the transaction layer releases the connection object and calls the error callback function, if the application provided one. If the callback function not does return a value of 0, or if the application does not provide a callback function, the stack terminates the transaction and frees the associated resources.