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

SIP URI, optionally in name-addr form (`"Display" <sip:...>;params`).

Port of NkLIB's `nklib_parse_uri` and `nklib_unparse`. The struct keeps
both URI-level components (inside `<>`) and header-level ones (outside):

  * `params` / `headers`: URI parameters and headers (`;lr`, `?Route=...`).
  * `ext_params` / `ext_headers`: header parameters after the URI (`;tag=...`).
    When a URI is written without `<>` (addr-spec form), all its parameters
    and headers are header-level ones, as RFC 3261 §20 requires.

Parameters are `{name, value}` tuples, with `nil` value for flags. Names keep
their original case; quoted values keep their quotes. URI header names are
lowercased.

`port` and `path` are `nil` when absent. `disp` is the raw display name
(quotes included), or `nil`.

# `param`

```elixir
@type param() :: {String.t(), String.t() | nil}
```

A parameter: name and value (`nil` for flags).

# `scheme`

```elixir
@type scheme() :: :sip | :sips | :tel | String.t()
```

A URI scheme.

# `t`

```elixir
@type t() :: %Caracola.URI{
  disp: String.t() | nil,
  domain: String.t(),
  ext_headers: [param()],
  ext_params: [param()],
  headers: [param()],
  params: [param()],
  pass: String.t() | nil,
  path: String.t() | nil,
  port: :inet.port_number() | nil,
  scheme: scheme(),
  user: String.t() | nil
}
```

A SIP URI, with its parameters and headers.

# `encode`

```elixir
@spec encode(t() | [t()]) :: iodata()
```

Serializes the URI in name-addr form (always with `<>`), as used in headers.

# `encode_ruri`

```elixir
@spec encode_ruri(t()) :: iodata()
```

Serializes the URI as a Request-URI: no `<>`, display name, path, headers
or header-level parameters.

# `get_ext_param`

```elixir
@spec get_ext_param(t(), String.t()) :: {:ok, String.t() | nil} | :error
```

Gets a header-level parameter (outside `<>`), case-insensitively.

# `get_param`

```elixir
@spec get_param(t(), String.t()) :: {:ok, String.t() | nil} | :error
```

Gets a URI parameter (inside `<>`), case-insensitively.

# `parse`

```elixir
@spec parse(binary() | [binary()]) :: {:ok, [t()]} | :error
```

Parses a comma-separated list of URIs, or a list of such binaries.

    iex> {:ok, [uri]} = Caracola.URI.parse("\"Bob\" <sip:bob@example.com:5070;transport=tcp>;tag=1")
    iex> {uri.disp, uri.user, uri.domain, uri.port, uri.params, uri.ext_params}
    {"\"Bob\"", "bob", "example.com", 5070, [{"transport", "tcp"}], [{"tag", "1"}]}

# `parse_one`

```elixir
@spec parse_one(binary()) :: {:ok, t()} | :error
```

Parses a single URI. Fails if there is none or more than one.

---

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