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

`Malla.Plugin` providing a SIP stack to a `Malla.Service`.

```
defmodule MyUA do
  use Malla.Service,
    plugins: [Caracola],
    sip: [listen: "sip:all:5060, <sip:all:5061;transport=tls>"]

  defcb sip_options(_req, _call), do: {:reply, :ok}
end
```

Configuration goes under the `:sip` key; see `Caracola.Config` for the
options. A missing `:sip` key is equivalent to `sip: []` (all defaults).

## Callbacks

Incoming requests go through the `sip_*` callbacks, which services can
implement with `defcb` (returning `:cont` to fall back to the default):

  * `sip_authorize(auth_list, req, call)` - `:ok` (default), `:forbidden`,
    `:authenticate`, `{:authenticate, realm}`, `:proxy_authenticate` or
    `{:proxy_authenticate, realm}`. It is called first with an empty
    list and, if the result is not `:ok`, again with the authorization
    list: `:dialog` if the request comes from an authorized origin of its
    dialog (see `Caracola.Dialog.authorized/1`), and
    `{{:digest, realm}, result}` for the credentials of each realm, where
    `result` is `true`, `false` (wrong password or unknown user) or
    `:invalid` (unknown or expired nonce, or invalid credentials).
  * `sip_get_user_pass(user, realm, req, call)` - the password of a user
    (a binary, or an HA1 as `{:ha1, hex}` for MD5 or `{:ha1, algorithm, hex}`,
    see `Caracola.Digest.ha1/4`), `true` to
    accept it without checking or `false` (default) if unknown.
  * `sip_route(scheme, user, domain, req, call)` - `:process` (default),
    `:process_stateless`, `{:reply, reply}`, `{:reply_stateless, reply}`,
    or to proxy the request: `:proxy` (to the Request-URI),
    `{:proxy, uri_set}` or `{:proxy, uri_set, opts}` (`uri_set` can be
    `:ruri`, see [Proxies](07-proxy.md)), and the same with
    `:proxy_stateless`. `:noreply` routes the request later, with
    `route/2` (not for ACK and CANCEL). Proxy options are the header options of
    `Caracola.UAC` plus `:record_route`, `:path` and `:follow_redirects`.
  * `sip_invite`, `sip_reinvite`, `sip_bye`, `sip_options`, `sip_register`,
    `sip_info`, `sip_message`, `sip_update`, `sip_subscribe`,
    `sip_resubscribe`, `sip_notify`, `sip_refer`, `sip_publish` and
    `sip_prack`, called as `fun(req, call)` - `{:reply, reply}` or
    `:noreply`, to reply later with `reply/2`.
  * `sip_unsolicited_notify(req, call)` - a NOTIFY outside of any
    dialog or subscription, as the message waiting (`message-summary`)
    ones many PBXs send to registered phones. Same results as above; the
    default replies 481, as RFC 6665 requires. Accepting it creates no
    dialog.
  * `sip_ack(req, call)` and `sip_cancel(invite_req, cancel_req, call)` -
    notifications, the result is ignored.
  * `sip_dialog_update(event, dialog, call)` - a `Caracola.Dialog` has
    changed. `event` is `:start`, `{:invite_status, status}` (see
    `Caracola.Dialog.Invite`; `{:stop, reason}` when the INVITE usage
    ends, and a dialog created by a provisional response gets its first
    `:proceeding_uac` or `:proceeding_uas` too), `:target_update`,
    `:invite_timeout`, `{:invite_refresh, local_sdp}` (session timers: time
    to refresh the session, see `Caracola.SessionTimers`),
    `{:subscription_status, status, subscription}` (see
    `Caracola.Subscription`) or `:stop`. The result is ignored.
  * `sip_session_update(event, dialog, call)` - the session of a dialog has
    changed: `{:start, local_sdp, remote_sdp}`,
    `{:update, local_sdp, remote_sdp}` or `:stop`. The result is ignored.

Replies are described in `Caracola.Reply`. To send requests, see
`Caracola.UAC`.

# `listeners`

```elixir
@spec listeners(module()) :: [Caracola.Transport.Port.t()]
```

Returns the listeners of a service.

# `reply`

```elixir
@spec reply(Caracola.Message.t(), Caracola.Reply.sipreply()) :: :ok | {:error, term()}
```

Replies to a request received in a `sip_*` callback that returned
`:noreply`. Must be called from another process.

# `route`

```elixir
@spec route(Caracola.Message.t(), term()) :: :ok | {:error, term()}
```

Routes a request received in `sip_route/5`, that returned `:noreply`:
`route` is any other result of `sip_route/5`. Must be called from
another process. Returns an error if the request is gone (for example,
it was cancelled or timed out).

---

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