Dialogs API

This document describes the API NkSIP makes available to extract information from Dialogs.

Most functions in the API allows two ways to refer to the dialogs:

• From a full dialog object (nksip:dialog()). In some specific callback functions like sip_dialog_update/3 you receive a full dialog object. You can use these API functions inside the function call.

  You can also get a full dialog object calling get_dialog/2 using a request or subscription object and a call object (received in callback functions like sip_invite/2, sip_options/2, etc.

• From a dialog handle (nksip:handle()). You can get a dialog handle from a dialog object, request or response objects or handles for dialogs, request, responses or subscriptions, calling get_handle/1. You can then use the handle to call most functions in this API.

  In this case, the API function must contact with the corresponding call process to get the actual dialog, so you cannot use this method inside the same call process (like in the callback functions). This method is useful to refer to the dialog from a spawned process, avoiding the need to copy the full object. Please notice that the dialog object may not exists any longer at the moment that the handle is used. Most functions return error in this case.

Function	Description
get_handle/1	Grabs a dialog's handle
srv_id/1	Gets then Service's internal name
srv_name/1	Gets the Service's user name
call_id/1	Gets the Call-ID header of the dialog
meta/2	Gets specific metadata from the dialog
metas/2	Gets specific metadata from the dialog
get_dialog/2	Gets a dialog object from a request and a call objects
get_all/0	Get the handles of all started dialogs
get_all/2	Gets all current started dialog handles belonging to App and having Call-ID
bye_all/0	Sends an in-dialog BYE to all existing dialogs
stop/1	Stops an existing dialog from its handle (remove it from memory)
stop_all/0	Stops (removes from memory) all current dialogs
get_authorized_list/0	Gets the authorized list of transport, ip and ports for a dialog.
clear_authorized_list/0	Clear the authorized list of transport, ip and ports for a dialog.

Functions List

get_handle/1

nksip_dialog:get_handle(nksip:dialog()|nksip:request()|nksip:response()|nksip:handle()) ->
    {ok, nksip:handle()} | {error, term()}.

Grabs a dialog's handle.

srv_id/1

nksip_dialog:srv_id(nksip:dialog()|nksip:handle()) -> 
    {ok, nksip:srv_id()}.

Gets then Service's internal name.

srv_name/1

nksip_dialog:srv_name(nksip:dialog()|nksip:handle()) -> 
    {ok, nksip:srv_name()}.

Gets the Service's user name

call_id/1

nksip_dialog:call_id(nksip:dialog()|nksip:handle()) ->
    {ok, nksip:call_id()}.

Gets the Call-ID header of the dialog.

meta/2

nksip_dialog:meta(nksip_dialog:field(), nksip:dialog()|nksip:handle()) -> 
    {ok, term()} | {error, term()}.

Gets specific metadata from the dialog.

See Metadata Fields for a description of available fields.

metas/2

nksip_dialog:meta([nksip_dialog:field()], nksip:dialog()|nksip:handle()) -> 
    {ok, [{field(), term()}]} | {error, term()}.

Gets specific metadata from the dialog.

See Metadata Fields for a description of available fields.

get_dialog/2

nksip_dialog:get_dialog(nksip:request()|nksip:response()|nksip:subscription(), nksip:call()) ->
    {ok, nksip:dialog()} | {error, term()}.

Gets a dialog object from a request, response or subscription object and a call object.

get_all/0

nksip_dialog:get_all() ->
    [nksip:handle()].

Get the handles of all started dialogs.

get_all/2

nksip_dialog:get_all(App::nksip:srv_id(), CallId::nksip:call_id()) ->
    [nksip:handle()].

Gets all current started dialog handles belonging to a Service and having a specific Call-ID.

bye_all/0

nksip_dialog:bye_all() ->
    ok.

Sends an in-dialog BYE to all existing dialogs.

stop/1

nksip_dialog:stop(nksip:handle()) ->
    ok | {error, term()}.

Destroys an existing dialog from its handle (remove it from memory).

stop_all/0

nksip_dialog:stop_all() ->
    ok.

Destroys all current dialogs.

get_authorized_list/1

get_authorized_list(nksip:handle()) ->
    [{nksip:protocol(), inet:ip_address(), inet:port_number()}].

Gets the authorized list of transport, ip and ports for a dialog.

clear_authorized_list/1

clear_authorized_list(nksip:handle()) ->
    ok | {error, term()}.

Clears the authorized list of transport, ip and ports for a dialog.