Requests are sent with Caracola.UAC. There is a function per method
(options/3, invite/3, register/3, subscribe/3, notify/3,
message/3, info/3, update/3, refer/3, publish/3, bye/3), and
Caracola.UAC.request/4 for any method.
Caracola.UAC.options(MyUA, "sip:sip.example.com", opts)
Caracola.UAC.request(MyUA, "MESSAGE", "sip:bob@example.com", body: "Hi")Destination
The destination is a URI, as a string or a Caracola.URI. Write it between
< and > when it has URI parameters: "<sip:host;transport=tcp>".
Without them, the parameters would belong to the header, not to the URI.
The request is sent to the first route (the :route option, or the
:route of the service configuration) or, without routes, to the
Request-URI. The transport, address and port are resolved following RFC
3263 (NAPTR, SRV and A/AAAA records), trying each address in order until
one works. The service needs a listener for the transport used: a service
listening only on UDP can not send over TLS.
Results
By default, the call blocks until the final response arrives and returns
{:ok, code, metas}:
{:ok, 200, []} = Caracola.UAC.options(MyUA, "sip:sip.example.com")or {:error, reason} if the request could not be generated (an invalid
URI or option, an unknown dialog...). If it can not be sent (the name does
not resolve, no listener for the transport, the connection is refused),
the result is {:error, :service_unavailable}. A destination that does
not answer generates a 408 response.
metas has the values asked for with :get_meta: parts of the response
(:reason_phrase, :contacts, :body, :call_id, :cseq_num, :to_tag,
:all_headers...) or headers by name (always lowercase), as lists of
values:
{:ok, 200, [reason_phrase: "OK", {"server", ["Asterisk"]}]} =
Caracola.UAC.options(MyUA, uri, get_meta: [:reason_phrase, "server"])Responses to INVITE always have the dialog handle first ([dialog: dialog]),
and 2xx responses to SUBSCRIBE and REFER the subscription handle
([subscription: subscription]).
Asynchronous requests
With :async, the function returns at once with {:async, handle}, and the
responses go to the :callback function:
{:async, handle} =
Caracola.UAC.invite(MyUA, uri, [
:async,
callback: fn
{:resp, code, _resp} -> send(pid, {:invite, code})
{:error, error} -> send(pid, {:invite_error, error})
end
])
# Cancels it, if there is no final response yet
Caracola.UAC.cancel(handle)The callback also gets the provisional responses ({:resp, 180, resp}) in
synchronous mode, and the request sent ({:req, req}) with :get_request.
Headers and body
The common headers have options: from:, to:, route:, contact:,
content_type:, expires:, event:, require:, supported:... Others
are added with {:add, name, value}, {:replace, name, value} or
{:insert, name, value}:
Caracola.UAC.message(MyUA, "sip:bob@example.com", [
{:add, "x-custom", "value"},
content_type: "text/plain",
body: "Hello"
])Some options add headers from the service configuration: :allow,
:supported, :accept, :allow_event, :date, :user_agent. :contact
adds a Contact with the address of the transport used (INVITE, SUBSCRIBE,
NOTIFY, REFER and UPDATE get one automatically).
The body can be a binary or a Caracola.SDP, which also sets the
Content-Type:
sdp = Caracola.SDP.new("10.0.0.1", [{"audio", 4000, [{:rtpmap, 0, "PCMU/8000"}]}])
Caracola.UAC.invite(MyUA, uri, body: sdp)URI headers in the destination are added to the request:
"<sip:bob@example.com?subject=hi&priority=urgent>".
Authentication
password: password answers the 401 and 407 challenges of the request:
it is sent again with the credentials. It can be a list of passwords, or
{realm, password} pairs; {:ha1, hex} (MD5) and {:ha1, algorithm, hex}
are precomputed digests (see Caracola.Digest.ha1/4). SHA-256 and
SHA-512-256 challenges are answered too. The :password of the service configuration is
also used. See Authentication.
Registrations
# Registers the address of the transport used, for an hour
Caracola.UAC.register(MyUA, "sip:registrar.example.com", [:contact, expires: 3600])
# The current contacts
{:ok, 200, [contacts: contacts]} =
Caracola.UAC.register(MyUA, "sip:registrar.example.com", get_meta: [:contacts])
# Removes our contact, or all of them
Caracola.UAC.register(MyUA, "sip:registrar.example.com", [:unregister])
Caracola.UAC.register(MyUA, "sip:registrar.example.com", [:unregister_all])To keep a registration refreshed, see Caracola.UACAutoRegister.
In-dialog requests
Requests inside a dialog are sent with the dialog handle instead of the service and URI. Their From, To, Call-ID, CSeq, Route and Contact come from the dialog:
{:ok, 200, [dialog: dialog]} = Caracola.UAC.invite(MyUA, uri, body: sdp)
:ok = Caracola.UAC.ack(dialog)
{:ok, 200, []} = Caracola.UAC.info(dialog, body: "...", content_type: "application/x")
{:ok, 200, _} = Caracola.UAC.invite(dialog, body: new_sdp) # re-INVITE
{:ok, 200, []} = Caracola.UAC.bye(dialog)The ACK of a 2xx response to INVITE must be sent with Caracola.UAC.ack/2,
unless the INVITE has the :auto_2xx_ack option. Caracola.UAC.refresh/2
sends a re-INVITE with the current local SDP (with a new version), and can
put the call on hold (:hold, :inactive, :active).
See Dialogs and subscriptions.
Other options
call_id:andcseq_num:- use these Call-ID and CSeq number.timeout:- maximum time to wait (milliseconds).:no_dialog- do not create dialogs with this request.:new_connection- use a new connection, instead of reusing one.tls:,connect_timeout:,idle_timeout:- options for new connections.
See Caracola.UAC for the full list, including the options of the plugins
(session_expires:, reg_id:, refer_to:...).