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

Sending requests. Equivalent to NkSIP's `nksip_uac`.

Requests are sent from a service (which must have listeners for the
transports used) to a URI. By default the call waits for the final
response and returns `{:ok, code, metas}`, or `{:error, reason}` if the
request could not be sent.

In-dialog requests are sent passing a `t:Caracola.Dialog.handle/0`
instead of the service and the URI: `bye(dialog)`,
`invite(dialog, body: sdp)`... Their From, To, Call-ID, CSeq, Route and
Contact come from the dialog. They fail with `{:error, :unknown_dialog}`
if the dialog does not exist, or `{:error, :request_pending}` if another
INVITE or offer is in progress.

Responses to INVITE (101-299) always include the dialog handle as the
first meta: `{:ok, 200, [dialog: dialog]}`, and 2xx responses to
SUBSCRIBE and REFER the subscription handle: `[subscription: subscription]`
(see `Caracola.Subscription`). The ACK for a 2xx response
must be sent with `ack/2`, unless the INVITE is sent with `:auto_2xx_ack`.

## Options

  * `{:add | :replace | :insert, name, value}` - header manipulation, see
    `Caracola.Message.update_header/4`; `{:remove, name}` removes a header
    (`Caracola.Message.remove_header/2`).
  * `{name, value}` for `:from`, `:to`, `:contact`, `:route`,
    `:content_type`, `:require`, `:supported`, `:expires`, `:event`,
    `:reason`, `:refer_to` and `:sip_if_match` - replace the header.
  * `{:body, body}` (a binary or a `Caracola.SDP`, which also sets the
    Content-Type), `{:call_id, call_id}` and `{:cseq_num, num}`.
  * `:contact` - add a Contact with the address of the transport used
    (added automatically for INVITE, SUBSCRIBE, NOTIFY, REFER and UPDATE).
  * `:unregister` (`[:contact, expires: 0]`) and `:unregister_all`
    (`[contact: "*", expires: 0]`), for REGISTER.
  * `{:password, password}` - answer 401 and 407 challenges (a password,
    an HA1 as `{:ha1, hex}` for MD5 or `{:ha1, algorithm, hex}`,
    `{realm, password}` or a list of them), sending the request again with
    the credentials. For each realm, the challenge with the strongest
    algorithm (SHA-512-256, SHA-256, MD5) that can be answered is used.
    The `:password` of the service configuration is also used.
  * `:allow`, `:supported`, `:accept`, `:allow_event`, `:date` and
    `:user_agent` - add the header from the service configuration.
  * `{:get_meta, metas}` - values of the final response to return:
    `:reason_phrase`, `:code`, `:call_id`, `:from`, `:to`, `:from_tag`,
    `:to_tag`, `:cseq_num`, `:body`, `:contacts`, `:handle`, `:dialog`,
    `:port` (the `Caracola.Transport.Port` it came from), `:all_headers`
    or any header name.
  * `:async` - return `{:async, handle}` at once; responses go to the
    callback.
  * `{:callback, fun}` - called with `{:resp, code, resp}` for provisional
    responses (and the final one in async mode), `{:req, req}` if
    `:get_request` is used, and `{:error, reason}` in async mode.
  * `{:subscription_state, state}` - Subscription-State of a NOTIFY (see
    `t:Caracola.Subscription.state/0`).
  * `:auto_2xx_ack` - send the ACK for 2xx responses to INVITE.
  * `:no_dialog` - do not create or update dialogs with this request.
  * `:no_auto_expire` - do not CANCEL an INVITE when its Expires time
    passes.
  * `{:session_expires, secs | {secs, :uac | :uas}}` and
    `{:min_se, secs}` - session timers (with `Caracola.SessionTimers`).
  * `{:prack_callback, fun}` - body of the PRACKs (with
    `Caracola.Rel100`).
  * `{:contact_params, params}` - header params (`[{name, value | nil}]`)
    of the automatic Contact, as feature tags (`[{"+sip.src", nil}]`).
  * `{:reg_id, n}` - `reg-id` of the Contact of a REGISTER (with
    `Caracola.Outbound`).
  * `{:refer_subscription, subscription}` - report the responses to this
    request with NOTIFYs to the subscription of a REFER (see
    `Caracola.Refer`).
  * `:new_connection`, `{:tls, opts}`, `{:connect_timeout, ms}`,
    `{:idle_timeout, ms}` - transport options.
  * `{:timeout, ms}` - maximum time to wait for the result.

# `handle`

```elixir
@type handle() :: {module(), String.t(), String.t()}
```

Identifies a request sent with `:async`, to cancel it.

# `result`

```elixir
@type result() ::
  {:ok, 100..699, list()} | {:async, handle()} | :ok | {:error, term()}
```

The result of sending a request.

# `target`

```elixir
@type target() :: module() | Caracola.Dialog.handle() | Caracola.Subscription.handle()
```

A service and a URI, or a dialog or subscription (and then the options go
second).

# `ack`

```elixir
@spec ack(Caracola.Dialog.handle(), list()) :: :ok | {:error, term()}
```

Sends the ACK for a 2xx response to an INVITE in a dialog. Returns `:ok`
once sent.

# `bye`

```elixir
@spec bye(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a BYE request. See `request/4`.

# `cancel`

```elixir
@spec cancel(handle(), list()) :: :ok | {:error, term()}
```

Cancels an INVITE sent with `:async`. The CANCEL is sent once a
provisional response has been received.

# `info`

```elixir
@spec info(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a INFO request. See `request/4`.

# `invite`

```elixir
@spec invite(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a INVITE request. See `request/4`.

# `message`

```elixir
@spec message(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a MESSAGE request. See `request/4`.

# `notify`

```elixir
@spec notify(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a NOTIFY request. See `request/4`.

# `options`

```elixir
@spec options(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a OPTIONS request. See `request/4`.

# `publish`

```elixir
@spec publish(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a PUBLISH request. See `request/4`.

# `refer`

```elixir
@spec refer(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a REFER request. See `request/4`.

# `refresh`

```elixir
@spec refresh(Caracola.Dialog.handle(), list()) :: result()
```

Refreshes the session of a dialog with a re-INVITE carrying the current
local SDP with a new version (or `{:body, sdp}`). `:hold`, `:inactive`
and `:active` change the direction of the medias.

# `register`

```elixir
@spec register(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a REGISTER request. See `request/4`.

# `request`

```elixir
@spec request(
  target(),
  Caracola.Message.method(),
  String.t() | Caracola.URI.t() | list(),
  list()
) ::
  result()
```

Sends a request with any method (an atom like `:options` or a string),
as `request(service, method, uri, opts)` or, inside a dialog,
`request(dialog, method, opts)`.

# `subscribe`

```elixir
@spec subscribe(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a SUBSCRIBE request. See `request/4`.

# `update`

```elixir
@spec update(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()
```

Sends a UPDATE request. See `request/4`.

---

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