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.
Summary
Types
The description of a conference.
A decoded conference-info document.
A media stream of a user: :type as "audio", :status as "sendrecv".
The status of a participant of a conference.
A participant. :endpoint is the URI of its device (its :entity by
default), and :joining_method is "dialed-in", "dialed-out" or
"focus-owner".
Functions
The content type of conference-info documents.
Parses a conference-info document.
The description of a conference.
Builds a conference-info document with the full state.
Sets the description of a conference, and notifies the watchers if it has changed.
Adds or updates a user of a conference (by its :entity), and notifies
the watchers if it has changed.
Removes a user of a conference: it is notified once as disconnected,
and forgotten.
The users of a conference.
Types
@type description() :: %{ optional(:subject) => String.t() | nil, optional(:display) => String.t() | nil, optional(:max_users) => pos_integer() | nil, optional(:locked) => boolean() | nil }
The description of a conference.
@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.
@type media() :: %{ optional(:id) => String.t(), optional(:type) => String.t() | nil, optional(:status) => String.t() | nil }
A media stream of a user: :type as "audio", :status as "sendrecv".
@type status() ::
:pending
| :dialing_out
| :dialing_in
| :alerting
| :on_hold
| :connected
| :muted_via_focus
| :disconnecting
| :disconnected
The status of a participant of a conference.
@type user() :: %{ optional(:entity) => String.t(), optional(:display) => String.t() | nil, optional(:endpoint) => String.t() | nil, optional(:status) => status() | nil, optional(:joining_method) => String.t() | nil, optional(:media) => [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".
Functions
@spec content_type() :: String.t()
The content type of conference-info documents.
Parses a conference-info document.
@spec description(module(), Caracola.Notifier.aor()) :: description()
The description of a conference.
@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: []}]}
@spec put_description(module(), Caracola.Notifier.aor(), description()) :: :ok
Sets the description of a conference, and notifies the watchers if it has changed.
@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.
@spec remove_user(module(), Caracola.Notifier.aor(), String.t()) :: :ok
Removes a user of a conference: it is notified once as disconnected,
and forgotten.
@spec users(module(), Caracola.Notifier.aor()) :: [user()]
The users of a conference.