BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

Transaction instance for all types of SIP transactions.The pjsip_transaction describes SIP transaction, and is used for both INVITE and non-INVITE, UAC or UAS. Application must register the transaction layer module with pjsip_tsx_layer_init_module() before performing any stateful operations. More...

Data Structures

struct  pjsip_transaction
 

Enumerations

enum  pjsip_tsx_state_e {
  PJSIP_TSX_STATE_NULL, PJSIP_TSX_STATE_CALLING, PJSIP_TSX_STATE_TRYING, PJSIP_TSX_STATE_PROCEEDING,
  PJSIP_TSX_STATE_COMPLETED, PJSIP_TSX_STATE_CONFIRMED, PJSIP_TSX_STATE_TERMINATED, PJSIP_TSX_STATE_DESTROYED,
  PJSIP_TSX_STATE_MAX
}
 

Functions

pj_status_t pjsip_tsx_layer_init_module (pjsip_endpoint *endpt)
 
pjsip_modulepjsip_tsx_layer_instance (void)
 
pj_status_t pjsip_tsx_layer_destroy (void)
 
unsigned pjsip_tsx_layer_get_tsx_count (void)
 
pjsip_transactionpjsip_tsx_layer_find_tsx (const pj_str_t *key, pj_bool_t lock)
 
pjsip_transactionpjsip_tsx_layer_find_tsx2 (const pj_str_t *key, pj_bool_t add_ref)
 
pj_status_t pjsip_tsx_create_uac (pjsip_module *tsx_user, pjsip_tx_data *tdata, pjsip_transaction **p_tsx)
 
pj_status_t pjsip_tsx_create_uac2 (pjsip_module *tsx_user, pjsip_tx_data *tdata, pj_grp_lock_t *grp_lock, pjsip_transaction **p_tsx)
 
pj_status_t pjsip_tsx_create_uas (pjsip_module *tsx_user, pjsip_rx_data *rdata, pjsip_transaction **p_tsx)
 
pj_status_t pjsip_tsx_create_uas2 (pjsip_module *tsx_user, pjsip_rx_data *rdata, pj_grp_lock_t *grp_lock, pjsip_transaction **p_tsx)
 
pj_status_t pjsip_tsx_set_transport (pjsip_transaction *tsx, const pjsip_tpselector *sel)
 
void pjsip_tsx_recv_msg (pjsip_transaction *tsx, pjsip_rx_data *rdata)
 
pj_status_t pjsip_tsx_send_msg (pjsip_transaction *tsx, pjsip_tx_data *tdata)
 
pj_status_t pjsip_tsx_retransmit_no_state (pjsip_transaction *tsx, pjsip_tx_data *tdata)
 
pj_status_t pjsip_tsx_create_key (pj_pool_t *pool, pj_str_t *key, pjsip_role_e role, const pjsip_method *method, const pjsip_rx_data *rdata)
 
pj_status_t pjsip_tsx_terminate (pjsip_transaction *tsx, int code)
 
pj_status_t pjsip_tsx_stop_retransmit (pjsip_transaction *tsx)
 
pj_status_t pjsip_tsx_set_timeout (pjsip_transaction *tsx, unsigned millisec)
 
pjsip_transactionpjsip_rdata_get_tsx (pjsip_rx_data *rdata)
 

Detailed Description

Enumeration Type Documentation

◆ pjsip_tsx_state_e

This enumeration represents transaction state.

Enumerator
PJSIP_TSX_STATE_NULL 

For UAC, before any message is sent.

PJSIP_TSX_STATE_CALLING 

For UAC, just after request is sent.

PJSIP_TSX_STATE_TRYING 

For UAS, just after request is received.

PJSIP_TSX_STATE_PROCEEDING 

For UAS/UAC, after provisional response.

PJSIP_TSX_STATE_COMPLETED 

For UAS/UAC, after final response.

PJSIP_TSX_STATE_CONFIRMED 

For UAS, after ACK is received.

PJSIP_TSX_STATE_TERMINATED 

For UAS/UAC, before it's destroyed.

PJSIP_TSX_STATE_DESTROYED 

For UAS/UAC, will be destroyed now.

PJSIP_TSX_STATE_MAX 

Number of states.

Function Documentation

◆ pjsip_tsx_layer_init_module()

pj_status_t pjsip_tsx_layer_init_module ( pjsip_endpoint endpt)

Create and register transaction layer module to the specified endpoint.

Parameters
endptThe endpoint instance.
Returns
PJ_SUCCESS on success.

◆ pjsip_tsx_layer_instance()

pjsip_module* pjsip_tsx_layer_instance ( void  )

Get the instance of the transaction layer module.

Returns
The transaction layer module.

◆ pjsip_tsx_layer_destroy()

