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

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)
```

# `header`

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

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

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

---

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