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

Copy Markdown View Source

The Replaces header (RFC 3891): a new INVITE replaces an existing dialog, as in attended transfers and call pickup.

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

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

  • with 481 if there is no such dialog, or it is an early dialog this UA did not start;
  • with 486 if it has early-only and the dialog is confirmed;
  • with 603 if the dialog has already been hung up;
  • with 400 if the header is invalid.

Otherwise sip_invite/2 is called as usual (replaced/1 returns the handle of the replaced dialog), and once the new dialog is confirmed (its ACK is received), the replaced one is ended: with a BYE if it was confirmed, or a CANCEL if it was an early dialog this UA started.

To replace a dialog of another UA, send an INVITE with the header of header/1, or, for an attended transfer, a REFER with the Refer-To of refer_to/2:

# A is talking to B (dialog_b) and to C (dialog_c), and transfers B to C
{:ok, refer_to} = Caracola.Replaces.refer_to("sip:c@example.com", dialog_c)
Caracola.UAC.refer(dialog_b, refer_to: refer_to)

Summary

Functions

The value of a Replaces 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 Refer-To of an attended transfer: uri (the remote party of dialog) with a Replaces header for dialog.

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

Functions

header(dialog)

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

The value of a Replaces 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).

refer_to(uri, dialog)

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

The Refer-To of an attended transfer: uri (the remote party of dialog) with a Replaces header for dialog.

replaced(req)

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

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