Changeset 879 for pjproject/trunk/pjsip/include/pjsip

Timestamp:

Jan 12, 2007 6:37:35 AM (17 years ago)

Author:

bennylp

Message:

Workaround for ticket #50: added API to lock/bind transaction, dialog, and regc to a specific transport/listener

Location:

pjproject/trunk/pjsip/include/pjsip

Files:

• sip_dialog.h (modified) (3 diffs)
• sip_endpoint.h (modified) (2 diffs)
• sip_errno.h (modified) (1 diff)
• sip_transaction.h (modified) (3 diffs)
• sip_transport.h (modified) (7 diffs)

pjproject/trunk/pjsip/include/pjsip/sip_dialog.h

@@ -29 +29 @@
 #include <pjsip/sip_auth.h>
 #include <pjsip/sip_errno.h>
+#include <pjsip/sip_transport.h>
 #include <pj/sock.h>
 #include <pj/assert.h>
@@ -135 +136 @@
     int                 tsx_count;  /**< Number of pending transactions.    */
 
+    /** Transport selector. */
+    pjsip_tpselector    tp_sel;
+
     /* Dialog usages. */
     unsigned            usage_cnt;  /**< Number of registered usages.       */
@@ -225 +229 @@
 
 /**
+ * Lock/bind dialog to a specific transport/listener. This is optional,
+ * as normally transport will be selected automatically based on the 
+ * destination of requests upon resolver completion. When the dialog is 
+ * explicitly bound to the specific transport/listener, all UAC transactions
+ * originated by this dialog will use the specified transport/listener
+ * when sending outgoing requests.
+ *
+ * Note that this doesn't affect the Contact header generated by this
+ * dialog. Application must manually update the Contact header if
+ * necessary, to adjust the address according to the transport being
+ * selected.
+ *
+ * @param dlg       The dialog instance.
+ * @param sel       Transport selector containing the specification of
+ *                  transport or listener to be used by this dialog
+ *                  to send requests.
+ *
+ * @return          PJ_SUCCESS on success, or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjsip_dlg_set_transport(pjsip_dialog *dlg,
+                                             const pjsip_tpselector *sel);
+
+
+/**
  * Create a new (forked) dialog on receipt on forked response in rdata. 
  * The new dialog will be created from original_dlg, except that it will have

pjproject/trunk/pjsip/include/pjsip/sip_endpoint.h

@@ -353 +353 @@
 /**
  * Find a SIP transport suitable for sending SIP message to the specified
- * address. This function will complete asynchronously when the transport is
- * ready (for example, when TCP socket is connected), and when it completes,
- * the callback will be called with the status of the operation.
- *
- * @see pjsip_transport_get
+ * address. If transport selector ("sel") is set, then the function will
+ * check if the transport selected is suitable to send requests to the
+ * specified address.
+ *
+ * @see pjsip_tpmgr_acquire_transport
+ *
+ * @param endpt     The SIP endpoint instance.
+ * @param type      The type of transport to be acquired.
+ * @param remote    The remote address to send message to.
+ * @param addr_len  Length of the remote address.
+ * @param sel       Optional pointer to transport selector instance which is
+ *                  used to find explicit transport, if required.
+ * @param p_tp      Pointer to receive the transport instance, if one is found.
+ *
+ * @return          PJ_SUCCESS on success, or the appropriate error code.
  */
 PJ_DECL(pj_status_t) 
@@ -364 +374 @@
                                const pj_sockaddr_t *remote,
                                int addr_len,
-                               pjsip_transport **p_transport);
+                               const pjsip_tpselector *sel,
+                               pjsip_transport **p_tp);
 
 

pjproject/trunk/pjsip/include/pjsip/sip_errno.h

@@ -215 +215 @@
  */
 #define PJSIP_EBUFDESTROYED     (PJSIP_ERRNO_START_PJSIP + 63)  /* 171063 */
+/**
+ * @hideinitializer
+ * Unsuitable transport selected. This error occurs when application
+ * has explicitly requested to use a particular transport/listener,
+ * but the selected transport is not suitable to send request to
+ * the specified destination.
+ */
+#define PJSIP_ETPNOTSUITABLE    (PJSIP_ERRNO_START_PJSIP + 64)  /* 171064 */
 
 

pjproject/trunk/pjsip/include/pjsip/sip_transaction.h

@@ -27 +27 @@
 #include <pjsip/sip_msg.h>
 #include <pjsip/sip_util.h>
+#include <pjsip/sip_transport.h>
 #include <pj/timer.h>
 
@@ -97 +98 @@
     pj_uint32_t                 hashed_key;     /**< Key's hashed value.    */
     pj_str_t                    branch;         /**< The branch Id.         */
+    pjsip_tpselector            tp_sel;         /**< Transport selector.    */
 
     /*
@@ -215 +217 @@
 
 /**
+ * Lock/bind transaction to a specific transport/listener. This is optional,
+ * as normally transport will be selected automatically based on the 
+ * destination of the request upon resolver completion. Also it's only valid
+ * for UAC transaction (to send outgoing request), since for UAS the
+ * transport will be selected according to rules about handling incoming
+ * request (most likely it will use the transport where the request is
+ * coming from if ";rport" parameter is present in Via header).
+ *
+ * @param tsx       The UAC 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

pjproject/trunk/pjsip/include/pjsip/sip_transport.h

@@ -55 +55 @@
  *
  *****************************************************************************/
