Group PJSIP_DIALOG¶

group PJSIP_DIALOG

The base dialog framework to support dialog usages.

The base dialog framework provides management for base dialog properties such as From header, To header, CSeq sequencing, Call-ID header, Contact header management, dialog route-set management, and common authentication. This basic dialog functionality will be shared by all dialog usages of a particular dialog.

More detailed information is explained in PJSIP Developer’s Guide PDF document, and readers are encouraged to read the document to get the concept behind dialog, dialog usages, and INVITE sessions.

Application MUST initialize the user agent layer module by calling pjsip_ua_init_module() before using any of the dialog API, and link the application with with pjsip-core library.

Enums

enum pjsip_dialog_state¶

Dialog state.

Values:

enumerator PJSIP_DIALOG_STATE_NULL¶: Dialog is not established.

enumerator PJSIP_DIALOG_STATE_ESTABLISHED¶: Dialog has been established (probably early)

enum pjsip_dialog_cap_status¶

Dialog capability status.

Values:

enumerator PJSIP_DIALOG_CAP_UNSUPPORTED¶: Capability is unsupported.

enumerator PJSIP_DIALOG_CAP_SUPPORTED¶: Capability is supported

enumerator PJSIP_DIALOG_CAP_UNKNOWN¶: Unknown capability status. This is usually because we lack the capability info which is retrieved from capability header specified in the dialog messages.

Functions

pj_bool_t pjsip_method_creates_dialog(const pjsip_method *m)¶

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.

Parameters: m – The SIP method.
Returns: PJ_TRUE if the method creates a dialog.

pj_status_t pjsip_dlg_create_uac(pjsip_user_agent *ua, const pj_str_t *local_uri, const pj_str_t *local_contact, const pj_str_t *remote_uri, const pj_str_t *target, pjsip_dialog **p_dlg)¶

Create a new dialog and return the instance in p_dlg parameter. After creating the dialog, application can add modules as dialog usages by calling pjsip_dlg_add_usage().

If the request has To tag parameter, dialog’s local tag will be initialized from this value. Otherwise a globally unique id generator will be invoked to create dialog’s local tag.

This function also initializes the dialog’s route set based on the Record-Route headers in the request, if present.

Note that initially, the session count in the dialog will be initialized to zero.

Parameters

ua – The user agent module instance.
local_uri – Dialog local URI (i.e. From header).
local_contact – Optional dialog local Contact to be put as Contact header value, hence the format must follow RFC 3261 Section 20.10: When the header field value contains a display name, the URI including all URI parameters is enclosed in “<” and “>”. If no “<” and “>” are present, all parameters after the URI are header parameters, not URI parameters. The display name can be tokens, or a quoted string, if a larger character set is desired. If this argument is NULL, the Contact will be taken from the local URI.
remote_uri – Dialog remote URI (i.e. To header).
target – Optional initial remote target. If this argument is NULL, the initial target will be set to remote URI.
p_dlg – Pointer to receive the dialog.

Returns

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_create_uas(pjsip_user_agent *ua, pjsip_rx_data *rdata, const pj_str_t *contact, pjsip_dialog **p_dlg)¶

Initialize UAS dialog from the information found in the incoming request that creates a dialog (such as INVITE, REFER, or SUBSCRIBE), and set the local Contact to contact. If contact is not specified, the local contact is initialized from the URI in the To header in the request.

This function will also create UAS transaction for the incoming request, and associate the transaction to the rdata. Application can query the transaction used to handle this request by calling pjsip_rdata_get_tsx() after this function returns.

Note that initially, the session count in the dialog will be initialized to zero.

Parameters

ua – The user agent module instance.
rdata – The incoming request that creates the dialog, such as INVITE, SUBSCRIBE, or REFER.
contact – Optional dialog local Contact to be put as Contact header value, hence the format must follow RFC 3261 Section 20.10: When the header field value contains a display name, the URI including all URI parameters is enclosed in “<” and “>”. If no “<” and “>” are present, all parameters after the URI are header parameters, not URI parameters. The display name can be tokens, or a quoted string, if a larger character set is desired. If this argument is NULL, the local contact will be initialized from the value of To header in the request.
p_dlg – Pointer to receive the dialog.

Returns

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_set_transport(pjsip_dialog *dlg, const pjsip_tpselector *sel)¶

Lock/bind dialog to a specific transport/listener. This is optional, as normally transport will be selected automatically based on the destination of messages upon resolver completion. When the dialog is explicitly bound to the specific transport/listener, all 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.

Parameters

dlg – The dialog instance.
sel – Transport selector containing the specification of transport or listener to be used by this dialog to send requests.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsip_dlg_fork(const pjsip_dialog *original_dlg, const pjsip_rx_data *rdata, pjsip_dialog **new_dlg)¶

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, the new_dlg will have been registered to the user agent. Applications just need to add modules as dialog’s usages.

