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

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

# `class`

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

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

# `counts`

```elixir
@type counts() :: %{
  optional(:new) =&gt; non_neg_integer(),
  optional(:old) =&gt; non_neg_integer(),
  optional(:urgent_new) =&gt; non_neg_integer(),
  optional(:urgent_old) =&gt; non_neg_integer()
}
```

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

# `document`

```elixir
@type document() :: %{
  waiting: boolean(),
  account: String.t() | nil,
  messages: %{optional(class()) =&gt; counts()}
}
```

A decoded message summary.

# `summary`

```elixir
@type summary() :: %{
  optional(:account) =&gt; String.t() | nil,
  optional(class()) =&gt; counts()
}
```

A message summary, as given to `put/3`.

# `content_type`

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

The content type of message summaries.

# `decode`

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

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

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

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

# `put`

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

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

---

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