Caracola.UACAutoRegister (Caracola v0.1.0-rc.1)

Copy Markdown View Source

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).

Summary

Types

Identifies a registration.

Functions

Returns the pings, as get_registers/1.

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

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).

Starts sending OPTIONS to uri periodically.

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

Stops a ping.

Stops an automatic registration, unregistering it.

Types

id()

@type id() :: term()

Identifies a registration.

Functions

get_pings(service)

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

Returns the pings, as get_registers/1.

get_registers(service)

@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(service, id)

@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(service, id, uri, opts \\ [])

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

Starts sending OPTIONS to uri periodically.

start_register(service, id, uri, opts \\ [])

@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(service, id)

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

Stops a ping.

stop_register(service, id)

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

Stops an automatic registration, unregistering it.