@voipsdk/react-native-voipcloud 1.0.0 → 1.0.2

package/ios/VoipCloud.xcframework/ios-arm64_x86_64-simulator/Headers/pjsip/sip_transaction.h

@@ -0,0 +1,542 @@
+/* 
+ * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
+ * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
+ */
+#ifndef __PJSIP_SIP_TRANSACTION_H__
+#define __PJSIP_SIP_TRANSACTION_H__
+
+/**
+ * @file sip_transaction.h
+ * @brief SIP Transaction
+ */
+
+#include <pjsip/sip_msg.h>
+#include <pjsip/sip_util.h>
+#include <pjsip/sip_transport.h>
+#include <pj/timer.h>
+
+PJ_BEGIN_DECL
+
+/**
+ * @defgroup PJSIP_TRANSACT Transaction Layer
+ * @brief Provides statefull message processing.
+ *
+ * This module provides stateful processing to incoming or outgoing SIP
+ * messages. 
+ * Before performing any stateful operations, application must register the
+ * transaction layer module by calling #pjsip_tsx_layer_init_module().
+ *
+ * Application should link with <b>pjsip-core</b> library to
+ * use the transaction layer.
+ */
+
+/**
+ * @defgroup PJSIP_TRANSACT_TRANSACTION Transaction
+ * @ingroup PJSIP_TRANSACT
+ * @brief 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.
+ */
+
+/**
+ * This enumeration represents transaction state.
+ */
+typedef enum pjsip_tsx_state_e
+{
+    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.                      */
+} pjsip_tsx_state_e;
+
+
+/**
+ * This structure describes SIP transaction object. The transaction object
+ * is used to handle both UAS and UAC transaction.
+ */
+struct pjsip_transaction
+{
+    /*
+     * Administrivia
+     */
+    pj_pool_t                  *pool;           /**< Pool owned by the tsx. */
+    pjsip_module               *tsx_user;       /**< Transaction user.      */
+    pjsip_endpoint             *endpt;          /**< Endpoint instance.     */
+    pj_bool_t                   terminating;    /**< terminate() was called */
+    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.         */
+
+    /*
+     * Transaction identification.
+     */
+    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_str_t                    transaction_key;/**< Hash table key.        */
+    pj_str_t                    transaction_key2;/**< Hash table key (2)   
+                                                     for merged requests
+                                                     tsx lookup.            */
+    pj_uint32_t                 hashed_key;     /**< Key's hashed value.    */
+    pj_uint32_t                 hashed_key2;    /**< Key's hashed value (2).*/
+    pj_str_t                    branch;         /**< The branch Id.         */
+
+    /*
+     * State and status.
+     */
+    int                         status_code;    /**< Last status code seen. */
+    pj_str_t                    status_text;    /**< Last reason phrase.    */
+    pjsip_tsx_state_e           state;          /**< State.                 */
+    int                         handle_200resp; /**< UAS 200/INVITE  retrsm.*/
+    int                         tracing;        /**< Tracing enabled?       */
+
+    /** Handler according to current state. */
+    pj_status_t (*state_handler)(struct pjsip_transaction *, pjsip_event *);
+
+    /*
+     * Transport.
+     */
+    pjsip_transport            *transport;      /**< Transport to use.      */
+    pj_bool_t                   is_reliable;    /**< Transport is reliable. */
+    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.                   */
+
+    /*
+     * Messages and timer.
+     */
+    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.         */
+
+    /** Module specific data. */
+    void                       *mod_data[PJSIP_MAX_MODULE];
+};
+
+
+/**
+ * Create and register transaction layer module to the specified endpoint.
+ *
+ * @param endpt     The endpoint instance.
+ *
+ * @return          PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_layer_init_module(pjsip_endpoint *endpt);
+
+/**
+ * Get the instance of the transaction layer module.
+ *
+ * @return          The transaction layer module.
+ */
+PJ_DECL(pjsip_module*) pjsip_tsx_layer_instance(void);
+
+/**
+ * Unregister and destroy transaction layer module.
+ *
+ * @return          PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_layer_destroy(void);
+
+/**
+ * Retrieve the current number of transactions currently registered
+ * in the hash table.
+ *
+ * @return          Number of transactions.
+ */
+PJ_DECL(unsigned) pjsip_tsx_layer_get_tsx_count(void);
+
+/**
+ * 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.
+ *
+ * @param key       The key string to find the transaction.
+ * @param lock      If non-zero, transaction will be locked before the
+ *                  function returns, to make sure that it's not deleted
+ *                  by other threads.
+ *
+ * @return          The matching transaction instance, or NULL if transaction
+ *                  can not be found.
+ */
+PJ_DECL(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.
+ *
+ * @param key       The key string to find the transaction.
+ * @param 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.
+ *
+ * @return          The matching transaction instance, or NULL if transaction
+ *                  can not be found.
+ */
+PJ_DECL(pjsip_transaction*) pjsip_tsx_layer_find_tsx2( const pj_str_t *key,
+                                                       pj_bool_t add_ref );
+
+/**
+ * Create, initialize, and register a new transaction as UAC from the 
+ * specified transmit data (\c tdata). The transmit data must have a valid
+ * \c Request-Line and \c CSeq header. 
+ *
+ * If \c Via header does not exist, it will be created along with a unique
+ * \c branch parameter. If it exists and contains branch parameter, then
+ * the \c 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.
+ *
+ * @param 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.
+ * @param tdata     The outgoing request message.
+ * @param p_tsx     On return will contain the new transaction instance.
+ *
+ * @return          PJ_SUCCESS if successfull.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_create_uac( pjsip_module *tsx_user,
+                                           pjsip_tx_data *tdata,
+                                           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.
+ *
+ * @param 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.
+ * @param tdata     The outgoing request message.
+ * @param grp_lock  Optional group lock to use by this transaction. If
+ *                  the value is NULL, the transaction will create its
+ *                  own group lock.
+ * @param p_tsx     On return will contain the new transaction instance.
+ *
+ * @return          PJ_SUCCESS if successfull.
+ */
+PJ_DECL(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);
+
+/**
+ * Create, initialize, and register a new transaction as UAS from the
+ * specified incoming request in \c rdata. After calling this function,
+ * application MUST call #pjsip_tsx_recv_msg() so that transaction
+ * moves from state NULL.
+ *
+ * @param 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.
+ * @param rdata     The received incoming request.
+ * @param p_tsx     On return will contain the new transaction instance.
+ *
+ * @return          PJ_SUCCESS if successfull.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_create_uas( pjsip_module *tsx_user,
+                                           pjsip_rx_data *rdata,
+                                           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.
+ *
+ * @param 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.
+ * @param rdata     The received incoming request.
+ * @param grp_lock  Optional group lock to use by this transaction. If
+ *                  the value is NULL, the transaction will create its
+ *                  own group lock.
+ * @param p_tsx     On return will contain the new transaction instance.
+ *
+ * @return          PJ_SUCCESS if successfull.
+ */
+PJ_DECL(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 );
+
+/**
+ * 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.
+ *
+ * @param rdata     The received incoming request.
+ *
+ * @return          The matching transaction, if any, or NULL.
+ */
+PJ_DECL(pjsip_transaction *)
+pjsip_tsx_detect_merged_requests(pjsip_rx_data *rdata);
+
+/**
+ * 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.
+ *
+ * @param tsx       The transaction.
+ * @param sel       Transport selector containing the specification of
+ *                  transport or listener to be used by this transaction
+ *                  to send requests.
+ *
+ * @return          PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_set_transport(pjsip_transaction *tsx,
+                                             const pjsip_tpselector *sel);
+
+/**
+ * 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().
+ *
+ * @param tsx       The transaction.
+ * @param rdata     The message.
+ */
+PJ_DECL(void) pjsip_tsx_recv_msg( pjsip_transaction *tsx, 
+                                  pjsip_rx_data *rdata);
+
+/**
+ * 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;
+ *
+ * @param tsx       The transaction.
+ * @param tdata     The outgoing message. If NULL is specified, then the
+ *                  last message transmitted (or the message specified 
+ *                  in UAC initialization) will be sent.
+ *
+ * @return          PJ_SUCCESS if successfull.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_send_msg( 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).
+ *
+ * @param tsx       The transaction.
+ * @param tdata     The outgoing message. If NULL is specified, then the
+ *                  last message transmitted (or the message specified 
+ *                  in UAC initialization) will be sent.
+ *
+ *
+ * @return          PJ_SUCCESS if successful.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_retransmit_no_state(pjsip_transaction *tsx,
+                                                   pjsip_tx_data *tdata);
+
+
+/**
+ * Create transaction key, which is used to match incoming requests 
+ * or response (retransmissions) against transactions.
+ *
+ * @param pool      The pool
+ * @param key       Output key.
+ * @param role      The role of the transaction.
+ * @param method    The method to be put as a key. 
+ * @param rdata     The received data to calculate.
+ *
+ * @return          PJ_SUCCESS or the appropriate error code.
+ */
+PJ_DECL(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 );
+
+/**
+ * Force terminate transaction.
+ *
+ * @param tsx       The transaction.
+ * @param code      The status code to report.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_terminate( pjsip_transaction *tsx,
+                                          int code );
+
+
+/**
+ * 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.
+ *
+ * @param tsx       The transaction.
+ *
+ * @return          PJ_SUCCESS or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_stop_retransmit(pjsip_transaction *tsx);
+
+
+/**
+ * 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.
+ *
+ * @param tsx       The transaction.
+ * @param millisec  Timeout value in milliseconds.
+ *
+ * @return          PJ_SUCCESS or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsip_tsx_set_timeout(pjsip_transaction *tsx,
+                                           unsigned millisec);
+
+
+/**
+ * Change timer values used by transaction layer. Currently scheduled
+ * timers will not be changed. Any value set to 0 will be left
+ * unchanged.
+ *
+ * @param t1        Transaction T1 timeout, in msec
+ * @param t2        Transaction T2 timeout, in msec
+ * @param t4        Transaction completed timer for non-INVITE, in msec
+ * @param td        Transaction completed timer for INVITE, in msec
+ */
+PJ_DECL(void) pjsip_tsx_set_timers(unsigned t1, unsigned t2, unsigned t4,
+                                   unsigned td);
+
+
+/**
+ * (Re)Initializes timer values from pjsip_cfg().
+ */
+PJ_DECL(void) pjsip_tsx_initialize_timer_values(void);
+
+
+/**
+ * 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.
+ *
+ * @param max       Maximum retransmission count.
+ */
+PJ_DECL(void) pjsip_tsx_set_max_retransmit_count(int max);
+
+
+/**
+ * Get the transaction instance in the incoming message. If the message
+ * has a corresponding transaction, this function will return non NULL
+ * value.
+ *
+ * @param rdata     The incoming message buffer.
+ *
+ * @return          The transaction instance associated with this message,
+ *                  or NULL if the message doesn't match any transactions.
+ */
+PJ_DECL(pjsip_transaction*) pjsip_rdata_get_tsx( pjsip_rx_data *rdata );
+
+
+/**
+ * @}
+ */
+
+/*
+ * Internal.
+ */
+
+/**
+ * Dump transaction layer.
+ */
+PJ_DECL(void) pjsip_tsx_layer_dump(pj_bool_t detail);
+
+/**
+ * Get the string name for the state.
+ * @param state State
+ */
+PJ_DECL(const char *) pjsip_tsx_state_str(pjsip_tsx_state_e state);
+
+/**
+ * Get the role name.
+ * @param role  Role.
+ */
+PJ_DECL(const char *) pjsip_role_name(pjsip_role_e role);
+
+
+PJ_END_DECL
+
+#endif  /* __PJSIP_TRANSACT_H__ */
+