Transaction Layer Functions

const struct sip_xaction *sip_get_trans(sip_msg_t sip_msg, int which, int *error);

The *sip_get_trans() function returns the transaction that is associated with the SIP message in the sip_msg parameter. This function follows the specifications of sections 17.1.3 and 17.2.3 of RFC 3261 to determine a matching transaction. If this function finds a matching transaction, this call increments the reference count on the transaction. The calling thread must release the hold on the transaction by using the sip_release_trans() function. The which parameter specifies whether the transaction of interest is a client or a server transaction. When a client receives a response, the value of the which parameter is SIP_CLIENT_TRANSACTION. When a server gets a request, the value of the which parameter is SIP_SERVER_TRANSACTION.

The value of the error parameter is set to zero when this function completes successfully. When this function completes unsuccessfully, it sets the value of the error parameter to the appropriate error value.

sip_method_t sip_get_trans_method(sip_transaction_t sip_trans, int *error);

The sip_get_trans_method() function returns the method that created the transaction that is specified by the value of the sip_trans parameter.

The value of the error parameter is set to zero when this function completes successfully. When this function completes unsuccessfully, it sets the value of the error parameter to the appropriate error value.

int sip_get_trans_state(sip_transaction_t sip_trans, int *error);

The sip_get_trans_state() function returns the state of the transaction that is specified by the value of the sip_trans parameter. A CLIENT transaction can have the following states:

• SIP_CLNT_CALLING

• SIP_CLNT_INV_PROCEEDING

• SIP_CLNT_INV_COMPLETED

• SIP_CLNT_INV_TERMINATED

• SIP_CLNT_TRYING

• SIP_CLNT_NONINV_PROCEEDING

• SIP_CLNT_NONINV_COMPLETED

• SIP_CLNT_NONINV_TERMINATED

A SERVER transaction can have the following states:

• SIP_SRV_INV_PROCEEDING

• SIP_SRV_INV_COMPLETED

• SIP_SRV_CONFIRMED

• SIP_SRV_INV_TERMINATED

• SIP_SRV_TRYING

• SIP_SRV_NONINV_PROCEEDING

• SIP_SRV_NONINV_COMPLETED

• SIP_SRV_NONINV_TERMINATED

The value of the error parameter is set to zero when this function completes successfully. When this function completes unsuccessfully, it sets the value of the error parameter to the appropriate error value.

const struct sip_message *sip_get_trans_orig_msg(sip_transaction_t sip_trans, int *error);

The *sip_get_trans_orig_msg() function returns the original message that created this transaction. A client transaction returns the request. A server transaction returns the response sent to the transaction creating request.

The value of the error parameter is set to zero when this function completes successfully. When this function completes unsuccessfully, it sets the value of the error parameter to the appropriate error value.

const struct sip_conn_object *sip_get_trans_conn_obj(sip_transaction_t sip_trans, int *error);

The *sip_get_trans_conn_obj() function returns the cached connection object for the transaction that is specified by the value of the sip_trans parameter. This connection object is the object that the application passed in, along with the most recent message for this transaction.

The value of the error parameter is set to zero when this function completes successfully. When this function completes unsuccessfully, it sets the value of the error parameter to the appropriate error value.

void sip_hold_trans(sip_transaction_t sip_trans, int *error);

The sip_hold_trans() function increments the reference count on the transaction that is specified by the value of the sip_trans parameter. The caller of the sip_get_trans() function must call the sip_release_trans() function for the returned transaction after using the transaction.

The value of the error parameter is set to zero when this function completes successfully. When this function completes unsuccessfully, it sets the value of the error parameter to the appropriate error value.

void sip_release_trans(sip_transaction_t sip_trans, int *error);

The sip_release_trans() function decrements the reference count on the transaction that is specified by the value of the sip_trans parameter. The caller of the sip_get_trans() function must call the sip_release_trans() function for the returned transaction after using the transaction. If the reference count drops to zero and the transaction is in a terminated state, the stack destroys the transaction.

The value of the error parameter is set to zero when this function completes successfully. When this function completes unsuccessfully, it sets the value of the error parameter to the appropriate error value.