Watcher information (RFC 3857, RFC 3858): the .winfo template event
packages, with application/watcherinfo+xml bodies, that tell a
presentity who is subscribed to its state, so it can authorize the
pending watchers.
defmodule MyPresence do
use Malla.Service,
plugins: [Caracola.Presence, Caracola.WatcherInfo],
sip: [listen: "sip:all:5060"],
watcher_info: [events: ["presence"]]
# Unknown watchers wait until the presentity authorizes them
defcb sip_notifier_authorize("presence", aor, req, _call),
do: if(MyApp.allowed?(aor, req.from), do: :ok, else: :pending)
defcb sip_notifier_authorize(_event, _aor, _req, _call), do: :cont
endThe plugin is built on Caracola.Notifier: for each event of :events
it accepts SUBSCRIBEs to <event>.winfo (presence.winfo), and sends
to them the watchers of the resource (see
Caracola.Notifier.watcher_info/3) whenever they change. Only the
resource itself can subscribe (the AOR of the From must be the one of
the Request-URI); services can change it implementing
sip_notifier_authorize/4 for the .winfo events.
Pending watchers (those sip_notifier_authorize/4 answered with
:pending) are authorized with Caracola.Notifier.approve/1, or
rejected with Caracola.Notifier.terminate/2, by the application (for
example, from the authorization rules of the presentity). Rejected
watchers appear in one notification as terminated, and then are
removed. Only full state is sent.
Configuration
Under the :watcher_info key:
:events- the event packages with watcher information (default["presence"]).
Summary
Types
A watcherinfo document.
A list of watchers of a resource and package.
A watcher of a watcherinfo document: its id, status (:active,
:pending, :waiting or :terminated), the event that changed it
("subscribe", "approved", "rejected", "timeout"...), the URI and
the seconds it has been subscribed.
Functions
Parses a watcherinfo document.
Encodes a watcherinfo document with the watchers of a resource (as
returned by Caracola.Notifier.watcher_info/3).
Types
@type document() :: %{ version: non_neg_integer() | nil, state: :full | :partial | nil, lists: [list_info()] }
A watcherinfo document.
A list of watchers of a resource and package.
@type watcher() :: %{ id: String.t(), status: :active | :pending | :waiting | :terminated, event: String.t() | nil, uri: String.t(), duration: non_neg_integer() | nil }
A watcher of a watcherinfo document: its id, status (:active,
:pending, :waiting or :terminated), the event that changed it
("subscribe", "approved", "rejected", "timeout"...), the URI and
the seconds it has been subscribed.
Functions
Parses a watcherinfo document.
@spec encode(String.t(), String.t(), non_neg_integer(), [Caracola.Notifier.watcher()]) :: binary()
Encodes a watcherinfo document with the watchers of a resource (as
returned by Caracola.Notifier.watcher_info/3).