sip_dialog.h

一个开源SIP协议栈

 *
 * @return		    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjsip_dlg_set_route_set( pjsip_dialog *dlg,
					      const pjsip_route_hdr *route_set );

/**
 * 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);


/**
 * Decrement the number of sessions in the dialog. Once the session counter 
 * 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,
					  void *mod_data );

/**
 * 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,
					     void *data );

/**
 * 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);


/**
 * 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 );

/**
 * Try to acquire dialog's lock, but return immediately if lock can not
 * be acquired.
 *
 * @param dlg		    The dialog.
 *
 * @return		    PJ_SUCCESS if lock has been acquired.
 */
PJ_DECL(pj_status_t) pjsip_dlg_try_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 );


/**
 * Get the dialog instance in the incoming rdata. If an incoming message 
 * 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 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 );


/**
 * Create a basic/generic request with the specified method and optionally
 * specify the cseq. Use value -1 for cseq to have the dialog automatically
 * put next cseq number for the request. Otherwise for some requests, 
 * e.q. CANCEL and ACK, application must put the CSeq in the original 
 * 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,
						int cseq,
						pjsip_tx_data **tdata);


/**
 * Send request message to remote peer. If the request is not an ACK request, 
 * the dialog will send the request statefully, by creating an UAC transaction
 * and send the request with the transaction. 
 *
 * Also when the request is not ACK or CANCEL, the dialog will increment its
 * local cseq number and update the cseq in the request according to dialog's 
 * cseq.
 *
 * If p_tsx is not null, this argument will be set with the transaction 
 * instance that was used to send the request.
 *
 * 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 mod_data_id	    Optional module data index to put an optional data
 *			    into the transaction. If no module data is to be
 *			    attached, this value should be -1.
 * @param mod_data	    Optional module data to be attached to the 
 *			    transaction at mod_data_id index.
 *
 * @return		    PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjsip_dlg_send_request (	pjsip_dialog *dlg,
						pjsip_tx_data *tdata,
						int mod_data_id,
						void *mod_data);


/**
 * Create a response message for the incoming request in rdata with status
 * code st_code and optional status text st_text. This function is different
 * 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,
						int st_code,
						const pj_str_t *st_text,
						pjsip_tx_data **tdata);


/**
 * 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,
						int st_code,
						const pj_str_t *st_text);


/**
 * Send response message statefully. The transaction instance MUST be the 
 * transaction that was reported on on_rx_request() callback.
 *
 * 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,
						pjsip_tx_data *tdata);


/**
 * This composite function sends response message statefully to an incoming
 * request message inside dialog.
 *
 * @param dlg	    The endpoint instance.
 * @param rdata	    The incoming request message.
 * @param st_code   Status code of the response.
 * @param st_text   Optional status text of the response.
 * @param hdr_list  Optional header list to be added to the response.
 * @param body	    Optional message body to be added to the response.
 *
 * @return	    PJ_SUCCESS if response message has successfully been
 *		    sent.
 */
PJ_DECL(pj_status_t) pjsip_dlg_respond( pjsip_dialog *dlg,
					pjsip_rx_data *rdata,
					int st_code,
					const pj_str_t *st_text,
					const pjsip_hdr *hdr_list,
					const pjsip_msg_body *body );


/**
 * @}
 */

/* 
 * Internal (called by sip_ua_layer.c)
 */

/* Receives transaction event (called by user_agent module) */
void pjsip_dlg_on_tsx_state( pjsip_dialog *dlg,
			     pjsip_transaction *tsx,
			     pjsip_event *e );

void pjsip_dlg_on_rx_request( pjsip_dialog *dlg,
			      pjsip_rx_data *rdata );

void pjsip_dlg_on_rx_response( pjsip_dialog *dlg,
			       pjsip_rx_data *rdata );



PJ_END_DECL


#endif	/* __PJSIP_SIP_DIALOG_H__ */