pj_status_t pjsip_tsx_layer_destroy ( void  )

Unregister and destroy transaction layer module.

Returns
PJ_SUCCESS on success.

◆ pjsip_tsx_layer_get_tsx_count()

unsigned pjsip_tsx_layer_get_tsx_count ( void  )

Retrieve the current number of transactions currently registered in the hash table.

Returns
Number of transactions.

◆ pjsip_tsx_layer_find_tsx()

pjsip_transaction* pjsip_tsx_layer_find_tsx ( const pj_str_t key,
pj_bool_t  lock 
)

Find a transaction with the specified key. The transaction key normally is created by calling pjsip_tsx_create_key() from an incoming message.

IMPORTANT: To prevent deadlock, application should use pjsip_tsx_layer_find_tsx2() instead which only adds a reference to the transaction instead of locking it.

Parameters
keyThe key string to find the transaction.
lockIf non-zero, transaction will be locked before the function returns, to make sure that it's not deleted by other threads.
Returns
The matching transaction instance, or NULL if transaction can not be found.

◆ pjsip_tsx_layer_find_tsx2()

pjsip_transaction* pjsip_tsx_layer_find_tsx2 ( const pj_str_t key,
pj_bool_t  add_ref 
)

Find a transaction with the specified key. The transaction key normally is created by calling pjsip_tsx_create_key() from an incoming message.

Parameters
keyThe key string to find the transaction.
add_refIf non-zero, transaction's reference will be added by one before the function returns, to make sure that it's not deleted by other threads.
Returns
The matching transaction instance, or NULL if transaction can not be found.

◆ pjsip_tsx_create_uac()

pj_status_t pjsip_tsx_create_uac ( pjsip_module tsx_user,
pjsip_tx_data tdata,
pjsip_transaction **  p_tsx 
)

Create, initialize, and register a new transaction as UAC from the specified transmit data (tdata). The transmit data must have a valid Request-Line and CSeq header.

If Via header does not exist, it will be created along with a unique branch parameter. If it exists and contains branch parameter, then the branch parameter will be used as is as the transaction key. If it exists but branch parameter doesn't exist, a unique branch parameter will be created.

Parameters
tsx_userModule to be registered as transaction user of the new transaction, which will receive notification from the transaction via on_tsx_state() callback.
tdataThe outgoing request message.
p_tsxOn return will contain the new transaction instance.
Returns
PJ_SUCCESS if successfull.

◆ pjsip_tsx_create_uac2()

pj_status_t pjsip_tsx_create_uac2 ( pjsip_module tsx_user,
pjsip_tx_data tdata,
pj_grp_lock_t grp_lock,
pjsip_transaction **  p_tsx 
)

Variant of pjsip_tsx_create_uac() with additional parameter to specify the group lock to use. Group lock can be used to synchronize locking among several objects to prevent deadlock, and to synchronize the lifetime of objects sharing the same group lock.

See pjsip_tsx_create_uac() for general info about this function.

Parameters
tsx_userModule to be registered as transaction user of the new transaction, which will receive notification from the transaction via on_tsx_state() callback.
tdataThe outgoing request message.
grp_lockOptional group lock to use by this transaction. If the value is NULL, the transaction will create its own group lock.
p_tsxOn return will contain the new transaction instance.
Returns
PJ_SUCCESS if successfull.

◆ pjsip_tsx_create_uas()

pj_status_t pjsip_tsx_create_uas ( pjsip_module tsx_user,
pjsip_rx_data rdata,
pjsip_transaction **  p_tsx 
)

Create, initialize, and register a new transaction as UAS from the specified incoming request in rdata. After calling this function, application MUST call pjsip_tsx_recv_msg() so that transaction moves from state NULL.

Parameters
tsx_userModule to be registered as transaction user of the new transaction, which will receive notification from the transaction via on_tsx_state() callback.
rdataThe received incoming request.
p_tsxOn return will contain the new transaction instance.
Returns
PJ_SUCCESS if successfull.

◆ pjsip_tsx_create_uas2()

pj_status_t pjsip_tsx_create_uas2 ( pjsip_module tsx_user,
pjsip_rx_data rdata,
pj_grp_lock_t grp_lock,
pjsip_transaction **  p_tsx 
)

Variant of pjsip_tsx_create_uas() with additional parameter to specify the group lock to use. Group lock can be used to synchronize locking among several objects to prevent deadlock, and to synchronize the lifetime of objects sharing the same group lock.

See pjsip_tsx_create_uas() for general info about this function.

Parameters
tsx_userModule to be registered as transaction user of the new transaction, which will receive notification from the transaction via on_tsx_state() callback.
rdataThe received incoming request.
grp_lockOptional group lock to use by this transaction. If the value is NULL, the transaction will create its own group lock.
p_tsxOn return will contain the new transaction instance.
Returns
PJ_SUCCESS if successfull.

