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

Generation of responses from "sip replies". Port of NkSIP's `nksip_reply`
and `nksip_call_uas_make`.

A sip reply is a status code, `{code, opts}`, or one of these shortcuts:

| Reply | Code |
|---|---|
| `:ringing`, `:session_progress` | 180, 183 |
| `:rel_ringing`, `{:rel_ringing, body}` | 180, reliable (see `Caracola.Rel100`) |
| `:rel_session_progress`, `{:rel_session_progress, body}` | 183, reliable |
| `:ok`, `{:ok, opts}`, `{:answer, body}` | 200 |
| `:accepted` | 202 |
| `{:redirect, contacts}` | 300 |
| `{:redirect_permanent, contact}`, `{:redirect_temporary, contact}` | 301, 302 |
| `:invalid_request`, `{:invalid_request, phrase}` | 400 |
| `:forbidden`, `{:forbidden, phrase}` | 403 |
| `:not_found`, `{:not_found, phrase}` | 404 |
| `{:method_not_allowed, allow}` | 405 |
| `:timeout`, `{:timeout, phrase}` | 408 |
| `:conditional_request_failed` | 412 |
| `:request_too_large` | 413 |
| `{:unsupported_media_type, accept}`, `{:unsupported_media_encoding, enc}` | 415 |
| `:unsupported_uri_scheme` | 416 |
| `{:bad_extension, unsupported}` | 420 |
| `{:extension_required, require}` | 421 |
| `{:session_too_small, min_se}` | 422 |
| `{:interval_too_brief, min_expires}` | 423 |
| `:flow_failed` | 430 |
| `:first_hop_lacks_outbound` | 439 |
| `:temporarily_unavailable` | 480 |
| `:unknown_dialog`, `:no_transaction` | 481 |
| `:loop_detected` | 482 |
| `:too_many_hops` | 483 |
| `:ambiguous` | 485 |
| `:busy` | 486 |
| `:request_terminated` | 487 |
| `{:not_acceptable, warning}` | 488 |
| `:bad_event` | 489 |
| `:request_pending` | 491 |
| `:internal_error`, `{:internal_error, phrase}` | 500 |
| `:service_unavailable`, `{:service_unavailable, phrase}` | 503 |
| `:busy_everywhere` | 600 |
| `:decline` | 603 |

In `sip_authorize/3`, `:authenticate` and `:proxy_authenticate` (or
`{:authenticate, realm}` and `{:proxy_authenticate, realm}`) reply with
a 401 or 407 digest challenge.

Response options:

  * `{:add | :replace | :insert, name, value}` - header manipulation, see
    `Caracola.Message.update_header/4`.
  * `{name, value}` for `:from`, `:to`, `:contact`, `:route`,
    `:content_type`, `:require`, `:supported`, `:expires`, `:event` and
    `:reason` - replace the header.
  * `{:body, body}` and `{:reason_phrase, phrase}`.
  * `{:to_tag, tag}` - use this To tag.
  * `:contact` - add a Contact with the address of the transport used.
  * `:allow`, `:supported`, `:accept`, `:allow_event`, `:date`,
    `:user_agent`, `:timestamp` - add the corresponding header, from the
    service configuration or the request.

# `sipreply`

```elixir
@type sipreply() ::
  non_neg_integer()
  | {non_neg_integer(), keyword() | list()}
  | atom()
  | {atom(), term()}
```

A reply for a request: a status code, `{code, opts}` or a named reply as `:ok` or `:busy`.

# `make`

```elixir
@spec make(Caracola.Message.t(), sipreply(), keyword()) ::
  {:ok, Caracola.Message.t(), list()} | {:error, term()}
```

Generates a response for `req`. Returns the response and the options to
use when sending it.

# `make!`

```elixir
@spec make!(Caracola.Message.t(), sipreply(), keyword()) ::
  {Caracola.Message.t(), list()}
```

Like `make/3`, but invalid replies or options generate a `500` response,
as NkSIP does for user replies.

# `parse`

```elixir
@spec parse(sipreply()) :: {:ok, 100..699, list()} | :error
```

Converts a sip reply into a code and options.

    iex> Caracola.Reply.parse(:busy)
    {:ok, 486, []}
    iex> Caracola.Reply.parse({:bad_extension, "a, b"})
    {:ok, 420, [{:replace, "unsupported", "a, b"}]}
    iex> Caracola.Reply.parse(:unknown)
    :error

---

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