From cb88a08734906fe0e47fef54752d5928ae9d45ac Mon Sep 17 00:00:00 2001 From: Benny Prijono Date: Sun, 5 Mar 2006 11:53:36 +0000 Subject: Added API to terminate dialog prematurely. Affect: dialog, invite sessions, evsub, and presence git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@283 74dad513-b988-da41-8d7b-12977e46ad98 --- pjsip/include/pjsip-simple/evsub.h | 15 +++ pjsip/include/pjsip-simple/presence.h | 17 ++++ pjsip/include/pjsip-ua/sip_inv.h | 25 +++++ pjsip/include/pjsip/sip_dialog.h | 186 ++++++++++++++++++++++++++++++++-- pjsip/include/pjsip/sip_errno.h | 9 ++ 5 files changed, 242 insertions(+), 10 deletions(-) (limited to 'pjsip/include') diff --git a/pjsip/include/pjsip-simple/evsub.h b/pjsip/include/pjsip-simple/evsub.h index ba1dd0a6..0bcd63a9 100644 --- a/pjsip/include/pjsip-simple/evsub.h +++ b/pjsip/include/pjsip-simple/evsub.h @@ -287,6 +287,21 @@ PJ_DECL(pj_status_t) pjsip_evsub_create_uas( pjsip_dialog *dlg, unsigned option, pjsip_evsub **p_evsub); +/** + * Forcefully destroy the subscription session. This function should only + * be called on special condition, such as when the subscription + * initialization has failed. For other conditions, application MUST terminate + * the subscription by sending the appropriate un(SUBSCRIBE) or NOTIFY. + * + * @param sub The event subscription. + * @param notify Specify whether the state notification callback + * should be called. + * + * @return PJ_SUCCESS if subscription session has been destroyed. + */ +PJ_DECL(pj_status_t) pjsip_evsub_terminate( pjsip_evsub *sub, + pj_bool_t notify ); + /** * Get subscription state. diff --git a/pjsip/include/pjsip-simple/presence.h b/pjsip/include/pjsip-simple/presence.h index 8559d91d..f8d63527 100644 --- a/pjsip/include/pjsip-simple/presence.h +++ b/pjsip/include/pjsip-simple/presence.h @@ -128,6 +128,23 @@ PJ_DECL(pj_status_t) pjsip_pres_create_uas( pjsip_dialog *dlg, pjsip_evsub **p_evsub ); +/** + * Forcefully destroy the presence subscription. This function should only + * be called on special condition, such as when the subscription + * initialization has failed. For other conditions, application MUST terminate + * the subscription by sending the appropriate un(SUBSCRIBE) or NOTIFY. + * + * @param sub The presence subscription. + * @param notify Specify whether the state notification callback + * should be called. + * + * @return PJ_SUCCESS if subscription session has been destroyed. + */ +PJ_DECL(pj_status_t) pjsip_pres_terminate( pjsip_evsub *sub, + pj_bool_t notify ); + + + /** * Call this function to create request to initiate presence subscription, to * refresh subcription, or to request subscription termination. diff --git a/pjsip/include/pjsip-ua/sip_inv.h b/pjsip/include/pjsip-ua/sip_inv.h index f41a1d94..4939c9d3 100644 --- a/pjsip/include/pjsip-ua/sip_inv.h +++ b/pjsip/include/pjsip-ua/sip_inv.h @@ -169,6 +169,8 @@ struct pjsip_inv_session char obj_name[PJ_MAX_OBJ_NAME]; /**< Log identification. */ pj_pool_t *pool; /**< Dialog's pool. */ pjsip_inv_state state; /**< Invite sess state. */ + pjsip_status_code cause; /**< Disconnect cause. */ + pj_bool_t notify; /**< Internal. */ pjsip_dialog *dlg; /**< Underlying dialog. */ pjsip_role_e role; /**< Invite role. */ unsigned options; /**< Options in use. */ @@ -332,6 +334,29 @@ PJ_DECL(pj_status_t) pjsip_inv_create_uas(pjsip_dialog *dlg, pjsip_inv_session **p_inv); +/** + * Forcefully terminate and destroy INVITE session, regardless of + * the state of the session. Note that this function should only be used + * when there is failure in the INVITE session creation. After the + * invite session has been created and initialized, normally application + * SHOULD use #pjsip_inv_end_session() to end the INVITE session instead. + * + * Note also that this function may terminate the underlying dialog, if + * there are no other sessions in the dialog. + * + * @param inv The invite session. + * @param st_code Status code for the reason of the termination. + * @param notify If set to non-zero, then on_state_changed() + * callback will be called. + * + * @return PJ_SUCCESS if the INVITE session has been + * terminated. + */ +PJ_DECL(pj_status_t) pjsip_inv_terminate( pjsip_inv_session *inv, + int st_code, + pj_bool_t notify ); + + /** * Create the initial INVITE request for this session. This function can only * be called for UAC session. If local media capability is specified when diff --git a/pjsip/include/pjsip/sip_dialog.h b/pjsip/include/pjsip/sip_dialog.h index 27ea7980..42ce7ba1 100644 --- a/pjsip/include/pjsip/sip_dialog.h +++ b/pjsip/include/pjsip/sip_dialog.h @@ -59,7 +59,19 @@ enum pjsip_dialog_state }; /** - * This structure describes the dialog structure. + * This structure describes the dialog structure. Application MUST NOT + * try to SET the values here directly, but instead it MUST use the + * appropriate dialog API. The dialog declaration only needs to be made + * visible because other PJSIP modules need to see it (e.g. INVITE session, + * the event framework, etc.). + * + * Application MAY READ the dialog contents directly after it acquires + * dialog lock. + * + * To acquire dialog lock, use #pjsip_dlg_inc_lock(), and to release it, + * use #pjsip_dlg_dec_lock(). DO NOT USE pj_mutex_lock()/pj_mutex_unlock() + * on the dialog's mutex directly, because this will not protect against + * dialog being destroyed. */ struct pjsip_dialog { @@ -69,7 +81,8 @@ struct pjsip_dialog /* Dialog's system properties. */ char obj_name[PJ_MAX_OBJ_NAME]; /**< Standard id. */ pj_pool_t *pool; /**< Dialog's pool. */ - pj_mutex_t *mutex; /**< Dialog's mutex. */ + pj_mutex_t *mutex; /**< Dialog's mutex. Do not call!! + Use pjsip_dlg_inc_lock() instead! */ pjsip_user_agent *ua; /**< User agent instance. */ pjsip_endpoint *endpt; /**< Endpoint instance. */ @@ -89,17 +102,18 @@ struct pjsip_dialog pjsip_auth_clt_sess auth_sess; /**< Client authentication session. */ /** Session counter. */ - int sess_count; + int sess_count; /**< Number of sessions. */ /** Transaction counter. */ - int tsx_count; + int tsx_count; /**< Number of pending transactions. */ /* Dialog usages. */ unsigned usage_cnt; /**< Number of registered usages. */ - pjsip_module *usage[PJSIP_MAX_MODULE]; /**< Array of usages, priority sorted */ + pjsip_module *usage[PJSIP_MAX_MODULE]; /**< Array of usages, + priority sorted */ /** Module specific data. */ - void *mod_data[PJSIP_MAX_MODULE]; + void *mod_data[PJSIP_MAX_MODULE]; /**< Module data. */ }; @@ -107,6 +121,10 @@ struct pjsip_dialog * This utility function returns PJ_TRUE if the specified method is a * dialog creating request. This method property is used to determine * whether Contact header should be included in outgoing request. + * + * @param m The SIP method. + * + * @return PJ_TRUE if the method creates a dialog. */ PJ_DECL(pj_bool_t) pjsip_method_creates_dialog(const pjsip_method *m); @@ -124,6 +142,19 @@ PJ_DECL(pj_bool_t) pjsip_method_creates_dialog(const pjsip_method *m); * * Note that initially, the session count in the dialog will be initialized * to zero. + * + * @param ua The user agent module instance. + * @param local_uri Dialog local URI (i.e. From header). + * @param local_contact_uri Optional dialog local Contact URI. + * If this argument is NULL, the Contact will be + * taken from the local URI. + * @param remote_uri Dialog remote URI (i.e. To header). + * @param target Optional initial remote target. If this argument + * is NULL, the initial target will be set to + * remote URI. + * @param p_dlg Pointer to receive the dialog. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_create_uac( pjsip_user_agent *ua, const pj_str_t *local_uri, @@ -146,6 +177,18 @@ PJ_DECL(pj_status_t) pjsip_dlg_create_uac( pjsip_user_agent *ua, * * Note that initially, the session count in the dialog will be initialized * to zero. + * + * + * @param ua The user agent module instance. + * @param rdata The incoming request that creates the dialog, + * such as INVITE, SUBSCRIBE, or REFER. + * @param contact Optional URI to be used as local Contact. If + * this argument is NULL, the local contact will be + * initialized from the value of To header in the + * request. + * @param p_dlg Pointer to receive the dialog. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_create_uas( pjsip_user_agent *ua, pjsip_rx_data *rdata, @@ -162,11 +205,32 @@ PJ_DECL(pj_status_t) pjsip_dlg_create_uas( pjsip_user_agent *ua, * * Note that initially, the session count in the dialog will be initialized * to zero. + * + * @param original_dlg The original UAC dialog. + * @param rdata The incoming forked response message. + * @param new_dlg Pointer to receive the new dialog. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_fork(const pjsip_dialog *original_dlg, const pjsip_rx_data *rdata, pjsip_dialog **new_dlg ); +/** + * Forcefully terminate the dialog. Application can only call this function + * when there is no session associated to the dialog. If there are sessions + * that use this dialog, this function will refuse to terminate the dialog. + * For this case, application MUST call the appropriate termination function + * for each dialog session (e.g. #pjsip_inv_terminate() to terminate INVITE + * session). + * + * @param dlg The dialog. + * + * @return PJ_SUCCESS if dialog has been terminated. + */ +PJ_DECL(pj_status_t) pjsip_dlg_terminate( pjsip_dialog *dlg ); + + /** * Set dialog's initial route set to route_set list. This can only be called * for UAC dialog, before any request is sent. After dialog has been @@ -177,6 +241,11 @@ PJ_DECL(pj_status_t) pjsip_dlg_fork(const pjsip_dialog *original_dlg, * * The route_set argument is standard list of Route headers (i.e. with * sentinel). + * + * @param dlg The UAC dialog. + * @param route_set List of Route header. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_set_route_set( pjsip_dialog *dlg, const pjsip_route_hdr *route_set ); @@ -184,6 +253,11 @@ PJ_DECL(pj_status_t) pjsip_dlg_set_route_set( pjsip_dialog *dlg, /** * Increment the number of sessions in the dialog. Note that initially * (after created) the dialog has the session counter set to zero. + * + * @param dlg The dialog. + * @param mod The module that increments the session counter. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_inc_session( pjsip_dialog *dlg, pjsip_module *mod); @@ -194,12 +268,24 @@ PJ_DECL(pj_status_t) pjsip_dlg_inc_session( pjsip_dialog *dlg, * reach zero and there is no pending transaction, the dialog will be * destroyed. Note that this function may destroy the dialog immediately * if there is no pending transaction when this function is called. + * + * @param dlg The dialog. + * @param mod The module that decrements the session counter. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_dec_session( pjsip_dialog *dlg, pjsip_module *mod); /** * Add a module as dialog usage, and optionally set the module specific data. + * + * @param dlg The dialog. + * @param module The module to be registered as dialog usage. + * @param mod_data Optional arbitrary data to be attached to dialog's + * mod_data array at the module's index. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_add_usage( pjsip_dialog *dlg, pjsip_module *module, @@ -208,6 +294,13 @@ PJ_DECL(pj_status_t) pjsip_dlg_add_usage( pjsip_dialog *dlg, /** * Attach module specific data to the dialog. Application can also set * the value directly by accessing dlg->mod_data[module_id]. + * + * @param dlg The dialog + * @param mod_id The ID of the module from which the data is to be + * set to the dialog. + * @param data Arbitrary data. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_set_mod_data( pjsip_dialog *dlg, int mod_id, @@ -216,6 +309,12 @@ PJ_DECL(pj_status_t) pjsip_dlg_set_mod_data( pjsip_dialog *dlg, /** * Get module specific data previously attached to the dialog. Application * can also get value directly by accessing dlg->mod_data[module_id]. + * + * @param dlg The dialog + * @param mod_id The ID of the module from which the data is to be + * retrieved from the dialog. + * + * @return The data that was previously set, or NULL. */ PJ_DECL(void*) pjsip_dlg_get_mod_data( pjsip_dialog *dlg, int mod_id); @@ -224,12 +323,16 @@ PJ_DECL(void*) pjsip_dlg_get_mod_data( pjsip_dialog *dlg, /** * Lock dialog and increment session counter termporarily, to prevent it * from being destroyed. + * + * @param dlg The dialog. */ PJ_DECL(void) pjsip_dlg_inc_lock( pjsip_dialog *dlg ); /** * Unlock dialog and decrement temporary session counter. After this function * is called, dialog may be destroyed. + * + * @param dlg The dialog. */ PJ_DECL(void) pjsip_dlg_dec_lock( pjsip_dialog *dlg ); @@ -239,11 +342,26 @@ PJ_DECL(void) pjsip_dlg_dec_lock( pjsip_dialog *dlg ); * matches an existing dialog, the user agent must have put the matching * dialog instance in the rdata, or otherwise this function will return * NULL if the message didn't match any existing dialog. + * + * This function can only be called after endpoint distributes the message + * to the transaction layer or UA layer. In other words, application can + * only call this function in the context of module that runs in priority + * number higher than PJSIP_MOD_PRIORITY_UA_PROXY_LAYER. + * + * @param rdata Incoming message buffer. + * + * @return The dialog instance that "owns" the message. */ PJ_DECL(pjsip_dialog*) pjsip_rdata_get_dlg( pjsip_rx_data *rdata ); /** - * Get the associated dialog in a transaction. + * Get the associated dialog for the specified transaction, if any. + * + * @param tsx The transaction. + * + * @return The dialog instance which has been registered + * to the transaction as transaction user, or + * NULL if the transaction is outside any dialogs. */ PJ_DECL(pjsip_dialog*) pjsip_tsx_get_dlg( pjsip_transaction *tsx ); @@ -256,6 +374,16 @@ PJ_DECL(pjsip_dialog*) pjsip_tsx_get_dlg( pjsip_transaction *tsx ); * INVITE request as the parameter. * * This function will also put Contact header where appropriate. + * + * @param dlg The dialog instance. + * @param method The method of the request. + * @param cseq Optional CSeq, which only needs to be specified + * when creating ACK and CANCEL. For other requests, + * specify -1 to use dialog's internal counter. + * @param tdata Pointer to receive the request's transmit + * data buffer. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_create_request( pjsip_dialog *dlg, const pjsip_method *method, @@ -277,6 +405,13 @@ PJ_DECL(pj_status_t) pjsip_dlg_create_request( pjsip_dialog *dlg, * * This function will decrement the transmit data's reference counter * regardless the status of the operation. + * + * @param dlg The dialog. + * @param tdata The request message to be sent. + * @param p_tsx Optional argument to receive the transaction + * instance used to send the request. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_send_request ( pjsip_dialog *dlg, pjsip_tx_data *tdata, @@ -289,6 +424,16 @@ PJ_DECL(pj_status_t) pjsip_dlg_send_request ( pjsip_dialog *dlg, * than endpoint's API #pjsip_endpt_create_response() in that the dialog * function adds Contact header and Record-Routes headers in the response * where appropriate. + * + * @param dlg The dialog. + * @param rdata The incoming request message for which the + * response will be created. + * @param st_code Status code. + * @param st_text Optional string for custom status reason text. + * @param tdata Pointer to receive the response message transmit + * data buffer. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_create_response( pjsip_dialog *dlg, pjsip_rx_data *rdata, @@ -300,6 +445,14 @@ PJ_DECL(pj_status_t) pjsip_dlg_create_response( pjsip_dialog *dlg, /** * Modify previously sent response with other status code. Contact header * will be added when appropriate. + * + * @param dlg The dialog. + * @param tdata The transmit data buffer containing response + * message to be modified. + * @param st_code New status code to be set. + * @param st_text Optional string for custom status reason text. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_modify_response( pjsip_dialog *dlg, pjsip_tx_data *tdata, @@ -313,6 +466,17 @@ PJ_DECL(pj_status_t) pjsip_dlg_modify_response( pjsip_dialog *dlg, * * This function decrements the transmit data's reference counter regardless * the status of the operation. + * + * @param dlg The dialog. + * @param tsx The UAS transaction associated with the incoming + * request. If the request is within a dialog, or + * a dialog has been created for the request that + * creates the dialog, application can get the + * transaction instance for the request by calling + * #pjsip_rdata_get_tsx(). + * @param tdata Response message to be sent. + * + * @return PJ_SUCCESS on success. */ PJ_DECL(pj_status_t) pjsip_dlg_send_response( pjsip_dialog *dlg, pjsip_transaction *tsx, @@ -340,6 +504,11 @@ PJ_DECL(pj_status_t) pjsip_dlg_respond( pjsip_dialog *dlg, const pjsip_hdr *hdr_list, const pjsip_msg_body *body ); + +/** + * @} + */ + /* * Internal (called by sip_ua_layer.c) */ @@ -356,9 +525,6 @@ void pjsip_dlg_on_rx_response( pjsip_dialog *dlg, pjsip_rx_data *rdata ); -/** - * @} - */ PJ_END_DECL diff --git a/pjsip/include/pjsip/sip_errno.h b/pjsip/include/pjsip/sip_errno.h index 89153344..c4195a13 100644 --- a/pjsip/include/pjsip/sip_errno.h +++ b/pjsip/include/pjsip/sip_errno.h @@ -363,6 +363,15 @@ PJ_BEGIN_DECL */ #define PJSIP_ENOREFERSESSION (PJSIP_ERRNO_START_PJSIP+122) /* 171122 */ +/************************************************************ + * INVITE SESSIONS ERRORS + ***********************************************************/ +/** + * @hideinitializer + * Session already terminated. + */ +#define PJSIP_ESESSIONTERMINATED (PJSIP_ERRNO_START_PJSIP+140) /* 171140 */ + -- cgit v1.2.3