◆ pjsip_tsx_set_transport()

pj_status_t pjsip_tsx_set_transport ( pjsip_transaction tsx,
const pjsip_tpselector sel 
)

Lock/bind transaction to a specific transport/listener. This is optional, as normally transport will be selected automatically based on the destination of the message upon resolver completion.

Parameters
tsxThe transaction.
selTransport selector containing the specification of transport or listener to be used by this transaction to send requests.
Returns
PJ_SUCCESS on success, or the appropriate error code.

◆ pjsip_tsx_recv_msg()

void pjsip_tsx_recv_msg ( pjsip_transaction tsx,
pjsip_rx_data rdata 
)

Call this function to manually feed a message to the transaction. For UAS transaction, application MUST call this function after UAS transaction has been created.

This function SHOULD only be called to pass initial request message to UAS transaction. Before this function returns, on_tsx_state() callback of the transaction user will be called. If response message is passed to this function, then on_rx_response() will also be called before on_tsx_state().

Parameters
tsxThe transaction.
rdataThe message.

◆ pjsip_tsx_send_msg()

pj_status_t pjsip_tsx_send_msg ( pjsip_transaction tsx,
pjsip_tx_data tdata 
)

Transmit message in tdata with this transaction. It is possible to pass NULL in tdata for UAC transaction, which in this case the last message transmitted, or the request message which was specified when calling pjsip_tsx_create_uac(), will be sent.

This function decrements the reference counter of the transmit buffer only when it returns PJ_SUCCESS;

Parameters
tsxThe transaction.
tdataThe outgoing message. If NULL is specified, then the last message transmitted (or the message specified in UAC initialization) will be sent.
Returns
PJ_SUCCESS if successfull.

◆ pjsip_tsx_retransmit_no_state()

pj_status_t pjsip_tsx_retransmit_no_state ( pjsip_transaction tsx,
pjsip_tx_data tdata 
)

Manually retransmit the last message transmitted by this transaction, without updating the transaction state. This function is useful when TU wants to maintain the retransmision by itself (for example, retransmitting reliable provisional response).

Parameters
tsxThe transaction.
tdataThe outgoing message. If NULL is specified, then the last message transmitted (or the message specified in UAC initialization) will be sent.
Returns
PJ_SUCCESS if successful.

◆ pjsip_tsx_create_key()

pj_status_t pjsip_tsx_create_key ( pj_pool_t pool,
pj_str_t key,
pjsip_role_e  role,
const pjsip_method method,
const pjsip_rx_data rdata 
)

Create transaction key, which is used to match incoming requests or response (retransmissions) against transactions.

Parameters
poolThe pool
keyOutput key.
roleThe role of the transaction.
methodThe method to be put as a key.
rdataThe received data to calculate.
Returns
PJ_SUCCESS or the appropriate error code.

◆ pjsip_tsx_terminate()

pj_status_t pjsip_tsx_terminate ( pjsip_transaction tsx,
int  code 
)

Force terminate transaction.

Parameters
tsxThe transaction.
codeThe status code to report.

◆ pjsip_tsx_stop_retransmit()

pj_status_t pjsip_tsx_stop_retransmit ( pjsip_transaction tsx)

Cease retransmission on the UAC transaction. The UAC transaction is still considered running, and it will complete when either final response is received or the transaction times out.

This operation normally is used for INVITE transaction only, when the transaction is cancelled before any provisional response has been received.

Parameters
tsxThe transaction.
Returns
PJ_SUCCESS or the appropriate error code.

◆ pjsip_tsx_set_timeout()

pj_status_t pjsip_tsx_set_timeout ( pjsip_transaction tsx,
unsigned  millisec 
)

Start a timer to terminate transaction after the specified time has elapsed. This function is only valid for INVITE transaction, and only before final response is received for the INVITE transaction. It is normally called after the UAC has sent CANCEL for this INVITE transaction.

The purpose of this function is to terminate the transaction if UAS does not send final response to this INVITE transaction even after it sends 200/OK to CANCEL (for example when the UAS complies to RFC 2543).

Once this timer is set, the transaction will be terminated either when a final response is received or the timer expires.

Parameters
tsxThe transaction.
millisecTimeout value in milliseconds.
Returns
PJ_SUCCESS or the appropriate error code.

◆ pjsip_rdata_get_tsx()

pjsip_transaction* pjsip_rdata_get_tsx ( pjsip_rx_data rdata)

Get the transaction instance in the incoming message. If the message has a corresponding transaction, this function will return non NULL value.

Parameters
rdataThe incoming message buffer.
Returns
The transaction instance associated with this message, or NULL if the message doesn't match any transactions.

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.