# `Caracola.Message`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/message.ex#L1)

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.

# `class`

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

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

# `method`

```elixir
@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`

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

# `get_headers`

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

Gets all values of a non pre-parsed header.

# `header`

```elixir
@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`

```elixir
@spec method(t()) :: method()
```

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

# `method_to_string`

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

Converts a method to its wire form.

# `remove_header`

```elixir
@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`

```elixir
@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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
