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

Copy Markdown View Source

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.

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.

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

class()

@type class() :: {:req, method()} | {:resp, 100..699, String.t()}

The class of a message: {:req, method} or {:resp, code, reason}.

method()

@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.

t()

@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

get_headers(message, name)

@spec get_headers(t(), String.t()) :: [String.t()]

Gets all values of a non pre-parsed header.

header(msg, name)

@spec header(t(), String.t()) :: [String.t()]

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"]

method(message)

@spec method(t()) :: method()

Returns the method of a request, or of the request a response belongs to.

method_to_string(method)

@spec method_to_string(method()) :: String.t()

Converts a method to its wire form.

remove_header(msg, name)

@spec remove_header(t(), String.t() | atom()) :: t()

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
[]

to_method(method)

@spec to_method(String.t()) :: method()

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"

update_header(msg, op, name, value)

@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"}}