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

Copy Markdown View Source

Back-to-back user agent: bridges an incoming INVITE (the A leg) with a new outgoing one (the B leg), relaying the responses, the in-dialog requests and the hangups between both dialogs.

defmodule MyB2BUA do
  use Malla.Service,
    plugins: [Caracola.B2BUA],
    sip: [listen: "sip:all:5060"]

  defcb sip_invite(req, _call),
    do: Caracola.B2BUA.bridge(req, "sip:bob@10.0.0.2", copy_headers: ["p-asserted-identity"])
end

bridge/3 starts a process for the bridge and returns :noreply, a result for sip_invite/2: the B leg is sent from that process, and its provisional and final responses (with their SDP) are relayed to the A leg. Then:

  • BYEs are answered and sent to the other leg.
  • re-INVITEs, UPDATEs and INFOs are sent to the other leg, and its final response relayed back. A re-INVITE without SDP is answered with the last SDP sent to that leg.
  • A CANCEL of the A leg cancels the B leg.
  • When the INVITE usage of a leg ends for any other reason (a timeout, for example), the other leg is hung up.

As both legs are separate dialogs, the B leg has its own Call-ID, tags, Via, Contact and route set: nothing of the A leg reaches it (topology hiding), except the From address and the headers in :copy_headers. Both early offer (SDP in the INVITE) and delayed offer (SDP in the 2xx and the ACK) are supported. 3xx responses are relayed as 480.

Services implementing sip_bye, sip_reinvite, sip_update, sip_info, sip_ack, sip_cancel or sip_dialog_update must return :cont for the bridged calls, to let this plugin get them.

Callbacks

  • sip_b2bua_sdp(sdp, from, bridge) - changes each Caracola.SDP relayed from the leg from (:a or :b) to the other one, for example to put a media relay in the middle. Returns the SDP to send (by default, the same).
  • sip_b2bua_update(event, bridge) - the bridge has changed: :answered or {:stop, reason}, where reason is {:bye, leg}, {:rejected, code}, {:error, reason}, :cancelled, :hangup or {:dialog_stop, leg, reason}. The result is ignored.

Both are called in the process of the bridge, with a t/0.

Summary

Types

A leg of a bridge: :a is the caller, :b the callee.

t()

A bridge: the Call-IDs and dialogs of both legs (the dialogs are set once answered), its status (:calling or :answered) and the :meta given to bridge/3.

Functions

Bridges an INVITE received in sip_invite/2 with a new INVITE to uri, returning the result for sip_invite/2 (:noreply).

Gets the bridge of a call, by the Call-ID of any of its legs.

Ends the bridge of a call: cancels the B leg if not answered yet (the A leg gets a 487), or hangs up both legs.

Types

leg()

@type leg() :: :a | :b

A leg of a bridge: :a is the caller, :b the callee.

t()

@type t() :: %Caracola.B2BUA{
  a: Caracola.Dialog.handle() | nil,
  a_call_id: String.t(),
  b: Caracola.Dialog.handle() | nil,
  b_call_id: String.t(),
  meta: term(),
  service: module(),
  status: :calling | :answered
}

A bridge: the Call-IDs and dialogs of both legs (the dialogs are set once answered), its status (:calling or :answered) and the :meta given to bridge/3.

Functions

bridge(req, uri, opts \\ [])

@spec bridge(Caracola.Message.t(), String.t() | Caracola.URI.t(), list()) ::
  :noreply | {:reply, term()}

Bridges an INVITE received in sip_invite/2 with a new INVITE to uri, returning the result for sip_invite/2 (:noreply).

Options:

  • {:from, from} - From of the B leg (by default, the address of the From of the A leg).
  • {:copy_headers, names} - headers of the A leg to copy to the B leg.
  • {:meta, term} - kept in the bridge, for the callbacks.
  • Any other option is passed to Caracola.UAC.invite/3 (as :route, :password or header options).

get(service, call_id)

@spec get(module(), String.t()) :: {:ok, t()} | {:error, :not_found}

Gets the bridge of a call, by the Call-ID of any of its legs.

hangup(service, call_id)

@spec hangup(module(), String.t()) :: :ok | {:error, :not_found}

Ends the bridge of a call: cancels the B leg if not answered yet (the A leg gets a 487), or hangs up both legs.