# `Caracola.B2BUA`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/b2bua.ex#L1)

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:t/0`.

# `leg`

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

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

# `t`

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

# `bridge`

```elixir
@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`

```elixir
@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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
