Notifier of event packages (RFC 6665 §4.2): accepts subscriptions to the
state of a resource and sends NOTIFYs with it, initially and whenever it
changes. It is the base of Caracola.Presence, Caracola.DialogInfo,
Caracola.MessageWaiting and Caracola.Conference, and of any other
event package with the state in a body.
A plugin built on it adds its events with add_events/2 in its
Malla.Plugin.plugin_config/2, and implements
sip_notifier_body(event, aor, version, service), returning the
current state as {content_type, body} (or :none for a NOTIFY without
body). For example, a message waiting package taking the summaries from
a voicemail system (Caracola.MessageWaiting keeps them itself):
defmodule MyMWI do
use Malla.Plugin, plugin_deps: [Caracola.Notifier]
@impl true
def plugin_config(_srv_id, config),
do: {:ok, Caracola.Notifier.add_events(config, ["message-summary"])}
defcb sip_notifier_body("message-summary", {_scheme, user, _domain}, _version, _service),
do: {"application/simple-message-summary", MyVoicemail.summary(user)}
defcb sip_notifier_body(_event, _aor, _version, _service), do: :cont
endThe resource of a SUBSCRIBE is the AOR ({scheme, user, domain}) of its
Request-URI. Before accepting it, the plugin calls
sip_notifier_authorize(event, aor, req, call), which returns :ok
(the default), :pending or a reply to reject it (as :forbidden).
Accepted subscriptions get a 200 and a NOTIFY with the current state, and another
one with each refresh; when the state of a resource changes, call
notify/3 to send it to all its watchers.
Pending subscriptions get NOTIFYs with Subscription-State: pending and
no state, until they are authorized with approve/1 or rejected with
terminate/2. watcher_info/3 returns the watchers of a resource and
their status, and Caracola.WatcherInfo sends them to the subscribers
of the .winfo packages (RFC 3857).
version starts at 0 and grows with each NOTIFY of a subscription (as
RFC 4235 requires). The NOTIFYs of a resource are sent in order by the
same process, so watchers get the states in the order they happened.
Summary
Types
A resource: the AOR of the Request-URI of the subscriptions.
A watcher of a resource: its subscription, status, the URI of the subscriber (its From) and when it subscribed (system time in seconds).
Functions
Adds event packages to the notifier, and to the :events of the sip
configuration. For plugins, in their Malla.Plugin.plugin_config/2.
The resource of a request: the AOR of its Request-URI.
Authorizes a pending subscription: its watcher gets a NOTIFY with the current state.
The items of the state of a resource, as {key, value}, ordered by key.
Sends the current state of a resource to all its watchers (in the background).
Stores an item of the state of a resource (nil removes it), for
plugins that keep the state in the notifier. Items are kept in memory,
in the node.
Ends a subscription, with a last NOTIFY with the reason (:rejected
by default, or :deactivated, :probation, :timeout, :giveup or
:noresource).
The URI of a resource, as "sip:alice@example.com".
The watchers of an event of a resource.
The subscriptions to an event of a resource.
Types
@type aor() :: {Caracola.URI.scheme(), String.t() | nil, String.t()}
A resource: the AOR of the Request-URI of the subscriptions.
@type watcher() :: %{ handle: Caracola.Subscription.handle(), status: :active | :pending | {:terminated, Caracola.Subscription.reason()}, uri: String.t(), since: integer() }
A watcher of a resource: its subscription, status, the URI of the subscriber (its From) and when it subscribed (system time in seconds).
Functions
Adds event packages to the notifier, and to the :events of the sip
configuration. For plugins, in their Malla.Plugin.plugin_config/2.
@spec aor(Caracola.Message.t()) :: aor()
The resource of a request: the AOR of its Request-URI.
@spec approve(Caracola.Subscription.handle()) :: :ok | {:error, :not_found}
Authorizes a pending subscription: its watcher gets a NOTIFY with the current state.
The items of the state of a resource, as {key, value}, ordered by key.
Sends the current state of a resource to all its watchers (in the background).
With {:then, fun}, fun (without arguments) is called once the NOTIFYs
have been queued, before any later state is read: for example, to forget
ended items that must appear in one notification.
Stores an item of the state of a resource (nil removes it), for
plugins that keep the state in the notifier. Items are kept in memory,
in the node.
@spec terminate(Caracola.Subscription.handle(), Caracola.Subscription.reason()) :: :ok | {:error, :not_found}
Ends a subscription, with a last NOTIFY with the reason (:rejected
by default, or :deactivated, :probation, :timeout, :giveup or
:noresource).
The URI of a resource, as "sip:alice@example.com".
iex> Caracola.Notifier.uri({:sip, "alice", "example.com"})
"sip:alice@example.com"
The watchers of an event of a resource.
@spec watchers(module(), String.t(), aor()) :: [Caracola.Subscription.handle()]
The subscriptions to an event of a resource.