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

Presence (RFC 3856) with PIDF documents (RFC 3863): a presence server
that composes the state published by the user agents of each presentity
and notifies it to its watchers.

```
defmodule MyPresenceServer do
  use Malla.Service,
    plugins: [Caracola.Presence],
    sip: [listen: "sip:all:5060"]

  # Only users of the domain can watch
  defcb sip_notifier_authorize("presence", _aor, req, _call),
    do: if(req.from.domain == "example.com", do: :ok, else: :forbidden)
end
```

The plugin depends on `Caracola.EventCompositor`, which stores the
PUBLISH requests of the `presence` event, and on `Caracola.Notifier`,
which accepts the SUBSCRIBEs (see `sip_notifier_authorize/4` there) and
sends the NOTIFYs. Each change of the publications of a presentity (the
AOR of the Request-URI) is notified to all its watchers, with the
composite state:

  * with one publication, its document as it was published;
  * with several, a document with the tuples and notes of all of them
    (the latest publication wins when two tuples have the same id;
    elements of other namespaces, as RPID ones, are not kept);
  * with none, a document with a single `closed` tuple.

A service can build the state itself (from its registrar, for example)
implementing `sip_notifier_body("presence", aor, version, service)`.

User agents publish their state with a PIDF built by `encode/3`, and
watchers read the NOTIFYs with `decode/1`:

```
body = Caracola.Presence.encode("sip:alice@example.com", [%{id: "pc", status: :open, note: "Online"}])

{:ok, 200, meta} =
  Caracola.UAC.publish(MyUA, "sip:alice@example.com",
    event: "presence",
    content_type: Caracola.Presence.content_type(),
    body: body,
    expires: 3600
  )
```

# `document`

```elixir
@type document() :: %{
  entity: String.t() | nil,
  tuples: [tuple_info()],
  notes: [String.t()]
}
```

A decoded PIDF document.

# `status`

```elixir
@type status() :: :open | :closed
```

The basic status of a PIDF tuple.

# `tuple_info`

```elixir
@type tuple_info() :: %{
  optional(:id) =&gt; String.t(),
  optional(:status) =&gt; status() | nil,
  optional(:contact) =&gt; String.t() | nil,
  optional(:priority) =&gt; String.t() | nil,
  optional(:note) =&gt; String.t() | nil,
  optional(:timestamp) =&gt; String.t() | nil
}
```

A PIDF tuple: a way to contact the presentity (`:id` and `:status` are
required when encoding, the rest are optional).

# `content_type`

```elixir
@spec content_type() :: String.t()
```

The content type of PIDF documents.

# `decode`

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

Parses a PIDF document.

# `encode`

```elixir
@spec encode(String.t(), [tuple_info()], keyword()) :: String.t()
```

Builds a PIDF document. Options: `:notes` (a list of notes of the
presentity).

    iex> Caracola.Presence.encode("sip:alice@example.com", [%{id: "a1", status: :open}])
    ...> |> Caracola.Presence.decode()
    {:ok, %{entity: "sip:alice@example.com", notes: [], tuples: [%{id: "a1", status: :open, contact: nil, priority: nil, note: nil, timestamp: nil}]}}

# `state`

```elixir
@spec state(module(), Caracola.Notifier.aor()) :: {String.t(), String.t()}
```

The composite presence state of a presentity, from its current
publications (see the module documentation).

---

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