Note that initially, the session count in the dialog will be initialized to zero.

Parameters

original_dlg – The original UAC dialog.
rdata – The incoming forked response message.
new_dlg – Pointer to receive the new dialog.

Returns

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_terminate(pjsip_dialog *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).

Parameters: dlg – The dialog.
Returns: PJ_SUCCESS if dialog has been terminated.

pj_status_t pjsip_dlg_set_route_set(pjsip_dialog *dlg, const pjsip_route_hdr *route_set)¶

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 established, the route set can not be changed.

For UAS dialog,the route set will be initialized in pjsip_dlg_create_uas() from the Record-Route headers in the incoming request.

The route_set argument is standard list of Route headers (i.e. with sentinel).

Parameters

dlg – The UAC dialog.
route_set – List of Route header.

Returns

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_inc_session(pjsip_dialog *dlg, pjsip_module *mod)¶

Increment the number of sessions in the dialog. Note that initially (after created) the dialog has the session counter set to zero.

Parameters

dlg – The dialog.
mod – The module that increments the session counter.

Returns

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_dec_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.

Parameters

dlg – The dialog.
mod – The module that decrements the session counter.

Returns

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_add_usage(pjsip_dialog *dlg, pjsip_module *module, void *mod_data)¶

Add a module as dialog usage, and optionally set the module specific data.

Parameters

dlg – The dialog.
module – The module to be registered as dialog usage.
mod_data – Optional arbitrary data to be attached to dialog’s mod_data array at the module’s index.

Returns

PJ_SUCCESS on success.

pj_bool_t pjsip_dlg_has_usage(pjsip_dialog *dlg, pjsip_module *module)¶

Check if the specified module has been registered as usage to the dialog.

Parameters

dlg – The dialog.
module – The module.

Returns

PJ_TRUE if the specified module is currently registered as a usage to the dialog.

pj_status_t pjsip_dlg_set_mod_data(pjsip_dialog *dlg, int mod_id, void *data)¶

Attach module specific data to the dialog. Application can also set the value directly by accessing dlg->mod_data[module_id].

Parameters

dlg – The dialog
mod_id – The ID of the module from which the data is to be set to the dialog.
data – Arbitrary data.

Returns

PJ_SUCCESS on success.

void *pjsip_dlg_get_mod_data(pjsip_dialog *dlg, int mod_id)¶

Get module specific data previously attached to the dialog. Application can also get value directly by accessing dlg->mod_data[module_id].

Parameters

dlg – The dialog
mod_id – The ID of the module from which the data is to be retrieved from the dialog.

Returns

The data that was previously set, or NULL.

void pjsip_dlg_inc_lock(pjsip_dialog *dlg)¶

Lock dialog and increment session counter termporarily, to prevent it from being destroyed.

Parameters: dlg – The dialog.

pj_status_t pjsip_dlg_try_inc_lock(pjsip_dialog *dlg)¶

Try to acquire dialog’s lock, but return immediately if lock can not be acquired.

Parameters: dlg – The dialog.
Returns: PJ_SUCCESS if lock has been acquired.

void pjsip_dlg_dec_lock(pjsip_dialog *dlg)¶

Unlock dialog and decrement temporary session counter. After this function is called, dialog may be destroyed.

Parameters: dlg – The dialog.

pjsip_dialog *pjsip_rdata_get_dlg(pjsip_rx_data *rdata)¶

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.

Parameters: rdata – Incoming message buffer.
Returns: The dialog instance that “owns” the message.

pjsip_dialog *pjsip_tsx_get_dlg(pjsip_transaction *tsx)¶

Get the associated dialog for the specified transaction, if any.

Parameters: tsx – The transaction.
Returns: The dialog instance which has been registered to the transaction as transaction user, or NULL if the transaction is outside any dialogs.

pj_status_t pjsip_dlg_create_request(pjsip_dialog *dlg, const pjsip_method *method, int cseq, pjsip_tx_data **tdata)¶

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.

Parameters

dlg – The dialog instance.
method – The method of the request.
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.
tdata – Pointer to receive the request’s transmit data buffer.

Returns

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_send_request(pjsip_dialog *dlg, pjsip_tx_data *tdata, int mod_data_id, void *mod_data)¶

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.

Parameters

dlg – The dialog.
tdata – The request message to be sent.
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.
mod_data – Optional module data to be attached to the transaction at mod_data_id index.

Returns

PJ_SUCCESS on success.

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)¶

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.

Parameters

dlg – The dialog.
rdata – The incoming request message for which the response will be created.
st_code – Status code.
st_text – Optional string for custom status reason text.
tdata – Pointer to receive the response message transmit data buffer.

