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

Copy Markdown View Source

Message waiting indication (RFC 3842): the message-summary event package, with application/simple-message-summary bodies, that turns on the message lamp of phones.

defmodule MyVoicemail do
  use Malla.Service,
    plugins: [Caracola.MessageWaiting],
    sip: [listen: "sip:all:5060"]
end

Caracola.MessageWaiting.put(MyVoicemail, {:sip, "alice", "example.com"}, %{
  voice: %{new: 2, old: 8}
})

The plugin is built on Caracola.Notifier: it accepts SUBSCRIBEs to the message-summary event of any AOR (see sip_notifier_authorize/4 there), and notifies the watchers of an AOR when the service sets its summary with put/3. The mailboxes themselves are up to the application.

A summary has, for each message class (:voice, :fax, :pager, :multimedia, :text and :none), the number of :new and :old messages, and optionally of :urgent_new and :urgent_old ones, and an optional :account (the URI of the mailbox). Messages are waiting if there is any new one.

User agents read the NOTIFYs (or the unsolicited NOTIFYs of PBXs, see sip_unsolicited_notify/2) with decode/1.

Summary

Types

A message class of a message-summary (RFC 3842).

The counters of a message class: new, old, urgent new and urgent old.

A decoded message summary.

A message summary, as given to put/3.

Functions

The content type of message summaries.

Parses a message summary body. Message headers after the summary are ignored.

Builds a message summary body.

The message summary of an AOR (empty if it has not been set).

Sets the message summary of an AOR, and notifies the watchers if it has changed.

Types

class()

@type class() :: :voice | :fax | :pager | :multimedia | :text | :none

A message class of a message-summary (RFC 3842).

counts()

@type counts() :: %{
  optional(:new) => non_neg_integer(),
  optional(:old) => non_neg_integer(),
  optional(:urgent_new) => non_neg_integer(),
  optional(:urgent_old) => non_neg_integer()
}

The counters of a message class: new, old, urgent new and urgent old.

document()

@type document() :: %{
  waiting: boolean(),
  account: String.t() | nil,
  messages: %{optional(class()) => counts()}
}

A decoded message summary.

summary()

@type summary() :: %{
  optional(:account) => String.t() | nil,
  optional(class()) => counts()
}

A message summary, as given to put/3.

Functions

content_type()

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

The content type of message summaries.

decode(body)

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

Parses a message summary body. Message headers after the summary are ignored.

iex> Caracola.MessageWaiting.decode("Messages-Waiting: yes\r\nVoice-Message: 2/8 (0/1)\r\n")
{:ok, %{waiting: true, account: nil, messages: %{voice: %{new: 2, old: 8, urgent_new: 0, urgent_old: 1}}}}
iex> Caracola.MessageWaiting.decode("nothing")
:error

encode(summary)

@spec encode(summary()) :: String.t()

Builds a message summary body.

iex> Caracola.MessageWaiting.encode(%{account: "sip:alice@example.com", voice: %{new: 2, old: 8, urgent_old: 1}})
"Messages-Waiting: yes\r\nMessage-Account: sip:alice@example.com\r\nVoice-Message: 2/8 (0/1)\r\n"
iex> Caracola.MessageWaiting.encode(%{})
"Messages-Waiting: no\r\n"

get(service, aor)

@spec get(module(), Caracola.Notifier.aor()) :: summary()

The message summary of an AOR (empty if it has not been set).

put(service, aor, summary)

@spec put(module(), Caracola.Notifier.aor(), summary()) :: :ok

Sets the message summary of an AOR, and notifies the watchers if it has changed.