Caracola (Caracola v0.1.0-rc.1)

Copy Markdown View Source

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

Summary

Functions

Returns the listeners of a service.

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

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

Functions

listeners(service)

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

Returns the listeners of a service.

reply(message, sipreply)

@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(message, route)

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