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

Copy Markdown View Source

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
  )

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

document()

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

A decoded PIDF document.

status()

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

The basic status of a PIDF tuple.

tuple_info()

@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

content_type()

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

The content type of PIDF documents.

decode(body)

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

Parses a PIDF document.

encode(entity, tuples, opts \\ [])

@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(service, aor)

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