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.
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
@type handle() :: {:subscription, module(), String.t(), Caracola.Dialog.id(), id()}
Identifies a subscription: service, Call-ID, dialog id and subscription id.
@type id() :: String.t()
Identifies a subscription inside a dialog.
@type reason() :: :deactivated | :probation | :rejected | :timeout | :giveup | :noresource | :invariant | :forced | {:code, pos_integer()} | nil
The reason a subscription ended (RFC 6665).
@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.
@type status() :: :init | :pending | :active | {:terminated, reason()}
The status of a subscription.
@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
@spec dialog(handle()) :: Caracola.Dialog.handle()
Returns the handle of the dialog of a subscription.
Gets the current state of a subscription.
Returns the handle of a subscription.
@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.