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

Session timers (RFC 4028). Equivalent to NkSIP's `nksip_timers`.

```
defmodule MyUA do
  use Malla.Service,
    plugins: [Caracola.SessionTimers],
    sip: [listen: "sip:all:5060", session_expires: 1800, min_se: 90]
end
```

The plugin adds `timer` to the Supported header. With it, INVITE and
UPDATE transactions negotiate a session interval:

  * Requests can propose one with `{:session_expires, interval}` or
    `{:session_expires, {interval, :uac | :uas}}` (the refresher), and a
    `{:min_se, interval}`. In-dialog requests get the current interval
    automatically. A 422 (interval too small) is answered sending the
    request again with the Min-SE of the response.
  * Requests with an interval below the `:min_se` of the service are
    rejected with 422. The 2xx responses include the interval (the
    `:session_expires` of the service, or the requested one if lower),
    with the UAS as refresher unless the request asks for one.
  * Proxies lower the interval of the requests to their `:session_expires`,
    and add it to the responses if the UAS does not support timers.

When the session is established, the refresher gets
`sip_dialog_update({:invite_refresh, local_sdp}, dialog, call)` at half
the interval, and should refresh it (for example with
`Caracola.UAC.refresh/2` or an UPDATE). If it is not refreshed, the other
party sends a BYE before the interval ends.

# `session_expires`

```elixir
@spec session_expires(Caracola.Dialog.handle()) ::
  {:ok, pos_integer() | nil} | {:error, term()}
```

Returns the session interval of a dialog (secs), or `nil` without session timer.

# `session_refresh`

```elixir
@spec session_refresh(Caracola.Dialog.handle()) ::
  {:ok, non_neg_integer() | :expired | nil} | {:error, term()}
```

Returns the time to the next refresh notification (msecs), `:expired` if
it was already sent, or `nil` if we are not the refresher.

---

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