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, seeCaracola.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_toand:sip_if_match- replace the header.{:body, body}(a binary or aCaracola.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:passwordof the service configuration is also used.:allow,:supported,:accept,:allow_event,:dateand: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(theCaracola.Transport.Portit came from),:all_headersor 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_requestis used, and{:error, reason}in async mode.{:subscription_state, state}- Subscription-State of a NOTIFY (seeCaracola.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 (withCaracola.SessionTimers).{:prack_callback, fun}- body of the PRACKs (withCaracola.Rel100).{:contact_params, params}- header params ([{name, value | nil}]) of the automatic Contact, as feature tags ([{"+sip.src", nil}]).{:reg_id, n}-reg-idof the Contact of a REGISTER (withCaracola.Outbound).{:refer_subscription, subscription}- report the responses to this request with NOTIFYs to the subscription of a REFER (seeCaracola.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.
Sends a BYE request. See request/4.
Cancels an INVITE sent with :async. The CANCEL is sent once a
provisional response has been received.
Sends a INFO request. See request/4.
Sends a INVITE request. See request/4.
Sends a MESSAGE request. See request/4.
Sends a NOTIFY request. See request/4.
Sends a OPTIONS request. See request/4.
Sends a PUBLISH request. See request/4.
Sends a REFER request. See request/4.
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 REGISTER request. See request/4.
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).
Sends a SUBSCRIBE request. See request/4.
Sends a UPDATE request. See request/4.
Types
Identifies a request sent with :async, to cancel it.
The result of sending a request.
@type target() :: module() | Caracola.Dialog.handle() | Caracola.Subscription.handle()
A service and a URI, or a dialog or subscription (and then the options go second).
Functions
@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.
Sends a BYE request. See request/4.
Cancels an INVITE sent with :async. The CANCEL is sent once a
provisional response has been received.
Sends a INFO request. See request/4.
Sends a INVITE request. See request/4.
Sends a MESSAGE request. See request/4.
Sends a NOTIFY request. See request/4.
Sends a OPTIONS request. See request/4.
Sends a PUBLISH request. See request/4.
Sends a REFER request. See request/4.
@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.
Sends a REGISTER request. See request/4.
@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).
Sends a SUBSCRIBE request. See request/4.
Sends a UPDATE request. See request/4.