# `Caracola.DialogInfo`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/dialog_info.ex#L1)

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`).

# `dialog_info`

```elixir
@type dialog_info() :: %{
  optional(:id) =&gt; String.t(),
  optional(:state) =&gt; state(),
  optional(:call_id) =&gt; String.t() | nil,
  optional(:local_tag) =&gt; String.t() | nil,
  optional(:remote_tag) =&gt; String.t() | nil,
  optional(:direction) =&gt; :initiator | :recipient | nil,
  optional(:event) =&gt; String.t() | nil,
  optional(:code) =&gt; pos_integer() | nil,
  optional(:local) =&gt; participant() | nil,
  optional(:remote) =&gt; 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`

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

A decoded dialog-info document.

# `participant`

```elixir
@type participant() :: %{
  optional(:identity) =&gt; String.t() | nil,
  optional(:display) =&gt; String.t() | nil,
  optional(:target) =&gt; String.t() | nil
}
```

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

# `state`

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

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

# `content_type`

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

The content type of dialog-info documents.

# `decode`

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

Parses a dialog-info document.

# `dialogs`

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

The current dialogs of an AOR.

# `encode`

```elixir
@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`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
