Caracola.DialogInfo (Caracola v0.1.0-rc.1)

Copy Markdown View Source

Dialog state (RFC 4235): the dialog event package, with application/dialog-info+xml documents, used by the busy lamp fields of phones and by call pickup.

defmodule MyPBX do
  use Malla.Service,
    plugins: [Caracola.DialogInfo],
    sip: [listen: "sip:all:5060"]
end

The plugin is built on Caracola.Notifier: it accepts SUBSCRIBEs to the dialog event of any AOR (see sip_notifier_authorize/4 there), and notifies the watchers of an AOR whenever one of its dialogs changes, with the full state (a new version for each NOTIFY of a subscription).

The dialogs of an AOR are:

  • the INVITE dialogs of the service whose local URI (From for the dialogs it starts, To for the ones it receives) has that AOR, when :track is true (the default). This is the case of user agents and B2BUAs, whose dialogs go through early (a provisional response with a To tag), confirmed and terminated;
  • the ones set by the service with put/3, as a proxy that follows the calls of its users.

Terminated dialogs are notified once and forgotten.

Watchers read the NOTIFYs with decode/1.

Configuration

Under the :dialog_info key:

  • :track - follow the INVITE dialogs of the service (default true).

Summary

Types

A dialog. :id and :state are required when encoding; :event and :code are the reason of the terminated state (as "rejected" and 486).

A decoded dialog-info document.

A participant of a dialog: its identity (a URI), display name and target URI.

The state of a dialog in a dialog-info document (RFC 4235).

Functions

The content type of dialog-info documents.

Parses a dialog-info document.

The current dialogs of an AOR.

Builds a dialog-info document with the full state.

Sets the state of a dialog of an AOR (by its :id) and notifies the watchers, if it has changed. A terminated dialog is notified once and forgotten.

Types

dialog_info()

@type dialog_info() :: %{
  optional(:id) => String.t(),
  optional(:state) => state(),
  optional(:call_id) => String.t() | nil,
  optional(:local_tag) => String.t() | nil,
  optional(:remote_tag) => String.t() | nil,
  optional(:direction) => :initiator | :recipient | nil,
  optional(:event) => String.t() | nil,
  optional(:code) => pos_integer() | nil,
  optional(:local) => participant() | nil,
  optional(:remote) => participant() | nil
}

A dialog. :id and :state are required when encoding; :event and :code are the reason of the terminated state (as "rejected" and 486).

document()

@type document() :: %{
  entity: String.t() | nil,
  version: non_neg_integer() | nil,
  state: :full | :partial | nil,
  dialogs: [dialog_info()]
}

A decoded dialog-info document.

participant()

@type participant() :: %{
  optional(:identity) => String.t() | nil,
  optional(:display) => String.t() | nil,
  optional(:target) => String.t() | nil
}

A participant of a dialog: its identity (a URI), display name and target URI.

state()

@type state() :: :trying | :proceeding | :early | :confirmed | :terminated

The state of a dialog in a dialog-info document (RFC 4235).

Functions

content_type()

@spec content_type() :: String.t()

The content type of dialog-info documents.

decode(body)

@spec decode(binary()) :: {:ok, document()} | :error

Parses a dialog-info document.

dialogs(service, aor)

@spec dialogs(module(), Caracola.Notifier.aor()) :: [dialog_info()]

The current dialogs of an AOR.

encode(entity, version, dialogs)

@spec encode(String.t(), non_neg_integer(), [dialog_info()]) :: String.t()

Builds a dialog-info document with the full state.

iex> body = Caracola.DialogInfo.encode("sip:bob@example.com", 3, [%{id: "d1", state: :early, direction: :recipient}])
iex> {:ok, %{version: 3, state: :full, dialogs: [%{id: "d1", state: :early}]}} = Caracola.DialogInfo.decode(body)

put(service, aor, dialog)

@spec put(module(), Caracola.Notifier.aor(), dialog_info()) :: :ok

Sets the state of a dialog of an AOR (by its :id) and notifies the watchers, if it has changed. A terminated dialog is notified once and forgotten.