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

Copy Markdown View Source

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

description()

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

document()

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

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

status()

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

@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

content_type()

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

The content type of conference-info documents.

decode(body)

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

Parses a conference-info document.

description(service, aor)

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

The description of a conference.

encode(entity, version, description, users)

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

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

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

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

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

The users of a conference.