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

Copy Markdown View Source

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
end

The 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

document()

@type document() :: %{
  version: non_neg_integer() | nil,
  state: :full | :partial | nil,
  lists: [list_info()]
}

A watcherinfo document.

list_info()

@type list_info() :: %{
  resource: String.t(),
  package: String.t(),
  watchers: [watcher()]
}

A list of watchers of a resource and package.

watcher()

@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

decode(body)

@spec decode(binary()) :: {:ok, document()} | :error

Parses a watcherinfo document.

encode(resource, package, version, watchers)

Encodes a watcherinfo document with the watchers of a resource (as returned by Caracola.Notifier.watcher_info/3).