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

Conference state (RFC 4575): the `conference` event package, with
`application/conference-info+xml` documents, with the description and
the participants of a conference.

```
defmodule MyFocus do
  use Malla.Service,
    plugins: [Caracola.Conference, Caracola.Join],
    sip: [listen: "sip:all:5060"]
end

conf = {:sip, "room1", "example.com"}
Caracola.Conference.put_description(MyFocus, conf, %{subject: "Weekly"})

Caracola.Conference.put_user(MyFocus, conf, %{
  entity: "sip:alice@example.com",
  display: "Alice",
  status: :connected,
  media: [%{id: "1", type: "audio", status: "sendrecv"}]
})
```

The plugin is built on `Caracola.Notifier`: it accepts SUBSCRIBEs to the
`conference` event of any AOR (see `sip_notifier_authorize/4` there),
and notifies the watchers of a conference with its full state whenever
the service changes it. Running the conference (the focus and the
mixer) is up to the application.

Users are identified by their `:entity` (a URI). `remove_user/3`
notifies a user as `disconnected` once, and forgets it. The user count
of the conference state is the number of users that are not
disconnected.

Watchers read the NOTIFYs with `decode/1`.

# `description`

```elixir
@type description() :: %{
  optional(:subject) =&gt; String.t() | nil,
  optional(:display) =&gt; String.t() | nil,
  optional(:max_users) =&gt; pos_integer() | nil,
  optional(:locked) =&gt; boolean() | nil
}
```

The description of a conference.

# `document`

```elixir
@type document() :: %{
  entity: String.t() | nil,
  version: non_neg_integer() | nil,
  state: :full | :partial | :deleted | nil,
  description: description(),
  user_count: non_neg_integer() | nil,
  active: boolean() | nil,
  locked: boolean() | nil,
  users: [user()]
}
```

A decoded conference-info document.

# `media`

```elixir
@type media() :: %{
  optional(:id) =&gt; String.t(),
  optional(:type) =&gt; String.t() | nil,
  optional(:status) =&gt; String.t() | nil
}
```

A media stream of a user: `:type` as `"audio"`, `:status` as `"sendrecv"`.

# `status`

```elixir
@type status() ::
  :pending
  | :dialing_out
  | :dialing_in
  | :alerting
  | :on_hold
  | :connected
  | :muted_via_focus
  | :disconnecting
  | :disconnected
```

The status of a participant of a conference.

# `user`

```elixir
@type user() :: %{
  optional(:entity) =&gt; String.t(),
  optional(:display) =&gt; String.t() | nil,
  optional(:endpoint) =&gt; String.t() | nil,
  optional(:status) =&gt; status() | nil,
  optional(:joining_method) =&gt; String.t() | nil,
  optional(:media) =&gt; [media()]
}
```

A participant. `:endpoint` is the URI of its device (its `:entity` by
default), and `:joining_method` is `"dialed-in"`, `"dialed-out"` or
`"focus-owner"`.

# `content_type`

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

The content type of conference-info documents.

# `decode`

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

Parses a conference-info document.

# `description`

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

The description of a conference.

# `encode`

```elixir
@spec encode(String.t(), non_neg_integer(), description(), [user()]) :: String.t()
```

Builds a conference-info document with the full state.

    iex> body = Caracola.Conference.encode("sip:room@example.com", 1, %{subject: "Hi"}, [%{entity: "sip:a@example.com", status: :connected}])
    iex> {:ok, doc} = Caracola.Conference.decode(body)
    iex> {doc.version, doc.description.subject, doc.user_count, doc.users}
    {1, "Hi", 1, [%{entity: "sip:a@example.com", display: nil, endpoint: "sip:a@example.com", status: :connected, joining_method: nil, media: []}]}

# `put_description`

```elixir
@spec put_description(module(), Caracola.Notifier.aor(), description()) :: :ok
```

Sets the description of a conference, and notifies the watchers if it
has changed.

# `put_user`

```elixir
@spec put_user(module(), Caracola.Notifier.aor(), user()) :: :ok
```

Adds or updates a user of a conference (by its `:entity`), and notifies
the watchers if it has changed.

# `remove_user`

```elixir
@spec remove_user(module(), Caracola.Notifier.aor(), String.t()) :: :ok
```

Removes a user of a conference: it is notified once as `disconnected`,
and forgotten.

# `users`

```elixir
@spec users(module(), Caracola.Notifier.aor()) :: [user()]
```

The users of a conference.

---

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