Installation
Add caracola to your dependencies in mix.exs:
def deps do
[
{:caracola, "~> 0.1.0-rc.1"}
]
endCaracola requires Elixir 1.18 or later. It brings Malla, whose concepts (services, plugins, callbacks, configuration) are worth a look; this guide only covers what a SIP application needs.
A service
A SIP application is a Malla service using the Caracola plugin, or any of
the SIP plugins (they all depend on it):
defmodule MyUA do
use Malla.Service,
plugins: [Caracola],
sip: [
listen: "sip:all:5060, <sip:all:5061;transport=tls>",
from: "\"My UA\" <sip:my_ua@example.com>",
tls: [certfile: "priv/cert.pem", keyfile: "priv/key.pem"]
]
defcb sip_invite(_req, _call), do: {:reply, :decline}
endThe SIP configuration goes under the :sip key. The main options are:
:listen- the listening addresses, as URIs.sip:all:5060listens on all the IPv4 interfaces, on port 5060, for UDP and TCP (UDP listeners always listen on TCP on the same port). Usetransport=tcp,tls,wsorwssfor other transports,sips:for TLS, port0for a random port, and[::1]orall6(any IPv6 address) for IPv6. A path is the HTTP path accepted by WS and WSS listeners:<sip:all:8080/ws;transport=ws>.:from- the default From of the requests.:local_host(and:local_host6) - the host in the Via, Contact and Record-Route headers, instead of the IP of the listener (or the main IP of the machine, for listeners on all interfaces).:route- routes for all the requests (an outbound proxy).:tls-:ssloptions of the TLS and WSS listeners, and:tls_client- options of the outgoing TLS connections (the server certificate is verified against the system CAs by default).:timer_t1,:timer_t2... - SIP timers.
See Caracola.Config for all of them.
Configuration given when starting the service is deep-merged with the one in the module:
MyUA.start_link(sip: [listen: "sip:127.0.0.1:5070"])Usually you will start it in your application supervisor:
children = [
{MyUA, sip: [listen: "sip:all:5060"]}
]MyUA.stop() stops it. Services can be reconfigured at runtime (see
Malla's documentation); a change in the :sip configuration restarts the
SIP part of the service.
Sending requests
Requests are sent with the functions of Caracola.UAC, giving the service,
the destination URI and a list of options:
iex> Caracola.UAC.options(MyUA, "sip:sip.example.com")
{:ok, 200, []}
iex> Caracola.UAC.options(MyUA, "<sip:127.0.0.1:5070;transport=tcp>",
...> get_meta: [:reason_phrase, "server"])
{:ok, 200, [reason_phrase: "OK", {"server", ["MyServer 1.0"]}]}The call waits for the final response, and returns its code and the values
asked for with :get_meta. See Sending requests.
Receiving requests
Incoming requests go through the sip_* callbacks of the service.
sip_route/5 decides what to do with each request (process it, proxy it
or reply at once) and, for the requests to process, the callback of its
method (sip_invite/2, sip_options/2, sip_register/2...) replies to it:
defcb sip_options(_req, _call), do: {:reply, {:ok, [:allow, :supported]}}Any callback you do not implement has a default (OPTIONS are answered, INVITEs declined, REGISTERs rejected unless you use the registrar plugin...). See Receiving requests.
Plugins
SIP extensions are plugins, listed in :plugins instead of (or with)
Caracola:
use Malla.Service,
plugins: [Caracola.Registrar, Caracola.Rel100],
sip: [listen: "sip:all:5060"],
registrar: [min_time: 60]See Plugins.
Tracing messages
To see the SIP messages sent and received, while developing:
Caracola.Telemetry.trace(true)They are logged at the :info level. See Observability.