# `Caracola.WatcherInfo`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/watcher_info.ex#L1)

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"]`).

# `document`

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

A watcherinfo document.

# `list_info`

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

A list of watchers of a resource and package.

# `watcher`

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

# `decode`

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

Parses a watcherinfo document.

# `encode`

```elixir
@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`).

---

*Consult [api-reference.md](api-reference.md) for complete listing*
