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:
- Checks it (Max-Forwards, loops, required extensions...).
- Calls
sip_authorize(auth_list, req, call)(see Authentication). - Calls
sip_route(scheme, user, domain, req, call)with the parts of the Request-URI, to decide what to do with it. - 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 tosip_reinvite/2(which callssip_invite/2by default), and a SUBSCRIBE refreshing a subscription tosip_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}
endReplying 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
endIf 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)
...
endNotifications
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)andsip_session_update(event, dialog, call)- changes in dialogs and their sessions, see Dialogs and subscriptions.
Defaults
| Callback | Default |
|---|---|
sip_authorize/3 | :ok |
sip_get_user_pass/4 | false (no users) |
sip_route/5 | :process |
sip_options/2 | 200 with Contact, Allow, Allow-Event, Accept and Supported |
sip_invite/2 | 603 Decline |
sip_reinvite/2 | calls sip_invite/2 |
sip_register/2 | 405 (the registrar plugin processes them) |
sip_bye/2 | 200 |
sip_info/2 | 200 |
sip_message/2 | 603 Decline |
sip_update/2 | 603 Decline |
sip_subscribe/2 | 603 Decline |
sip_resubscribe/2 | 200 |
sip_notify/2 | 200 |
sip_unsolicited_notify/2 | 481 (NOTIFYs outside of any subscription) |
sip_refer/2 | 603 (the refer plugin processes them) |
sip_publish/2 | 405 (the event compositor plugin processes them) |
sip_prack/2 | 200 |
The list of callbacks and their arguments is in the documentation of the
Caracola module.