Ignore:
Timestamp:
Mar 5, 2006 11:53:36 AM (18 years ago)
Author:
bennylp
Message:

Added API to terminate dialog prematurely. Affect: dialog, invite sessions, evsub, and presence

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r265 r283  
    6060 
    6161/** 
    62  * This structure describes the dialog structure. 
     62 * This structure describes the dialog structure. Application MUST NOT 
     63 * try to SET the values here directly, but instead it MUST use the 
     64 * appropriate dialog API. The dialog declaration only needs to be made  
     65 * visible because other PJSIP modules need to see it (e.g. INVITE session, 
     66 * the event framework, etc.). 
     67 * 
     68 * Application MAY READ the dialog contents directly after it acquires 
     69 * dialog lock. 
     70 * 
     71 * To acquire dialog lock, use #pjsip_dlg_inc_lock(), and to release it, 
     72 * use #pjsip_dlg_dec_lock(). DO NOT USE pj_mutex_lock()/pj_mutex_unlock() 
     73 * on the dialog's mutex directly, because this will not protect against 
     74 * dialog being destroyed. 
    6375 */ 
    6476struct pjsip_dialog 
    … …  
    7082    char                obj_name[PJ_MAX_OBJ_NAME];  /**< Standard id.       */ 
    7183    pj_pool_t          *pool;       /**< Dialog's pool.                     */ 
    72     pj_mutex_t         *mutex;      /**< Dialog's mutex.                    */ 
     84    pj_mutex_t         *mutex;      /**< Dialog's mutex. Do not call!! 
     85                                         Use pjsip_dlg_inc_lock() instead!  */ 
    7386    pjsip_user_agent   *ua;         /**< User agent instance.               */ 
    7487    pjsip_endpoint     *endpt;      /**< Endpoint instance.                 */ 
    … …  
    90103 
    91104    /** Session counter. */ 
    92     int                 sess_count; 
     105    int                 sess_count; /**< Number of sessions.                */ 
    93106 
    94107    /** Transaction counter. */ 
    95     int                 tsx_count; 
     108    int                 tsx_count;  /**< Number of pending transactions.    */ 
    96109 
    97110    /* Dialog usages. */ 
    98111    unsigned            usage_cnt;  /**< Number of registered usages.       */ 
    99     pjsip_module       *usage[PJSIP_MAX_MODULE]; /**< Array of usages, priority sorted   */ 
     112    pjsip_module       *usage[PJSIP_MAX_MODULE]; /**< Array of usages,  
     113                                         priority sorted                    */ 
    100114 
    101115    /** Module specific data. */ 
    102     void               *mod_data[PJSIP_MAX_MODULE]; 
     116    void               *mod_data[PJSIP_MAX_MODULE]; /**< Module data.       */ 
    103117}; 
    104118 
    … …  
    108122 * dialog creating request. This method property is used to determine 
    109123 * whether Contact header should be included in outgoing request. 
     124 * 
     125 * @param m             The SIP method. 
     126 * 
     127 * @return              PJ_TRUE if the method creates a dialog. 
    110128 */ 
    111129PJ_DECL(pj_bool_t) pjsip_method_creates_dialog(const pjsip_method *m); 
    … …  
    125143 * Note that initially, the session count in the dialog will be initialized  
    126144 * to zero. 
     145 * 
     146 * @param ua                The user agent module instance. 
     147 * @param local_uri         Dialog local URI (i.e. From header). 
     148 * @param local_contact_uri Optional dialog local Contact URI.  
     149 *                          If this argument is NULL, the Contact will be 
     150 *                          taken from the local URI. 
     151 * @param remote_uri        Dialog remote URI (i.e. To header). 
     152 * @param target            Optional initial remote target. If this argument 
     153 *                          is NULL, the initial target will be set to 
     154 *                          remote URI. 
     155 * @param p_dlg             Pointer to receive the dialog. 
     156 * 
     157 * @return                  PJ_SUCCESS on success. 
    127158 */ 
    128159PJ_DECL(pj_status_t) pjsip_dlg_create_uac( pjsip_user_agent *ua, 
    … …  
    147178 * Note that initially, the session count in the dialog will be initialized  
    148179 * to zero. 
     180 * 
     181 * 
     182 * @param ua                The user agent module instance. 
     183 * @param rdata             The incoming request that creates the dialog, 
     184 *                          such as INVITE, SUBSCRIBE, or REFER. 
     185 * @param contact           Optional URI to be used as local Contact. If 
     186 *                          this argument is NULL, the local contact will be 
     187 *                          initialized from the value of To header in the 
     188 *                          request. 
     189 * @param p_dlg             Pointer to receive the dialog. 
     190 * 
     191 * @return                  PJ_SUCCESS on success. 
    149192 */ 
    150193PJ_DECL(pj_status_t) pjsip_dlg_create_uas(  pjsip_user_agent *ua, 
    … …  
    163206 * Note that initially, the session count in the dialog will be initialized  
    164207 * to zero. 
     208 * 
     209 * @param original_dlg      The original UAC dialog. 
     210 * @param rdata             The incoming forked response message. 
     211 * @param new_dlg           Pointer to receive the new dialog. 
     212 * 
     213 * @return                  PJ_SUCCESS on success. 
    165214 */ 
    166215PJ_DECL(pj_status_t) pjsip_dlg_fork(const pjsip_dialog *original_dlg, 
    … …  
    169218 
    170219/** 
     220 * Forcefully terminate the dialog. Application can only call this function 
     221 * when there is no session associated to the dialog. If there are sessions 
     222 * that use this dialog, this function will refuse to terminate the dialog. 
     223 * For this case, application MUST call the appropriate termination function  
     224 * for each dialog session (e.g. #pjsip_inv_terminate() to terminate INVITE 
     225 * session). 
     226 * 
     227 * @param dlg               The dialog. 
     228 * 
     229 * @return                  PJ_SUCCESS if dialog has been terminated. 
     230 */ 
     231PJ_DECL(pj_status_t) pjsip_dlg_terminate( pjsip_dialog *dlg ); 
     232 
     233 
     234/** 
    171235 * Set dialog's initial route set to route_set list. This can only be called 
    172236 * for UAC dialog, before any request is sent. After dialog has been  
    … …  
    178242 * The route_set argument is standard list of Route headers (i.e. with  
    179243 * sentinel). 
     244 * 
     245 * @param dlg               The UAC dialog. 
     246 * @param route_set         List of Route header. 
     247 * 
     248 * @return                  PJ_SUCCESS on success. 
    180249 */ 
    181250PJ_DECL(pj_status_t) pjsip_dlg_set_route_set( pjsip_dialog *dlg, 
    … …  
    185254 * Increment the number of sessions in the dialog. Note that initially  
    186255 * (after created) the dialog has the session counter set to zero. 
     256 * 
     257 * @param dlg               The dialog. 
     258 * @param mod               The module that increments the session counter. 
     259 * 
     260 * @return                  PJ_SUCCESS on success. 
    187261 */ 
    188262PJ_DECL(pj_status_t) pjsip_dlg_inc_session( pjsip_dialog *dlg, 
    … …  
    195269 * destroyed. Note that this function may destroy the dialog immediately  
    196270 * if there is no pending transaction when this function is called. 
     271 * 
     272 * @param dlg               The dialog. 
     273 * @param mod               The module that decrements the session counter. 
     274 * 
     275 * @return                  PJ_SUCCESS on success. 
    197276 */ 
    198277PJ_DECL(pj_status_t) pjsip_dlg_dec_session( pjsip_dialog *dlg, 
    … …  
    201280/** 
    202281 * Add a module as dialog usage, and optionally set the module specific data. 
     282 * 
     283 * @param dlg               The dialog. 
     284 * @param module            The module to be registered as dialog usage. 
     285 * @param mod_data          Optional arbitrary data to be attached to dialog's 
     286 *                          mod_data array at the module's index. 
     287 * 
     288 * @return                  PJ_SUCCESS on success. 
    203289 */ 
    204290PJ_DECL(pj_status_t) pjsip_dlg_add_usage( pjsip_dialog *dlg, 
    … …  
    209295 * Attach module specific data to the dialog. Application can also set  
    210296 * the value directly by accessing dlg->mod_data[module_id]. 
     297 * 
     298 * @param dlg               The dialog 
     299 * @param mod_id            The ID of the module from which the data is to be 
     300 *                          set to the dialog. 
     301 * @param data              Arbitrary data. 
     302 * 
     303 * @return                  PJ_SUCCESS on success. 
    211304 */ 
    212305PJ_DECL(pj_status_t) pjsip_dlg_set_mod_data( pjsip_dialog *dlg, 
    … …  
    217310 * Get module specific data previously attached to the dialog. Application 
    218311 * can also get value directly by accessing dlg->mod_data[module_id]. 
     312 * 
     313 * @param dlg               The dialog 
     314 * @param mod_id            The ID of the module from which the data is to be 
     315 *                          retrieved from the dialog. 
     316 * 
     317 * @return                  The data that was previously set, or NULL. 
    219318 */ 
    220319PJ_DECL(void*) pjsip_dlg_get_mod_data( pjsip_dialog *dlg, 
    … …  
    225324 * Lock dialog and increment session counter termporarily, to prevent it  
    226325 * from being destroyed. 
     326 * 
     327 * @param dlg               The dialog. 
    227328 */ 
    228329PJ_DECL(void) pjsip_dlg_inc_lock( pjsip_dialog *dlg ); 
    … …  
    231332 * Unlock dialog and decrement temporary session counter. After this function 
    232333 * is called, dialog may be destroyed. 
     334 * 
     335 * @param dlg               The dialog. 
    233336 */ 
    234337PJ_DECL(void) pjsip_dlg_dec_lock( pjsip_dialog *dlg ); 
    … …  
    240343 * dialog instance in the rdata, or otherwise this function will return  
    241344 * NULL if the message didn't match any existing dialog. 
     345 * 
     346 * This function can only be called after endpoint distributes the message 
     347 * to the transaction layer or UA layer. In other words, application can 
     348 * only call this function in the context of module that runs in priority 
     349 * number higher than PJSIP_MOD_PRIORITY_UA_PROXY_LAYER. 
     350 * 
     351 * @param rdata             Incoming message buffer. 
     352 * 
     353 * @return                  The dialog instance that "owns" the message. 
    242354 */ 
    243355PJ_DECL(pjsip_dialog*) pjsip_rdata_get_dlg( pjsip_rx_data *rdata ); 
    244356 
    245357/** 
    246  * Get the associated dialog in a transaction. 
     358 * Get the associated dialog for the specified transaction, if any. 
     359 * 
     360 * @param tsx               The transaction. 
     361 * 
     362 * @return                  The dialog instance which has been registered 
     363 *                          to the transaction as transaction user, or 
     364 *                          NULL if the transaction is outside any dialogs. 
    247365 */ 
    248366PJ_DECL(pjsip_dialog*) pjsip_tsx_get_dlg( pjsip_transaction *tsx ); 
    … …  
    257375 * 
    258376 * This function will also put Contact header where appropriate. 
     377 * 
     378 * @param dlg               The dialog instance. 
     379 * @param method            The method of the request. 
     380 * @param cseq              Optional CSeq, which only needs to be specified 
     381 *                          when creating ACK and CANCEL. For other requests, 
     382 *                          specify -1 to use dialog's internal counter. 
     383 * @param tdata             Pointer to receive the request's transmit 
     384 *                          data buffer. 
     385 * 
     386 * @return                  PJ_SUCCESS on success. 
    259387 */ 
    260388PJ_DECL(pj_status_t) pjsip_dlg_create_request(  pjsip_dialog *dlg, 
    … …  
    278406 * This function will decrement the transmit data's reference counter 
    279407 * regardless the status of the operation. 
     408 * 
     409 * @param dlg               The dialog. 
     410 * @param tdata             The request message to be sent. 
     411 * @param p_tsx             Optional argument to receive the transaction  
     412 *                          instance used to send the request. 
     413 * 
     414 * @return                  PJ_SUCCESS on success. 
    280415 */ 
    281416PJ_DECL(pj_status_t) pjsip_dlg_send_request (   pjsip_dialog *dlg, 
    … …  
    290425 * function adds Contact header and Record-Routes headers in the response  
    291426 * where appropriate. 
     427 * 
     428 * @param dlg               The dialog. 
     429 * @param rdata             The incoming request message for which the 
     430 *                          response will be created. 
     431 * @param st_code           Status code. 
     432 * @param st_text           Optional string for custom status reason text. 
     433 * @param tdata             Pointer to receive the response message transmit 
     434 *                          data buffer. 
     435 * 
     436 * @return                  PJ_SUCCESS on success. 
    292437 */ 
    293438PJ_DECL(pj_status_t) pjsip_dlg_create_response( pjsip_dialog *dlg, 
    … …  
    301446 * Modify previously sent response with other status code. Contact header  
    302447 * will be added when appropriate. 
     448 * 
     449 * @param dlg               The dialog. 
     450 * @param tdata             The transmit data buffer containing response 
     451 *                          message to be modified. 
     452 * @param st_code           New status code to be set. 
     453 * @param st_text           Optional string for custom status reason text. 
     454 * 
     455 * @return                  PJ_SUCCESS on success. 
    303456 */ 
    304457PJ_DECL(pj_status_t) pjsip_dlg_modify_response( pjsip_dialog *dlg, 
    … …  
    314467 * This function decrements the transmit data's reference counter regardless 
    315468 * the status of the operation. 
     469 * 
     470 * @param dlg               The dialog. 
     471 * @param tsx               The UAS transaction associated with the incoming 
     472 *                          request. If the request is within a dialog, or 
     473 *                          a dialog has been created for the request that 
     474 *                          creates the dialog, application can get the 
     475 *                          transaction instance for the request by calling 
     476 *                          #pjsip_rdata_get_tsx(). 
     477 * @param tdata             Response message to be sent. 
     478 * 
     479 * @return                  PJ_SUCCESS on success. 
    316480 */ 
    317481PJ_DECL(pj_status_t) pjsip_dlg_send_response(   pjsip_dialog *dlg, 
    … …  
    341505                                        const pjsip_msg_body *body ); 
    342506 
     507 
     508/** 
     509 * @} 
     510 */ 
     511 
    343512/*  
    344513 * Internal (called by sip_ua_layer.c) 
    … …  
    357526 
    358527 
    359 /** 
    360  * @} 
    361  */ 
    362528 
    363529PJ_END_DECL 
Note: See TracChangeset for help on using the changeset viewer.