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

SIP dialogs (RFC 3261 §12). Equivalent to NkSIP's `nksip_dialog`.

Dialogs are created by 101-299 responses to INVITE requests, and by 2xx
responses to SUBSCRIBE, REFER and NOTIFY requests (see
`Caracola.Subscription`), and live in the process of their call. They
end when they have no INVITE usage and no subscriptions. They are identified by a `t:handle/0`, which
is returned in the `:dialog` meta of the response (see `Caracola.UAC`) and
can be obtained from any in-dialog message with `handle/1`. In-dialog
requests are sent passing the handle instead of the service to the
`Caracola.UAC` functions.

Dialog changes are notified to the service with the callbacks
`sip_dialog_update(event, dialog, call)` and
`sip_session_update(event, dialog, call)`, see `Caracola`.

# `handle`

```elixir
@type handle() :: {:dialog, module(), String.t(), id()}
```

Identifies a dialog: service, Call-ID and dialog id.

# `id`

```elixir
@type id() :: String.t()
```

Identifies a dialog inside a call.

# `t`

```elixir
@type t() :: %Caracola.Dialog{
  blocked_route_set: boolean(),
  call_id: String.t(),
  caller_tag: String.t(),
  created: integer(),
  early: boolean(),
  id: id(),
  invite: Caracola.Dialog.Invite.t() | nil,
  local_seq: non_neg_integer(),
  local_target: Caracola.URI.t() | nil,
  local_uri: Caracola.URI.t(),
  meta: map(),
  remote_seq: non_neg_integer(),
  remote_target: Caracola.URI.t() | nil,
  remote_uri: Caracola.URI.t(),
  route_set: [Caracola.URI.t()],
  secure: boolean(),
  service: module(),
  subscriptions: [Caracola.Subscription.t()],
  updated: integer()
}
```

A dialog: its id, local and remote URIs and tags, route set, CSeqs, the INVITE usage and its subscriptions.

# `authorized`

```elixir
@spec authorized(handle()) :: [{atom(), :inet.ip_address(), :inet.port_number()}]
```

Returns the origins (`{transport, ip, port}`) authorized in a dialog: the
sources of requests that were authorized, and of 2xx responses. Requests
from them get `:dialog` in the authorization list of `sip_authorize`.

# `clear_authorized`

```elixir
@spec clear_authorized(handle()) :: :ok
```

Removes the authorized origins of a dialog.

# `get`

```elixir
@spec get(handle()) :: {:ok, t()} | {:error, term()}
```

Gets the current state of a dialog.

# `handle`

```elixir
@spec handle(t() | Caracola.Message.t()) :: handle() | nil
```

Returns the handle of a dialog, or of the dialog a message belongs to
(`nil` if it does not belong to any).

# `list`

```elixir
@spec list(module(), String.t()) :: [handle()]
```

Returns the handles of the dialogs of a call.

# `stop`

```elixir
@spec stop(handle()) :: :ok | {:error, term()}
```

Removes a dialog without sending any request (use `Caracola.UAC.bye/2` to
hang up).

---

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