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)
endThe 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
closedtuple.
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
)
Summary
Types
A decoded PIDF document.
The basic status of a PIDF tuple.
A PIDF tuple: a way to contact the presentity (:id and :status are
required when encoding, the rest are optional).
Functions
The content type of PIDF documents.
Parses a PIDF document.
Builds a PIDF document. Options: :notes (a list of notes of the
presentity).
The composite presence state of a presentity, from its current publications (see the module documentation).
Types
@type document() :: %{ entity: String.t() | nil, tuples: [tuple_info()], notes: [String.t()] }
A decoded PIDF document.
@type status() :: :open | :closed
The basic status of a PIDF tuple.
@type tuple_info() :: %{ optional(:id) => String.t(), optional(:status) => status() | nil, optional(:contact) => String.t() | nil, optional(:priority) => String.t() | nil, optional(:note) => String.t() | nil, optional(:timestamp) => String.t() | nil }
A PIDF tuple: a way to contact the presentity (:id and :status are
required when encoding, the rest are optional).
Functions
@spec content_type() :: String.t()
The content type of PIDF documents.
Parses a PIDF document.
@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}]}}
@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).