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

Copy Markdown View Source

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

Summary

Types

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

Identifies a subscription inside a dialog.

The reason a subscription ended (RFC 6665).

The state of a Subscription-State header.

The status of a subscription.

t()

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

Functions

Returns the handle of the dialog of a subscription.

Gets the current state of a subscription.

Returns the handle of a subscription.

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.

Types

handle()

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

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

id()

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

Identifies a subscription inside a dialog.

reason()

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

The reason a subscription ended (RFC 6665).

state()

@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()

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

The status of a subscription.

t()

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

Functions

dialog(arg)

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

Returns the handle of the dialog of a subscription.

get(handle)

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

Gets the current state of a subscription.

handle(subs)

@spec handle(t()) :: handle()

Returns the handle of a subscription.

handle_of(msg)

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