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

Globally Routable User Agent URIs (RFC 5627). Equivalent to NkSIP's
`nksip_gruu`.

```
defmodule MyRegistrar do
  use Malla.Service,
    plugins: [Caracola.Registrar, Caracola.Gruu],
    sip: [listen: "sip:all:5060"]
end
```

The plugin adds `gruu` to the Supported header. With it:

  * As UA, Contacts get the `+sip.instance` of the service, and the GRUUs
    received in the responses to REGISTER are available with
    `get_gruu_pub/1` and `get_gruu_temp/1`.
  * As registrar (with `Caracola.Registrar`), registrations with a
    `+sip.instance` from UAs supporting GRUU get a public GRUU (the AOR
    with a `gr` parameter identifying the instance) and a temporary one
    (an encrypted user with `gr`), in the `pub-gruu` and `temp-gruu`
    Contact parameters. A new temporary GRUU is generated in each
    registration; all of them are invalidated when the Call-ID changes.
    `registrar_find/2` finds the contacts of a URI, which can be a GRUU.

# `get_gruu_pub`

```elixir
@spec get_gruu_pub(module()) :: {:ok, Caracola.URI.t()} | :undefined
```

The public GRUU received in the last registration.

# `get_gruu_temp`

```elixir
@spec get_gruu_temp(module()) :: {:ok, Caracola.URI.t()} | :undefined
```

The temporary GRUU received in the last registration.

# `registrar_find`

```elixir
@spec registrar_find(module(), Caracola.URI.t()) :: [Caracola.URI.t()]
```

Returns the registered contacts of a URI: for a public GRUU, those of its
instance; for a temporary GRUU, those of its instance if it is still
valid; otherwise, those of the AOR (see `Caracola.Registrar.find/2`).

---

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