# `Meshcore.Commands.Contact`
[🔗](https://github.com/nyannus/meshcore_ex/blob/v0.1.0/lib/meshcore/commands/contact.ex#L1)

Commands for managing the device's contact list.

A *contact* is a map with the keys the device reports in `:contacts` and
`:next_contact` events: `:public_key` (hex), `:type`, `:flags`,
`:out_path_len`, `:out_path_hash_mode`, `:out_path` (hex), `:adv_name`,
`:last_advert`, `:adv_lat`, `:adv_lon`, `:lastmod`.

# `contact`

```elixir
@type contact() :: map()
```

# `mc`

```elixir
@type mc() :: GenServer.server()
```

# `result`

```elixir
@type result() :: {:ok, Meshcore.Event.t()} | {:error, Meshcore.Event.t()}
```

# `add_contact`

```elixir
@spec add_contact(mc(), contact()) :: result()
```

Alias for `update_contact/3` with no changes: adds `contact` to the device.

# `change_contact_flags`

```elixir
@spec change_contact_flags(mc(), contact(), non_neg_integer()) :: result()
```

Changes a contact's flags.

# `change_contact_path`

```elixir
@spec change_contact_path(mc(), contact(), String.t(), keyword()) :: result()
```

Changes a contact's out path. See `update_contact/3` for the path format.

# `export_contact`

```elixir
@spec export_contact(mc(), Meshcore.Util.destination() | nil) :: result()
```

Exports a contact (or, with `nil`, this node) as a `meshcore://` URI
(`:contact_uri`).

# `get_advert_path`

```elixir
@spec get_advert_path(mc(), Meshcore.Util.destination()) :: result()
```

Reads the last known advert path of a contact (`:advert_path`).

# `get_autoadd_config`

```elixir
@spec get_autoadd_config(mc()) :: result()
```

Reads the auto-add configuration (`:autoadd_config`).

# `get_contact_by_key`

```elixir
@spec get_contact_by_key(mc(), binary()) :: result()
```

Fetches a single contact by its 32 byte public key (`:next_contact`), or an
error if it is unknown.

# `get_contacts`

```elixir
@spec get_contacts(mc(), keyword()) :: result()
```

Fetches the contact list and waits for the `:contacts` event, whose payload
is a map `public_key_hex => contact`.

The timeout restarts every time another contact arrives, so large lists don't
time out. Options: `:lastmod` (only contacts changed since, default `0`),
`:timeout` (ms of silence tolerated, default `5_000`).

# `get_contacts_async`

```elixir
@spec get_contacts_async(mc(), non_neg_integer()) :: result()
```

Asks for the contact list without waiting (the `:contacts` event follows).

# `import_contact`

```elixir
@spec import_contact(mc(), binary()) :: result()
```

Imports a contact card (raw bytes, as found after `meshcore://`).

# `remove_contact`

```elixir
@spec remove_contact(mc(), Meshcore.Util.destination()) :: result()
```

Removes a contact.

# `reset_path`

```elixir
@spec reset_path(mc(), Meshcore.Util.destination()) :: result()
```

Resets the stored path of a contact (it will be reached by flooding).

# `set_autoadd_config`

```elixir
@spec set_autoadd_config(mc(), 0..255) :: result()
```

Sets the auto-add configuration bit field.

# `share_contact`

```elixir
@spec share_contact(mc(), Meshcore.Util.destination()) :: result()
```

Shares a contact with the mesh.

# `update_contact`

```elixir
@spec update_contact(mc(), contact(), keyword()) :: result()
```

Writes a contact to the device (add or update).

Options:

  * `:path` – new out path as a hex string, optionally suffixed with `":" <> mode`
    (`"aabbcc:1"`); `""` makes it a zero-hop path
  * `:path_hash_mode` – hash mode for `:path`; when neither it nor a suffix is
    given the device's current mode is queried
  * `:flags` – new contact flags

The stored copy of the contact in the client is updated on success.

---

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