Group PJSIP_TRANSACT_TRANSACTION
- group PJSIP_TRANSACT_TRANSACTION
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.
Enums
-
enum pjsip_tsx_state_e
This enumeration represents transaction state.
Values:
-
enumerator PJSIP_TSX_STATE_NULL
For UAC, before any message is sent.
-
enumerator PJSIP_TSX_STATE_CALLING
For UAC, just after request is sent.
-
enumerator PJSIP_TSX_STATE_TRYING
For UAS, just after request is received.
-
enumerator PJSIP_TSX_STATE_PROCEEDING
For UAS/UAC, after provisional response.
-
enumerator PJSIP_TSX_STATE_COMPLETED
For UAS/UAC, after final response.
-
enumerator PJSIP_TSX_STATE_CONFIRMED
For UAS, after ACK is received.
-
enumerator PJSIP_TSX_STATE_TERMINATED
For UAS/UAC, before it’s destroyed.
-
enumerator PJSIP_TSX_STATE_DESTROYED
For UAS/UAC, will be destroyed now.
-
enumerator PJSIP_TSX_STATE_MAX
Number of states.
-
enumerator PJSIP_TSX_STATE_NULL
Functions
-
pj_status_t pjsip_tsx_layer_init_module(pjsip_endpoint *endpt)
Create and register transaction layer module to the specified endpoint.
- Parameters:
endpt – The endpoint instance.
- Returns:
PJ_SUCCESS on success.
-
pjsip_module *pjsip_tsx_layer_instance(void)
Get the instance of the transaction layer module.
- Returns:
The transaction layer module.
-
pj_status_t pjsip_tsx_layer_destroy(void)
Unregister and destroy transaction layer module.
- Returns:
PJ_SUCCESS on success.
-
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_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:
key – The key string to find the transaction.
lock – If 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_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:
key – The key string to find the transaction.
add_ref – If 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.
-
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 validRequest-Line
andCSeq
header.If
Via
header does not exist, it will be created along with a uniquebranch
parameter. If it exists and contains branch parameter, then thebranch
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_user – Module to be registered as transaction user of the new transaction, which will receive notification from the transaction via on_tsx_state() callback.
tdata – The outgoing request message.
p_tsx – On return will contain the new transaction instance.
- Returns:
PJ_SUCCESS if successfull.
-
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_user – Module to be registered as transaction user of the new transaction, which will receive notification from the transaction via on_tsx_state() callback.
tdata – The outgoing request message.
grp_lock – Optional group lock to use by this transaction. If the value is NULL, the transaction will create its own group lock.
p_tsx – On return will contain the new transaction instance.
- Returns:
PJ_SUCCESS if successfull.
-
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_user – Module to be registered as transaction user of the new transaction, which will receive notification from the transaction via on_tsx_state() callback.
rdata – The received incoming request.
p_tsx – On return will contain the new transaction instance.
- Returns:
PJ_SUCCESS if successfull.
-
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_user – Module to be registered as transaction user of the new transaction, which will receive notification from the transaction via on_tsx_state() callback.
rdata – The received incoming request.
grp_lock – Optional group lock to use by this transaction. If the value is NULL, the transaction will create its own group lock.
p_tsx – On return will contain the new transaction instance.
- Returns:
PJ_SUCCESS if successfull.
-
pjsip_transaction *pjsip_tsx_detect_merged_requests(pjsip_rx_data *rdata)
Detect merged requests according to RFC 3261 section 8.2.2.2: If the request has no tag in the To header field, the function will check the request against ongoing transactions. If the From tag, Call-ID, and CSeq exactly match those associated with an ongoing transaction, but the request does not match that transaction based on the matching rules described in section 17.2.3, the function will return that transaction.
- Parameters:
rdata – The received incoming request.
- Returns:
The matching transaction, if any, or NULL.
-
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:
tsx – The transaction.
sel – Transport 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.
-
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:
tsx – The transaction.
rdata – The message.
-
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:
tsx – The transaction.
tdata – The 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.
-
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:
tsx – The transaction.
tdata – The 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.
-
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:
pool – The pool
key – Output key.
role – The role of the transaction.
method – The method to be put as a key.
rdata – The received data to calculate.
- Returns:
PJ_SUCCESS or the appropriate error code.
-
pj_status_t pjsip_tsx_terminate(pjsip_transaction *tsx, int code)
Force terminate transaction.
- Parameters:
tsx – The transaction.
code – The status code to report.
- Returns:
PJ_SUCCESS or the appropriate error code.
-
pj_status_t pjsip_tsx_terminate_async(pjsip_transaction *tsx, int code)
Force terminate transaction asynchronously, using the transaction internal timer.
- Parameters:
tsx – The transaction.
code – The status code to report.
- Returns:
PJ_SUCCESS or the appropriate error code.
-
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:
tsx – The transaction.
- Returns:
PJ_SUCCESS or the appropriate error code.
-
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:
tsx – The transaction.
millisec – Timeout value in milliseconds.
- Returns:
PJ_SUCCESS or the appropriate error code.
-
void pjsip_tsx_set_timers(unsigned t1, unsigned t2, unsigned t4, unsigned td)
Change timer values used by transaction layer. Currently scheduled timers will not be changed. Any value set to 0 will be left unchanged.
- Parameters:
t1 – Transaction T1 timeout, in msec
t2 – Transaction T2 timeout, in msec
t4 – Transaction completed timer for non-INVITE, in msec
td – Transaction completed timer for INVITE, in msec
-
void pjsip_tsx_initialize_timer_values(void)
(Re)Initializes timer values from pjsip_cfg().
-
void pjsip_tsx_set_max_retransmit_count(int max)
Set maximum retransmission count in transaction layer for outgoing requests. When retransmission counter reaches the specified number, the transaction will be considered timeout. This will affect any ongoing transactions immediately.
By default (or when this is set to -1), retransmission number will not cause a transaction to be timeout, only the timer settings will cause transaction timeout. Also, this will not override the timer settings, i.e: if the timeout timer occurs before the maximum retransmission is reached, the transaction will still gets timeout.
When this is set to zero or possitive number P, a transaction timeout will occur right before the retransmission number (P+1). For example, if this is set to 1 there will be two transmissions: the initial transmission and one retransmission, before the transaction gets timeout.
- Parameters:
max – Maximum retransmission count.
-
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:
rdata – The incoming message buffer.
- Returns:
The transaction instance associated with this message, or NULL if the message doesn’t match any transactions.
-
struct pjsip_transaction
- #include <sip_transaction.h>
This structure describes SIP transaction object. The transaction object is used to handle both UAS and UAC transaction.
Forward declaration for transactions (sip_transaction.h).
Public Members
-
pjsip_module *tsx_user
Transaction user.
-
pjsip_endpoint *endpt
Endpoint instance.
-
pj_grp_lock_t *grp_lock
Transaction grp lock.
-
pj_mutex_t *mutex_b
Second mutex to avoid deadlock. It is used to protect timer.
-
char obj_name[PJ_MAX_OBJ_NAME]
Log info.
-
pjsip_role_e role
Role (UAS or UAC)
-
pjsip_method method
The method.
-
pj_int32_t cseq
The CSeq
-
pj_uint32_t hashed_key
Key’s hashed value.
-
pj_uint32_t hashed_key2
Key’s hashed value (2).
-
int status_code
Last status code seen.
-
pjsip_tsx_state_e state
State.
-
int handle_200resp
UAS 200/INVITE retrsm.
-
int tracing
Tracing enabled?
-
pj_status_t (*state_handler)(struct pjsip_transaction*, pjsip_event*)
Handler according to current state.
-
pjsip_transport *transport
Transport to use.
-
pj_sockaddr addr
Destination address.
-
int addr_len
Address length.
-
pjsip_response_addr res_addr
Response address.
-
unsigned transport_flag
Miscelaneous flag.
-
pj_status_t transport_err
Internal error code.
-
pjsip_tpselector tp_sel
Transport selector.
-
pjsip_tx_data *pending_tx
Tdata which caused pending transport flag to be set on tsx.
-
pjsip_tp_state_listener_key *tp_st_key
Transport state listener key.
-
pjsip_tx_data *last_tx
Msg kept for retrans.
-
int retransmit_count
Retransmission count.
-
pj_timer_entry retransmit_timer
Retransmit timer.
-
pj_timer_entry timeout_timer
Timeout timer.
-
void *mod_data[PJSIP_MAX_MODULE]
Module specific data.
-
pjsip_module *tsx_user
-
enum pjsip_tsx_state_e