Caracola.UAC (Caracola v0.1.0-rc.1)

Copy Markdown View Source

Sending requests. Equivalent to NkSIP's nksip_uac.

Requests are sent from a service (which must have listeners for the transports used) to a URI. By default the call waits for the final response and returns {:ok, code, metas}, or {:error, reason} if the request could not be sent.

In-dialog requests are sent passing a Caracola.Dialog.handle/0 instead of the service and the URI: bye(dialog), invite(dialog, body: sdp)... Their From, To, Call-ID, CSeq, Route and Contact come from the dialog. They fail with {:error, :unknown_dialog} if the dialog does not exist, or {:error, :request_pending} if another INVITE or offer is in progress.

Responses to INVITE (101-299) always include the dialog handle as the first meta: {:ok, 200, [dialog: dialog]}, and 2xx responses to SUBSCRIBE and REFER the subscription handle: [subscription: subscription] (see Caracola.Subscription). The ACK for a 2xx response must be sent with ack/2, unless the INVITE is sent with :auto_2xx_ack.

Options

  • {:add | :replace | :insert, name, value} - header manipulation, see Caracola.Message.update_header/4; {:remove, name} removes a header (Caracola.Message.remove_header/2).

  • {name, value} for :from, :to, :contact, :route, :content_type, :require, :supported, :expires, :event, :reason, :refer_to and :sip_if_match - replace the header.
  • {:body, body} (a binary or a Caracola.SDP, which also sets the Content-Type), {:call_id, call_id} and {:cseq_num, num}.
  • :contact - add a Contact with the address of the transport used (added automatically for INVITE, SUBSCRIBE, NOTIFY, REFER and UPDATE).
  • :unregister ([:contact, expires: 0]) and :unregister_all ([contact: "*", expires: 0]), for REGISTER.
  • {:password, password} - answer 401 and 407 challenges (a password, an HA1 as {:ha1, hex} for MD5 or {:ha1, algorithm, hex}, {realm, password} or a list of them), sending the request again with the credentials. For each realm, the challenge with the strongest algorithm (SHA-512-256, SHA-256, MD5) that can be answered is used. The :password of the service configuration is also used.
  • :allow, :supported, :accept, :allow_event, :date and :user_agent - add the header from the service configuration.
  • {:get_meta, metas} - values of the final response to return: :reason_phrase, :code, :call_id, :from, :to, :from_tag, :to_tag, :cseq_num, :body, :contacts, :handle, :dialog, :port (the Caracola.Transport.Port it came from), :all_headers or any header name.
  • :async - return {:async, handle} at once; responses go to the callback.
  • {:callback, fun} - called with {:resp, code, resp} for provisional responses (and the final one in async mode), {:req, req} if :get_request is used, and {:error, reason} in async mode.
  • {:subscription_state, state} - Subscription-State of a NOTIFY (see Caracola.Subscription.state/0).
  • :auto_2xx_ack - send the ACK for 2xx responses to INVITE.
  • :no_dialog - do not create or update dialogs with this request.
  • :no_auto_expire - do not CANCEL an INVITE when its Expires time passes.
  • {:session_expires, secs | {secs, :uac | :uas}} and {:min_se, secs} - session timers (with Caracola.SessionTimers).

  • {:prack_callback, fun} - body of the PRACKs (with Caracola.Rel100).
  • {:contact_params, params} - header params ([{name, value | nil}]) of the automatic Contact, as feature tags ([{"+sip.src", nil}]).

  • {:reg_id, n} - reg-id of the Contact of a REGISTER (with Caracola.Outbound).
  • {:refer_subscription, subscription} - report the responses to this request with NOTIFYs to the subscription of a REFER (see Caracola.Refer).
  • :new_connection, {:tls, opts}, {:connect_timeout, ms}, {:idle_timeout, ms} - transport options.
  • {:timeout, ms} - maximum time to wait for the result.

Summary

Types

Identifies a request sent with :async, to cancel it.

The result of sending a request.

A service and a URI, or a dialog or subscription (and then the options go second).

Functions

Sends the ACK for a 2xx response to an INVITE in a dialog. Returns :ok once sent.

Cancels an INVITE sent with :async. The CANCEL is sent once a provisional response has been received.

Refreshes the session of a dialog with a re-INVITE carrying the current local SDP with a new version (or {:body, sdp}). :hold, :inactive and :active change the direction of the medias.

Sends a request with any method (an atom like :options or a string), as request(service, method, uri, opts) or, inside a dialog, request(dialog, method, opts).

Types

handle()

@type handle() :: {module(), String.t(), String.t()}

Identifies a request sent with :async, to cancel it.

result()

@type result() ::
  {:ok, 100..699, list()} | {:async, handle()} | :ok | {:error, term()}

The result of sending a request.

target()

A service and a URI, or a dialog or subscription (and then the options go second).

Functions

ack(dialog, opts \\ [])

@spec ack(Caracola.Dialog.handle(), list()) :: :ok | {:error, term()}

Sends the ACK for a 2xx response to an INVITE in a dialog. Returns :ok once sent.

bye(target, uri_or_opts \\ [], opts \\ [])

@spec bye(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a BYE request. See request/4.

cancel(arg, opts \\ [])

@spec cancel(handle(), list()) :: :ok | {:error, term()}

Cancels an INVITE sent with :async. The CANCEL is sent once a provisional response has been received.

info(target, uri_or_opts \\ [], opts \\ [])

@spec info(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a INFO request. See request/4.

invite(target, uri_or_opts \\ [], opts \\ [])

@spec invite(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a INVITE request. See request/4.

message(target, uri_or_opts \\ [], opts \\ [])

@spec message(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a MESSAGE request. See request/4.

notify(target, uri_or_opts \\ [], opts \\ [])

@spec notify(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a NOTIFY request. See request/4.

options(target, uri_or_opts \\ [], opts \\ [])

@spec options(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a OPTIONS request. See request/4.

publish(target, uri_or_opts \\ [], opts \\ [])

@spec publish(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a PUBLISH request. See request/4.

refer(target, uri_or_opts \\ [], opts \\ [])

@spec refer(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a REFER request. See request/4.

refresh(dialog, opts \\ [])

@spec refresh(Caracola.Dialog.handle(), list()) :: result()

Refreshes the session of a dialog with a re-INVITE carrying the current local SDP with a new version (or {:body, sdp}). :hold, :inactive and :active change the direction of the medias.

register(target, uri_or_opts \\ [], opts \\ [])

@spec register(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a REGISTER request. See request/4.

request(target, method, uri_or_opts \\ [], opts \\ [])

@spec request(
  target(),
  Caracola.Message.method(),
  String.t() | Caracola.URI.t() | list(),
  list()
) ::
  result()

Sends a request with any method (an atom like :options or a string), as request(service, method, uri, opts) or, inside a dialog, request(dialog, method, opts).

subscribe(target, uri_or_opts \\ [], opts \\ [])

@spec subscribe(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a SUBSCRIBE request. See request/4.

update(target, uri_or_opts \\ [], opts \\ [])

@spec update(target(), String.t() | Caracola.URI.t() | list(), list()) :: result()

Sends a UPDATE request. See request/4.