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

Automatic registrations and pings. Equivalent to NkSIP's
`nksip_uac_auto_register`.

```
defmodule MyUA do
  use Malla.Service,
    plugins: [Caracola.UACAutoRegister],
    sip: [listen: "sip:all:5060"],
    uac_auto_register: [timer: 5]
end

{:ok, true} = Caracola.UACAutoRegister.start_register(MyUA, :reg1, "sip:registrar.com", [])
```

`start_register/4` sends a REGISTER (with a Contact and the
options given, see `Caracola.UAC`) and keeps refreshing it before it
expires (`expires: 300` by default). `start_ping/4` sends an OPTIONS
every `expires` seconds (300 by default). Both return when the first
response arrives, with `{:ok, true}` for a 2xx and `{:ok, false}`
otherwise. Failed registrations and pings are retried after the same
time (or the Retry-After of a 503).

Changes in their state are notified with the callbacks
`sip_uac_auto_register_updated_reg(id, ok, service)` and
`sip_uac_auto_register_updated_ping(id, ok, service)`.

Registrations are removed (sending a REGISTER with `expires: 0`) with
`stop_register/2`, and when the service stops.

## Configuration

Under the `:uac_auto_register` key:

  * `:timer` - interval (secs) to check if registrations and pings must
    be sent (5 by default).

# `id`

```elixir
@type id() :: term()
```

Identifies a registration.

# `get_pings`

```elixir
@spec get_pings(module()) :: [{id(), boolean() | nil, integer()}]
```

Returns the pings, as `get_registers/1`.

# `get_registers`

```elixir
@spec get_registers(module()) :: [{id(), boolean() | nil, integer()}]
```

Returns the automatic registrations: their id, if the last one was
successful, and the seconds to the next one.

# `service_route`

```elixir
@spec service_route(module(), id()) :: [String.t()]
```

Returns the Service-Route (RFC 3608) of the last successful response to
a registration: the routes to use as the `:route` of the requests sent
through that registrar (`[]` if it returned none, or the registration
is not found).

    routes = Caracola.UACAutoRegister.service_route(MyUA, :reg1)
    Caracola.UAC.invite(MyUA, "sip:bob@example.com", route: routes)

# `start_ping`

```elixir
@spec start_ping(module(), id(), String.t() | Caracola.URI.t(), list()) ::
  {:ok, boolean()} | {:error, term()}
```

Starts sending OPTIONS to `uri` periodically.

# `start_register`

```elixir
@spec start_register(module(), id(), String.t() | Caracola.URI.t(), list()) ::
  {:ok, boolean()} | {:error, term()}
```

Starts an automatic registration, replacing any other with the same `id`.
`uri` is the registrar.

# `stop_ping`

```elixir
@spec stop_ping(module(), id()) :: :ok | :not_found
```

Stops a ping.

# `stop_register`

```elixir
@spec stop_register(module(), id()) :: :ok | :not_found
```

Stops an automatic registration, unregistering it.

---

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