# `MdnsLite`
[🔗](https://github.com/nerves-networking/mdns_lite/blob/v0.9.1/lib/mdns_lite.ex#L7)

MdnsLite is a simple, limited, no frills mDNS implementation

Advertising hostnames and services is generally done using the application
config.  See `MdnsLite.Options` for documentation.

To change the advertised hostnames or services at runtime, see `set_host/1`,
`add_mdns_service/1` and `remove_mdns_service/1`.

MdnsLite's mDNS record tables and caches can be inspected using
`MdnsLite.Info` if you're having trouble.

Finally, check out the MdnsLite `README.md` for more information.

# `instance_name`

```elixir
@type instance_name() :: String.t() | :unspecified
```

A user-visible name for a service advertisement

# `service`

```elixir
@type service() :: %{
  :id => service_id(),
  :instance_name => instance_name(),
  :port => 1..65535,
  optional(:txt_payload) =>
    %{required(atom()) => String.t()} | [String.t()] | String.t(),
  optional(:priority) => 0..255,
  optional(:protocol) => String.t(),
  optional(:transport) => String.t(),
  optional(:type) => String.t(),
  optional(:weight) => 0..255
}
```

mDNS service description

Keys include:

* `:id` - an atom for referring to this service (only required if you want to
  reference the service at runtime)
* `:port` - the TCP/UDP port number for the service (required)
* `:transport` - the transport protocol. E.g., `"tcp"` (specify this and
  `:protocol`, or `:type`) * `:protocol` - the application protocol. E.g.,
  `"ssh"` (specify this and `:transport`, or `:type`)
* `:type` - the transport/protocol to advertize. E.g., `"_ssh._tcp"` (only
  needed if `:protocol` and `:transport` aren't specified)
* `:weight` - the service weight. Defaults to `0`. (optional)
* `:priority` - the service priority. Defaults to `0`. (optional)
* `:txt_payload` - a map of key/value pairs that will be converted to a
  list "key=value" strings or the raw list of strings to advertise. As
  a convenience, if a bare string is passed, it's wrapped in a list.

Example:

```
%{id: :my_ssh, port: 22, protocol: "ssh", transport: "tcp"}
```

# `service_id`

```elixir
@type service_id() :: atom() | binary()
```

A user-specified ID for referring to a service

Atoms are recommended, but binaries are still supported since they were used
in the past.

# `add_mdns_service`

```elixir
@spec add_mdns_service(service()) :: :ok
```

Start advertising a service

Services can be added at compile-time via the `:services` key in the `mdns_lite`
application environment or they can be added at runtime using this function.
See the `service` type for information on what's needed.

Example:

```elixir
iex> service = %{
    id: :my_web_server,
    protocol: "http",
    transport: "tcp",
    port: 80
  }
iex> MdnsLite.add_mdns_service(service)
:ok
```

# `gethostbyname`

```elixir
@spec gethostbyname(String.t(), non_neg_integer()) ::
  {:ok, :inet.ip_address()} | {:error, any()}
```

Lookup a hostname using mDNS

The hostname should be a .local name since the query only goes out via mDNS.
On success, an IP address is returned.

# `remove_mdns_service`

```elixir
@spec remove_mdns_service(service_id()) :: :ok
```

Stop advertising a service

Example:

```elixir
iex> MdnsLite.remove_mdns_service(:my_ssh)
:ok
```

# `set_hosts`

```elixir
@spec set_hosts([:hostname | String.t()]) :: :ok
```

Set the list of host names

This replaces the list of hostnames that MdnsLite will respond to. The first
hostname in the list is special. Service advertisements will use it. The
remainder are aliases.

Hostnames should not have the ".local" extension. MdnsLite will add it.

To specify the hostname returned by `:inet.gethostname/0`, use `:hostname`.

To make MdnsLite respond to queries for "<hostname>.local" and
"nerves.local", run this:

```elixir
iex> MdnsLite.set_hosts([:hostname, "nerves"])
:ok
```

# `set_instance_name`

```elixir
@spec set_instance_name(instance_name()) :: :ok
```

Updates the advertised instance name for service records

To specify the first hostname specified in `hosts`, use `:unspecified`

---

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