diff options
author | Benny Prijono <bennylp@teluu.com> | 2007-01-12 06:37:35 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2007-01-12 06:37:35 +0000 |
commit | 7567c6b90e8e0dd20204a579cd548ad7ae00febf (patch) | |
tree | faadb7133a618fe5b1551b3ea89717eec860bee3 /pjsip/include | |
parent | 5058236717c4a44f02a1507b2833e8cff8f54083 (diff) |
Workaround for ticket #50: added API to lock/bind transaction, dialog, and regc to a specific transport/listener
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@879 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjsip/include')
-rw-r--r-- | pjsip/include/pjsip-ua/sip_regc.h | 27 | ||||
-rw-r--r-- | pjsip/include/pjsip/sip_dialog.h | 28 | ||||
-rw-r--r-- | pjsip/include/pjsip/sip_endpoint.h | 21 | ||||
-rw-r--r-- | pjsip/include/pjsip/sip_errno.h | 8 | ||||
-rw-r--r-- | pjsip/include/pjsip/sip_transaction.h | 22 | ||||
-rw-r--r-- | pjsip/include/pjsip/sip_transport.h | 120 |
6 files changed, 215 insertions, 11 deletions
diff --git a/pjsip/include/pjsip-ua/sip_regc.h b/pjsip/include/pjsip-ua/sip_regc.h index 04f2752d..683c3d48 100644 --- a/pjsip/include/pjsip-ua/sip_regc.h +++ b/pjsip/include/pjsip-ua/sip_regc.h @@ -26,6 +26,7 @@ #include <pjsip/sip_types.h> #include <pjsip/sip_auth.h> +#include <pjsip/sip_transport.h> /** @@ -198,6 +199,32 @@ PJ_DECL(pj_status_t) pjsip_regc_set_credentials( pjsip_regc *regc, PJ_DECL(pj_status_t) pjsip_regc_set_route_set(pjsip_regc *regc, const pjsip_route_hdr*route_set); + +/** + * Lock/bind client registration 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 client registration is explicitly bound to the specific + * transport/listener, all UAC transactions originated by the client + * registration will use the specified transport/listener when sending + * outgoing requests. + * + * Note that this doesn't affect the Contact header set for this client + * registration. Application must manually update the Contact header if + * necessary, to adjust the address according to the transport being + * selected. + * + * @param regc The client registration instance. + * @param sel Transport selector containing the specification of + * transport or listener to be used by this session + * to send requests. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_regc_set_transport(pjsip_regc *regc, + const pjsip_tpselector *sel); + + /** * Add headers to be added to outgoing REGISTER requests. * diff --git a/pjsip/include/pjsip/sip_dialog.h b/pjsip/include/pjsip/sip_dialog.h index b4d2a1ac..9cea4ded 100644 --- a/pjsip/include/pjsip/sip_dialog.h +++ b/pjsip/include/pjsip/sip_dialog.h @@ -28,6 +28,7 @@ #include <pjsip/sip_msg.h> #include <pjsip/sip_auth.h> #include <pjsip/sip_errno.h> +#include <pjsip/sip_transport.h> #include <pj/sock.h> #include <pj/assert.h> @@ -134,6 +135,9 @@ struct pjsip_dialog /** Transaction counter. */ int tsx_count; /**< Number of pending transactions. */ + /** Transport selector. */ + pjsip_tpselector tp_sel; + /* Dialog usages. */ unsigned usage_cnt; /**< Number of registered usages. */ pjsip_module *usage[PJSIP_MAX_MODULE]; /**< Array of usages, @@ -224,6 +228,30 @@ PJ_DECL(pj_status_t) pjsip_dlg_create_uas( pjsip_user_agent *ua, /** + * 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 * new remote tag as copied from the To header in the response. Upon return, diff --git a/pjsip/include/pjsip/sip_endpoint.h b/pjsip/include/pjsip/sip_endpoint.h index 34413d7c..7f264908 100644 --- a/pjsip/include/pjsip/sip_endpoint.h +++ b/pjsip/include/pjsip/sip_endpoint.h @@ -352,18 +352,29 @@ PJ_DECL(pj_ioqueue_t*) pjsip_endpt_get_ioqueue(pjsip_endpoint *endpt); /** * 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. + * 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_transport_get + * @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) pjsip_endpt_acquire_transport( pjsip_endpoint *endpt, pjsip_transport_type_e type, const pj_sockaddr_t *remote, int addr_len, - pjsip_transport **p_transport); + const pjsip_tpselector *sel, + pjsip_transport **p_tp); /***************************************************************************** diff --git a/pjsip/include/pjsip/sip_errno.h b/pjsip/include/pjsip/sip_errno.h index 10b542c7..bd0fecaf 100644 --- a/pjsip/include/pjsip/sip_errno.h +++ b/pjsip/include/pjsip/sip_errno.h @@ -214,6 +214,14 @@ PJ_BEGIN_DECL * transmit data has been deleted on return of pjsip_tx_data_dec_ref(). */ #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 */ /************************************************************ diff --git a/pjsip/include/pjsip/sip_transaction.h b/pjsip/include/pjsip/sip_transaction.h index e15fd13d..dfd00339 100644 --- a/pjsip/include/pjsip/sip_transaction.h +++ b/pjsip/include/pjsip/sip_transaction.h @@ -26,6 +26,7 @@ #include <pjsip/sip_msg.h> #include <pjsip/sip_util.h> +#include <pjsip/sip_transport.h> #include <pj/timer.h> PJ_BEGIN_DECL @@ -96,6 +97,7 @@ struct pjsip_transaction pj_str_t transaction_key;/**< Hash table key. */ pj_uint32_t hashed_key; /**< Key's hashed value. */ pj_str_t branch; /**< The branch Id. */ + pjsip_tpselector tp_sel; /**< Transport selector. */ /* * State and status. @@ -214,6 +216,26 @@ PJ_DECL(pj_status_t) pjsip_tsx_create_uas( pjsip_module *tsx_user, /** + * 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 * UAS transaction has been created. diff --git a/pjsip/include/pjsip/sip_transport.h b/pjsip/include/pjsip/sip_transport.h index 4c9120e9..30516de7 100644 --- a/pjsip/include/pjsip/sip_transport.h +++ b/pjsip/include/pjsip/sip_transport.h @@ -55,6 +55,13 @@ PJ_BEGIN_DECL * *****************************************************************************/ +/* + * Forward declaration for transport factory (since it is referenced by + * the transport factory itself). + */ +typedef struct pjsip_tpfactory pjsip_tpfactory; + + /** * Flags for SIP transports. */ @@ -156,6 +163,76 @@ pjsip_transport_get_default_port_for_type(pjsip_transport_type_e type); PJ_DECL(const char*) pjsip_transport_get_type_name(pjsip_transport_type_e t); + +/***************************************************************************** + * + * 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); + + /***************************************************************************** * * RECEIVE DATA BUFFER. @@ -431,6 +508,14 @@ struct pjsip_tx_data char dst_name[16]; /**< Destination address. */ 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,6 +584,20 @@ PJ_DECL(void) pjsip_tx_data_invalidate_msg( pjsip_tx_data *tdata ); */ 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); + /***************************************************************************** * @@ -706,12 +805,6 @@ PJ_DECL(pj_ssize_t) pjsip_tpmgr_receive_packet(pjsip_tpmgr *mgr, * *****************************************************************************/ -/* - * Forward declaration for transport factory (since it is referenced by - * the transport factory itself). - */ -typedef struct pjsip_tpfactory pjsip_tpfactory; - /** * A transport factory is normally used for connection oriented transports @@ -859,11 +952,26 @@ PJ_DECL(void) pjsip_tpmgr_dump_transports(pjsip_tpmgr *mgr); /** * 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, pjsip_transport_type_e type, const pj_sockaddr_t *remote, int addr_len, + const pjsip_tpselector *sel, pjsip_transport **tp); |