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

Event subscriptions (RFC 6665). Equivalent to NkSIP's `nksip_subscription`.

Subscriptions are created by 2xx responses to SUBSCRIBE (or REFER)
requests, or by a NOTIFY arriving before that response, and live in a
`Caracola.Dialog`, which can have several of them (and an INVITE usage).
They are identified by a `t:handle/0`, returned in the `:subscription`
meta of the response to SUBSCRIBE (see `Caracola.UAC`).

`status` is `:init` (no NOTIFY yet), `:pending`, `:active` or
`{:terminated, reason}`; terminated subscriptions are removed. Changes are
notified with `sip_dialog_update({:subscription_status, status, subscription}, dialog, call)`,
where `status` can also be `:middle_timer` (half of the expiration time,
to refresh it), or `{:terminated, reason, retry_after}`.

In-dialog SUBSCRIBE and NOTIFY requests for a subscription are sent
passing its handle to `Caracola.UAC.subscribe/3` and
`Caracola.UAC.notify/3`, which add the Event and, for NOTIFY, the
Subscription-State headers (`{:subscription_state, state}` option,
`:active` by default, with the remaining expiration time).

# `handle`

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

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

# `id`

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

Identifies a subscription inside a dialog.

# `reason`

```elixir
@type reason() ::
  :deactivated
  | :probation
  | :rejected
  | :timeout
  | :giveup
  | :noresource
  | :invariant
  | :forced
  | {:code, pos_integer()}
  | nil
```

The reason a subscription ended (RFC 6665).

# `state`

```elixir
@type state() ::
  :active
  | :pending
  | {:active | :pending, non_neg_integer() | nil}
  | {:terminated, reason()}
  | {:terminated, reason(), non_neg_integer() | nil}
```

The state of a Subscription-State header.

# `status`

```elixir
@type status() :: :init | :pending | :active | {:terminated, reason()}
```

The status of a subscription.

# `t`

```elixir
@type t() :: %Caracola.Subscription{
  answered: integer() | nil,
  call_id: String.t(),
  class: :uac | :uas,
  dialog_id: Caracola.Dialog.id(),
  event: Caracola.Tokens.token(),
  expires: non_neg_integer() | nil,
  id: id(),
  service: module(),
  status: status(),
  timer_expire: {atom(), reference()} | nil,
  timer_middle: {atom(), reference()} | nil,
  timer_n: {atom(), reference()} | nil
}
```

A subscription: its event, expiration, status and the dialog it belongs to.

# `dialog`

```elixir
@spec dialog(handle()) :: Caracola.Dialog.handle()
```

Returns the handle of the dialog of a subscription.

# `get`

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

Gets the current state of a subscription.

# `handle`

```elixir
@spec handle(t()) :: handle()
```

Returns the handle of a subscription.

# `handle_of`

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

Returns the handle of the subscription a SUBSCRIBE, NOTIFY or REFER (or
one of their responses) belongs to, as the ones received in callbacks.
For a new SUBSCRIBE, the subscription exists once it is answered with a
2xx.

---

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