A parsed SIP request or response. Equivalent to NkSIP's #sipmsg{}.
The most used headers are pre-parsed into their own fields. Any other
header is kept, in order, in headers as {lowercase_name, raw_value}.
Messages handled by a service also carry the service id, a unique id,
the transport port they were received from or sent through and the
dialog_id of the dialog they belong to (see Caracola.Dialog.handle/1).
Methods are lowercase atoms for the ones defined in RFCs (:invite,
:register...) and strings for any other.
Summary
Types
The class of a message: {:req, method} or {:resp, code, reason}.
A SIP method, as an atom (:invite, :register...) or a binary for unknown ones.
A SIP message, request or response, parsed.
Functions
Gets all values of a non pre-parsed header.
Gets the values of any header as strings, including the pre-parsed ones.
Returns the method of a request, or of the request a response belongs to.
Converts a method to its wire form.
Removes all the values of a header. From, To, Call-ID, CSeq and Via cannot be removed.
Converts a method from its wire form. Method names are case-sensitive.
Adds (at the end), inserts (at the beginning) or replaces the values of a
header. Pre-parsed headers are parsed and stored in their fields;
From and To also update the tags.
Types
The class of a message: {:req, method} or {:resp, code, reason}.
@type method() :: :invite | :ack | :cancel | :bye | :options | :register | :subscribe | :notify | :publish | :refer | :message | :info | :prack | :update | String.t()
A SIP method, as an atom (:invite, :register...) or a binary for unknown ones.
@type t() :: %Caracola.Message{ body: binary(), call_id: String.t(), class: class(), contacts: [Caracola.URI.t()], content_type: Caracola.Tokens.token() | nil, cseq: {non_neg_integer(), method()}, dialog_id: String.t() | nil, event: Caracola.Tokens.token() | nil, expires: non_neg_integer() | nil, from: Caracola.URI.t(), from_tag: String.t() | nil, headers: [{String.t(), String.t()}], id: String.t() | nil, max_forwards: non_neg_integer() | nil, port: Caracola.Transport.Port.t() | nil, require: [String.t()], routes: [Caracola.URI.t()], ruri: Caracola.URI.t() | nil, service: term(), supported: [String.t()], to: Caracola.URI.t(), to_tag: String.t() | nil, vias: [Caracola.Via.t()] }
A SIP message, request or response, parsed.
Functions
Gets all values of a non pre-parsed header.
Gets the values of any header as strings, including the pre-parsed ones.
iex> {:ok, msg, _} = Caracola.Parser.parse("OPTIONS sip:a SIP/2.0\r\nVia: SIP/2.0/UDP h\r\nFrom: <sip:a>;tag=1\r\nTo: <sip:b>\r\nCall-ID: 1\r\nCSeq: 1 OPTIONS\r\nSupported: path, 100rel\r\n\r\n")
iex> Caracola.Message.header(msg, "Supported")
["path, 100rel"]
iex> Caracola.Message.header(msg, "from")
["<sip:a>;tag=1"]
Returns the method of a request, or of the request a response belongs to.
Converts a method to its wire form.
Removes all the values of a header. From, To, Call-ID, CSeq and Via cannot be removed.
iex> {:ok, msg} = Caracola.Message.update_header(%Caracola.Message{}, :add, "X-Data", "a")
iex> Caracola.Message.remove_header(msg, :x_data).headers
[]
Converts a method from its wire form. Method names are case-sensitive.
iex> Caracola.Message.to_method("INVITE")
:invite
iex> Caracola.Message.to_method("invite")
"invite"
@spec update_header(t(), :add | :insert | :replace, String.t() | atom(), term()) :: {:ok, t()} | {:error, {:invalid, String.t()}}
Adds (at the end), inserts (at the beginning) or replaces the values of a
header. Pre-parsed headers are parsed and stored in their fields;
From and To also update the tags.
Values can be strings, integers, atoms, lists of them (joined with ", "),
Caracola.URI structs and tokens. Replacing with [] removes the header.
Via, CSeq and Content-Length cannot be changed.
iex> msg = %Caracola.Message{}
iex> {:ok, msg} = Caracola.Message.update_header(msg, :replace, "From", "<sip:a@b>;tag=t1")
iex> {msg.from.user, msg.from_tag}
{"a", "t1"}
iex> {:ok, msg} = Caracola.Message.update_header(msg, :add, "X-Data", ["a", 1])
iex> msg.headers
[{"x-data", "a, 1"}]
iex> Caracola.Message.update_header(msg, :add, "Contact", "<sip:a")
{:error, {:invalid, "contact"}}