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

Copy Markdown View Source

The Join header (RFC 3911): a new INVITE joins an existing dialog, as in barge-in, call monitoring or ad hoc conferences.

defmodule MyUA do
  use Malla.Service,
    plugins: [Caracola.Join, Caracola.Refer],
    sip: [listen: "sip:all:5060"]
end

The plugin adds join to the Supported header. When a new INVITE with a Join header arrives, it looks for the joined dialog (in any call of the service), and rejects the INVITE:

  • with 481 if there is no such dialog, it is not an INVITE dialog, or it is an early dialog this UA did not start;
  • with 603 if the dialog has already been hung up;
  • with 400 if the header is invalid, or the INVITE has a Replaces header too.

Otherwise sip_invite/2 is called as usual, and joined/1 returns the handle of the joined dialog. Joining the sessions (mixing their media, or becoming a conference focus) is up to the application, which can also reject the INVITE (for example with 488 if it can not mix them). Unlike Replaces, the joined dialog goes on.

To join a dialog of another UA, send an INVITE with the header of header/1, or ask a third UA to do it with a REFER with the Refer-To of refer_to/2:

# A is talking to C (dialog_c), and asks B to join the call at C
{:ok, refer_to} = Caracola.Join.refer_to("sip:c@example.com", dialog_c)
Caracola.UAC.refer(dialog_b, refer_to: refer_to)

Summary

Functions

The value of a Join header for a dialog of this UA, to be sent to its remote party or to a third UA (the tags as seen by the remote party).

The handle of the dialog a received INVITE joins (nil if it has no valid Join header).

The Refer-To asking to join dialog at uri (its remote party).

Functions

header(dialog)

@spec header(Caracola.Dialog.handle()) :: {:ok, String.t()} | {:error, term()}

The value of a Join header for a dialog of this UA, to be sent to its remote party or to a third UA (the tags as seen by the remote party).

joined(req)

@spec joined(Caracola.Message.t()) :: Caracola.Dialog.handle() | nil

The handle of the dialog a received INVITE joins (nil if it has no valid Join header).

refer_to(uri, dialog)

@spec refer_to(String.t(), Caracola.Dialog.handle()) ::
  {:ok, String.t()} | {:error, term()}

The Refer-To asking to join dialog at uri (its remote party).