Incoming requests go through the callbacks of the service. They are implemented with defcb; callbacks you do not implement use the default of Caracola (or of the plugins), and returning :cont from a clause falls back to it.

All the callbacks run in the process of the call, receiving the request (a Caracola.Message) and the call (a Caracola.Call, with the service and its config). They must return quickly: a slow callback blocks every other message of the same call.

Processing steps

For each new request (not retransmissions, ACKs or CANCELs of existing transactions), Caracola:

  1. Checks it (Max-Forwards, loops, required extensions...).
  2. Calls sip_authorize(auth_list, req, call) (see Authentication).
  3. Calls sip_route(scheme, user, domain, req, call) with the parts of the Request-URI, to decide what to do with it.
  4. If it is to be processed, calls the callback of its method: sip_invite/2, sip_options/2, sip_register/2, sip_bye/2, sip_info/2, sip_message/2, sip_update/2, sip_subscribe/2, sip_notify/2, sip_refer/2, sip_publish/2, sip_prack/2. A re-INVITE goes to sip_reinvite/2 (which calls sip_invite/2 by default), and a SUBSCRIBE refreshing a subscription to sip_resubscribe/2.

Routing

sip_route/5 returns:

  • :process (the default) - process the request, statefully.
  • :process_stateless - process it without a transaction (the reply is sent once, and retransmissions are processed again).
  • {:reply, reply} or {:reply_stateless, reply} - reply at once.
  • :proxy, {:proxy, uri_set} or {:proxy, uri_set, opts} - proxy it statefully; and :proxy_stateless... to proxy it without state. See Proxies.
defcb sip_route(_scheme, nil, "example.com", _req, _call), do: :process
defcb sip_route(_scheme, user, "example.com", _req, call), do: {:proxy, locate(user, call)}
defcb sip_route(_scheme, _user, _domain, _req, _call), do: {:reply, :forbidden}

user is nil when the Request-URI has no user part.

Replying

Method callbacks return {:reply, reply}, where reply is a status code, {code, opts} or a shortcut, like :ok, :busy, :decline, {:redirect, contacts} or {:invalid_request, "Reason"}. See Caracola.Reply for all of them and the response options:

defcb sip_options(_req, _call),
  do: {:reply, {:ok, [:allow, :supported, {:add, "x-version", "1.0"}]}}

defcb sip_message(req, _call) do
  IO.puts("Message: #{req.body}")
  {:reply, :ok}
end

Replying later

A callback can return :noreply and reply from another process with Caracola.reply/2, several times for provisional responses:

defcb sip_invite(req, _call) do
  spawn(fn ->
    :ok = Caracola.reply(req, :ringing)
    sdp = MyMedia.answer(req.body)
    Caracola.reply(req, {:answer, sdp})
  end)

  :noreply
end

If no final response is sent, INVITE transactions are answered with a 408 after timer C (three minutes by default, :timer_c), and other requests with a 408 after 64·T1 (32 seconds by default).

As a safety net, every call removes the transactions older than twice :trans_timeout (15 minutes by default) and the dialogs without activity for twice :dialog_timeout.

Reading requests

The request is a Caracola.Message. The main headers are parsed into its fields (ruri, from, to, contacts, routes, vias, call_id, cseq, expires, event, content_type, supported, require...); the others are in headers, and Caracola.Message.header/2 returns the values of any header by name:

defcb sip_invite(req, _call) do
  [agent] = Caracola.Message.header(req, "user-agent")
  %Caracola.URI{user: caller} = req.from
  sdp = Caracola.SDP.from_message(req)
  ...
end

Notifications

Some callbacks only notify, and their result is ignored:

  • sip_ack(req, call) - the ACK of a 2xx response to INVITE.
  • sip_cancel(invite_req, cancel_req, call) - an INVITE was cancelled; Caracola replies 487 to it.
  • sip_dialog_update(event, dialog, call) and sip_session_update(event, dialog, call) - changes in dialogs and their sessions, see Dialogs and subscriptions.

Defaults

CallbackDefault
sip_authorize/3:ok
sip_get_user_pass/4false (no users)
sip_route/5:process
sip_options/2200 with Contact, Allow, Allow-Event, Accept and Supported
sip_invite/2603 Decline
sip_reinvite/2calls sip_invite/2
sip_register/2405 (the registrar plugin processes them)
sip_bye/2200
sip_info/2200
sip_message/2603 Decline
sip_update/2603 Decline
sip_subscribe/2603 Decline
sip_resubscribe/2200
sip_notify/2200
sip_unsolicited_notify/2481 (NOTIFYs outside of any subscription)
sip_refer/2603 (the refer plugin processes them)
sip_publish/2405 (the event compositor plugin processes them)
sip_prack/2200

The list of callbacks and their arguments is in the documentation of the Caracola module.