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: and cseq_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:...).