Returns

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_modify_response(pjsip_dialog *dlg, pjsip_tx_data *tdata, int st_code, const pj_str_t *st_text)¶

Modify previously sent response with other status code. Contact header will be added when appropriate.

Parameters

dlg – The dialog.
tdata – The transmit data buffer containing response message to be modified.
st_code – New status code to be set.
st_text – Optional string for custom status reason text.

Returns

PJ_SUCCESS on success.

pj_status_t pjsip_dlg_send_response(pjsip_dialog *dlg, pjsip_transaction *tsx, pjsip_tx_data *tdata)¶

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.

Parameters

dlg – The dialog.
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().
tdata – Response message to be sent.

Returns

PJ_SUCCESS on success.

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)¶

This composite function sends response message statefully to an incoming request message inside dialog.

Parameters

dlg – The endpoint instance.
rdata – The incoming request message.
st_code – Status code of the response.
st_text – Optional status text of the response.
hdr_list – Optional header list to be added to the response.
body – Optional message body to be added to the response.

Returns

PJ_SUCCESS if response message has successfully been sent.

pjsip_dialog_cap_status pjsip_dlg_remote_has_cap(pjsip_dialog *dlg, int htype, const pj_str_t *hname, const pj_str_t *token)¶

Check if remote peer have the specified capability as published in the dialog messages from remote peer.

Notes:

The capability token lookup will apply exact match, but not case-sensitive, for example: "text/html" will not match "text / html" (notice the spaces).

Parameters

dlg – The dialog.
htype – The header type to be checked, which value may be:
- PJSIP_H_ACCEPT
- PJSIP_H_ALLOW
- PJSIP_H_SUPPORTED
hname – If htype specifies PJSIP_H_OTHER, then the header name must be supplied in this argument. Otherwise the value must be set to NULL.
token – The capability token to check. For example, if htype is PJSIP_H_ALLOW, then token specifies the method names; if htype is PJSIP_H_SUPPORTED, then token specifies the extension names such as “100rel”.

Returns

PJSIP_DIALOG_CAP_SUPPORTED if the specified capability is explicitly supported, see for more info.

const pjsip_hdr *pjsip_dlg_get_remote_cap_hdr(pjsip_dialog *dlg, int htype, const pj_str_t *hname)¶

Get the specified capability header from the remote capability headers stored in the dialog.

Parameters

dlg – The dialog.
htype – The header type to be retrieved, which value may be:
- PJSIP_H_ACCEPT
- PJSIP_H_ALLOW
- PJSIP_H_SUPPORTED
hname – If htype specifies PJSIP_H_OTHER, then the header name must be supplied in this argument. Otherwise the value must be set to NULL.

Returns

The appropriate header, or NULL if the header is not available.

pj_status_t pjsip_dlg_set_remote_cap_hdr(pjsip_dialog *dlg, const pjsip_generic_array_hdr *cap_hdr)¶

Set remote capability from a SIP header containing array of capability tags/values.

Parameters

dlg – The dialog.
cap_hdr – The SIP header.

Returns

PJ_SUCCESS when successful, otherwise the appropriate error code will be returned.

pj_status_t pjsip_dlg_remove_remote_cap_hdr(pjsip_dialog *dlg, int htype, const pj_str_t *hname)¶

Remove a remote capability header.

Parameters

dlg – The dialog.
htype – The header type to be removed, which value may be:
- PJSIP_H_ACCEPT
- PJSIP_H_ALLOW
- PJSIP_H_SUPPORTED
hname – If htype specifies PJSIP_H_OTHER, then the header name must be supplied in this argument. Otherwise the value must be set to NULL.

Returns

PJ_SUCCESS when successful, otherwise the appropriate error code will be returned.

pj_status_t pjsip_dlg_update_remote_cap(pjsip_dialog *dlg, const pjsip_msg *msg, pj_bool_t strict)¶

Update remote capabilities from a received message. The header types to be updated from the message will only be PJSIP_H_ACCEPT, PJSIP_H_ALLOW, and PJSIP_H_SUPPORTED.

Parameters

dlg – The dialog.
msg – The received message.
strict – If this is set to PJ_TRUE, any header types missing from the message will cause removal of existing header types in the capability list. Otherwise, the capability list will not be modified when any header type is missing.

Returns

PJ_SUCCESS when successful, otherwise the appropriate error code will be returned.

struct pjsip_dlg_party¶: #include <sip_dialog.h>
This structure is used to describe dialog’s participants, which in this case is local party (i.e. us) and remote party.

struct pjsip_dialog¶

#include <sip_dialog.h>

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.

Forward declaration for dialog (sip_dialog.h).