# &develguide;

## Available Functions

### `register_dlgcb (dialog, type, cb, param, free_param_cb)`

Register a new callback to the dialog.

Meaning of the parameters is as follows:

- struct dlg_cell* dlg - dialog to register callback to. It may be NULL only for DLGCB_CREATED callback type, which is not a per dialog type.

- int type - types of callbacks; more types may be registered for the same callback function; only DLGCB_CREATED must be registered alone. Possible types:

  - DLGCB_LOADED

  - DLGCB_CREATED - called when a new dialog is created - it's a global type (not associated to any dialog)

  - DLGCB_FAILED - called when the dialog was negatively replied (non-2xx) - it's a per dialog type.

  - DLGCB_CONFIRMED_NA - called when the dialog is confirmed (2xx replied) but the setup-concluding ACK message from the caller is yet pending - it's a per dialog type.

  - DLGCB_CONFIRMED - called when the dialog is confirmed (2xx replied) and the setup-concluding ACK message from the caller has been seen - it's a per dialog type.

  - DLGCB_REQ_WITHIN - called when the dialog matches a sequential request (excluding setup-concluding ACK messages which are handled in DLGCB_CONFIRMED) - it's a per dialog type.

  - DLGCB_TERMINATED - called when the dialog is terminated via BYE - it's a per dialog type.

  - DLGCB_TERMINATED_CONFIRMED - called when response to a BYE request is received - it's a per dialog type.

  - DLGCB_EXPIRED - called when the dialog expires without receiving a BYE - it's a per dialog type.

  - DLGCB_EARLY - called when the dialog is created in an early state (18x replied) - it's a per dialog type.

  - DLGCB_RESPONSE_FWDED - called when the dialog matches a reply to the initial INVITE request - it's a per dialog type.

  - DLGCB_RESPONSE_WITHIN - called when the dialog matches a reply to a subsequent in dialog request - it's a per dialog type.

  - DLGCB_MI_CONTEXT - called when the mi dlg_list_ctx command is invoked - it's a per dialog type.

  - DLGCB_SPIRALED - called when the dialog matches a spiraling request - it's a per dialog type.

  - DLGCB_DESTROY

- dialog_cb cb - callback function to be called. Prototype is: void (dialog_cb) (struct dlg_cell* dlg, int type, struct dlg_cb_params * params);

- void *param - parameter to be passed to the callback function.

- param_free callback_param_free - callback function to be called to free the param. Prototype is: void (param_free_cb) (void *param);

### `terminate_dlg (str callid, str ftag, str ttag, hdrs)`

Terminate a Dialog identified by callid, ftag and ttag in early or confirmed state.

Meaning of parameters is as follows:

- str* callid - callid of dialog to terminate.

- str* ftag - from_tag of dialog to terminate.

- str* ttag - to tag of dialog to terminate.

- str* hdrs - string containing extra headers (full format) to be added to the BYE requests of the dialog.

### `lookup_terminate_dlg (unsigned int h_entry, unsigned int h_id, hdrs)`

Terminate a Dialog identified by h_entry and h_id (similar to dlg_end_dlg command via XMLRPC).

Meaning of parameters is as follows:

- unsigned int h_entry - Number of the table, where to find the dialog

- unsigned int h_id - Number of the entry in the table, where to find the dialog terminate.

- str* hdrs - string containing extra headers (full format) to be added to the BYE requests of the dialog.

### `set_dlg_var (dlg, key, val)`

Add a variable to the dialog structure

Meaning of parameters is as follows:

- struct dlg_cell* dlg - dialog to add to.

- str* key - Name of the variable.

- str* val - Value of the variable.

### `get_dlg_var (dlg, key)`

Retrieves a variable attached to the dialog structure

Meaning of parameters is as follows:

- struct dlg_cell* dlg - dialog to get the variable from.

- str* key - Name of the variable.

### `get_current_dialog ()`

Get the current dialog for a message, if exists