+
+/*
+ * Forward declaration for transport factory (since it is referenced by
+ * the transport factory itself).
+ */
+typedef struct pjsip_tpfactory pjsip_tpfactory;
+
 
 /**
@@ -157 +164 @@
 
 
+
+/*****************************************************************************
+ *
+ * TRANSPORT SELECTOR.
+ *
+ *****************************************************************************/
+
+/**
+ * This structure describes the type of data in pjsip_tpselector.
+ */
+typedef enum pjsip_tpselector_type
+{
+    /** Transport is not specified. */
+    PJSIP_TPSELECTOR_NONE,
+
+    /** Use the specific transport to send request. */
+    PJSIP_TPSELECTOR_TRANSPORT,
+
+    /** Use the specific listener to send request. */
+    PJSIP_TPSELECTOR_LISTENER,
+
+} pjsip_tpselector_type;
+
+
+/**
+ * This structure describes the transport/listener preference to be used
+ * when sending outgoing requests.
+ *
+ * Normally transport will be selected automatically according to rules about
+ * sending requests. But some applications (such as proxies or B2BUAs) may 
+ * want to explicitly use specific transport to send requests, for example
+ * when they want to make sure that outgoing request should go from a specific
+ * network interface.
+ *
+ * The pjsip_tpselector structure is used for that purpose, i.e. to allow
+ * application specificly request that a particular transport/listener
+ * should be used to send request. This structure is used when calling
+ * pjsip_tsx_set_transport() and pjsip_dlg_set_transport().
+ */
+typedef struct pjsip_tpselector
+{
+    /** The type of data in the union */
+    pjsip_tpselector_type   type;
+
+    /** Union representing the transport/listener criteria to be used. */
+    union {
+        pjsip_transport *transport;
+        pjsip_tpfactory *listener;
+    } u;
+
+} pjsip_tpselector;
+
+
+/**
+ * Add transport/listener reference in the selector to prevent the specified
+ * transport/listener from being destroyed while application still has
+ * reference to it.
+ *
+ * @param sel   The transport selector.
+ */
+PJ_DECL(void) pjsip_tpselector_add_ref(pjsip_tpselector *sel);
+
+
+/**
+ * Decrement transport/listener reference in the selector.
+ * @param sel   The transport selector
+ */
+PJ_DECL(void) pjsip_tpselector_dec_ref(pjsip_tpselector *sel);
+
+
 /*****************************************************************************
  *
@@ -432 +509 @@
         int                  dst_port;      /**< Destination port.      */
     } tp_info;
+
+    /** 
+     * Transport selector, to specify which transport to be used. 
+     * The value here must be set with pjsip_tx_data_set_transport(),
+     * to allow reference counter to be set properly.
+     */
+    pjsip_tpselector        tp_sel;
+
 };
 
@@ -499 +584 @@
  */
 PJ_DECL(char*) pjsip_tx_data_get_info( pjsip_tx_data *tdata );
+
+/**
+ * Set the explicit transport to be used when sending this transmit data.
+ * Application should not need to call this function, but rather use
+ * pjsip_tsx_set_transport() and pjsip_dlg_set_transport() instead (which
+ * will call this function).
+ *
+ * @param tdata     The transmit buffer.
+ * @param sel       Transport selector.
+ *
+ * @return          PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjsip_tx_data_set_transport(pjsip_tx_data *tdata,
+                                                 const pjsip_tpselector *sel);
 
 
@@ -707 +806 @@
  *****************************************************************************/
 
-/*
- * Forward declaration for transport factory (since it is referenced by
- * the transport factory itself).
- */
-typedef struct pjsip_tpfactory pjsip_tpfactory;
-
 
 /**
@@ -860 +953 @@
  * Find transport to be used to send message to remote destination. If no
  * suitable transport is found, a new one will be created.
+ *
+ * This is an internal function since normally application doesn't have access
+ * to transport manager. Application should use pjsip_endpt_acquire_transport()
+ * instead.
+ *
+ * @param mgr       The transport manager instance.
+ * @param type      The type of transport to be acquired.
+ * @param remote    The remote address to send message to.
+ * @param addr_len  Length of the remote address.
+ * @param sel       Optional pointer to transport selector instance which is
+ *                  used to find explicit transport, if required.
+ * @param tp        Pointer to receive the transport instance, if one is found.
+ *
+ * @return          PJ_SUCCESS on success, or the appropriate error code.
  */
 PJ_DECL(pj_status_t) pjsip_tpmgr_acquire_transport(pjsip_tpmgr *mgr,
@@ -865 +972 @@
                                                    const pj_sockaddr_t *remote,
                                                    int addr_len,
+                                                   const pjsip_tpselector *sel,
                                                    pjsip_transport **tp);