Crate mdns_sd

source ·
Expand description

A small and safe library for Multicast DNS-SD (Service Discovery).

This library creates one new thread to run a mDNS daemon, and exposes its API that interacts with the daemon via a flume channel. The channel supports both recv() and recv_async().

For example, a client querying (browsing) a service behaves like this:

  Client       <channel>       mDNS daemon thread
    |                             | starts its run-loop.
    |       --- Browse -->        |
    |                             | detects services
    |                             | finds service instance A
    |       <-- Found A --        |
    |           ...               | resolves service A
    |       <-- Resolved A --     |
    |           ...               |

All commands in the public API are sent to the daemon using the unblocking try_send() so that the caller can use it with both sync and async code, with no dependency on any particular async runtimes.

§Usage

The user starts with creating a daemon by calling ServiceDaemon::new(). Then as a mDNS querier, the user would call browse to search for services, and/or as a mDNS responder, call register to publish (i.e. announce) its own service. And, the daemon type can be cloned and passed around between threads.

The user can also call resolve_hostname to resolve a hostname to IP addresses using mDNS, regardless if the host publishes a service name.

§Example: a client querying for a service type.

use mdns_sd::{ServiceDaemon, ServiceEvent};

// Create a daemon
let mdns = ServiceDaemon::new().expect("Failed to create daemon");

// Browse for a service type.
let service_type = "_mdns-sd-my-test._udp.local.";
let receiver = mdns.browse(service_type).expect("Failed to browse");

// Receive the browse events in sync or async. Here is
// an example of using a thread. Users can call `receiver.recv_async().await`
// if running in async environment.
std::thread::spawn(move || {
    while let Ok(event) = receiver.recv() {
        match event {
            ServiceEvent::ServiceResolved(info) => {
                println!("Resolved a new service: {}", info.get_fullname());
            }
            other_event => {
                println!("Received other event: {:?}", &other_event);
            }
        }
    }
});

// Gracefully shutdown the daemon.
std::thread::sleep(std::time::Duration::from_secs(1));
mdns.shutdown().unwrap();

§Example: a server publishs a service and responds to queries.

use mdns_sd::{ServiceDaemon, ServiceInfo};
use std::collections::HashMap;

// Create a daemon
let mdns = ServiceDaemon::new().expect("Failed to create daemon");

// Create a service info.
let service_type = "_mdns-sd-my-test._udp.local.";
let instance_name = "my_instance";
let ip = "192.168.1.12";
let host_name = "192.168.1.12.local.";
let port = 5200;
let properties = [("property_1", "test"), ("property_2", "1234")];

let my_service = ServiceInfo::new(
    service_type,
    instance_name,
    host_name,
    ip,
    port,
    &properties[..],
).unwrap();

// Register with the daemon, which publishes the service.
mdns.register(my_service).expect("Failed to register our service");

// Gracefully shutdown the daemon
std::thread::sleep(std::time::Duration::from_secs(1));
mdns.shutdown().unwrap();

§Limitations

This implementation is based on the following RFCs:

We focus on the common use cases at first, and currently have the following limitations:

  • Only support multicast, not unicast send/recv.
  • Only support 32-bit or bigger platforms, not 16-bit platforms.

§Use logging in tests and examples

Often times it is helpful to enable logging running tests or examples to examine the details. For tests and examples, we use env_logger as the logger and use test-log to enable logging for tests. For instance you can show all test logs using:

RUST_LOG=debug cargo test integration_success -- --nocapture

We also enabled the logging for the examples. For instance you can do:

RUST_LOG=debug cargo run --example query _printer._tcp

Structs§

Enums§

  • DaemonEvent
    Some notable events from the daemon besides ServiceEvent. These events are expected to happen infrequently.
  • DaemonStatus
    Status code for the service daemon.
  • Error
    A basic error type from this library.
  • HostnameResolutionEvent
    All possible events sent to the client from the daemon regarding host resolution.
  • IfKind
    Specify kinds of interfaces. It is used to enable or to disable interfaces in the daemon.
  • ServiceEvent
    All possible events sent to the client from the daemon regarding service discovery.
  • UnregisterStatus
    Response status code for the service unregister call.

Constants§

Traits§

Type Aliases§

  • Metrics
    The metrics is a HashMap of (name_key, i64_value). The main purpose is to help monitoring the mDNS packet traffic.
  • Result
    One and only Result type from this library crate.