Struct ServiceDaemon

pub struct ServiceDaemon { /* private fields */ }

A daemon thread for mDNS

This struct provides a handle and an API to the daemon. It is cloneable.

Implementations

impl ServiceDaemon

pub fn new() -> Result<Self>

Creates a new daemon and spawns a thread to run the daemon.

The daemon (re)uses the default mDNS port 5353. To keep it simple, we don’t ask callers to set the port.

pub fn browse(&self, service_type: &str) -> Result<Receiver<ServiceEvent>>

Starts browsing for a specific service type.

service_type must end with a valid mDNS domain: ‘._tcp.local.’ or ‘._udp.local.’

Returns a channel Receiver to receive events about the service. The caller can call .recv_async().await on this receiver to handle events in an async environment or call .recv() in a sync environment.

When a new instance is found, the daemon automatically tries to resolve, i.e. finding more details, i.e. SRV records and TXT records.

pub fn stop_browse(&self, ty_domain: &str) -> Result<()>

Stops searching for a specific service type.

When an error is returned, the caller should retry only when the error is Error::Again, otherwise should log and move on.

pub fn resolve_hostname( &self, hostname: &str, timeout: Option<u64>, ) -> Result<Receiver<HostnameResolutionEvent>>

Starts querying for the ip addresses of a hostname.

Returns a channel Receiver to receive events about the hostname. The caller can call .recv_async().await on this receiver to handle events in an async environment or call .recv() in a sync environment.

The timeout is specified in milliseconds.

pub fn stop_resolve_hostname(&self, hostname: &str) -> Result<()>

Stops querying for the ip addresses of a hostname.

When an error is returned, the caller should retry only when the error is Error::Again, otherwise should log and move on.

pub fn register(&self, service_info: ServiceInfo) -> Result<()>

Registers a service provided by this host.

If service_info has no addresses yet and its addr_auto is enabled, this method will automatically fill in addresses from the host.

To re-announce a service with an updated service_info, just call this register function again. No need to call unregister first.

pub fn unregister(&self, fullname: &str) -> Result<Receiver<UnregisterStatus>>

Unregisters a service. This is a graceful shutdown of a service.

Returns a channel receiver that is used to receive the status code of the unregister.

When an error is returned, the caller should retry only when the error is Error::Again, otherwise should log and move on.

pub fn monitor(&self) -> Result<Receiver<DaemonEvent>>

Starts to monitor events from the daemon.

Returns a channel Receiver of DaemonEvent.

pub fn shutdown(&self) -> Result<Receiver<DaemonStatus>>

Shuts down the daemon thread and returns a channel to receive the status.

When an error is returned, the caller should retry only when the error is Error::Again, otherwise should log and move on.

pub fn status(&self) -> Result<Receiver<DaemonStatus>>

Returns the status of the daemon.

When an error is returned, the caller should retry only when the error is Error::Again, otherwise should consider the daemon stopped working and move on.

pub fn get_metrics(&self) -> Result<Receiver<Metrics>>

Returns a channel receiver for the metrics, e.g. input/output counters.

The metrics returned is a snapshot. Hence the caller should call this method repeatedly if they want to monitor the metrics continuously.

pub fn set_service_name_len_max(&self, len_max: u8) -> Result<()>

Change the max length allowed for a service name.

As RFC 6763 defines a length max for a service name, a user should not call this method unless they have to. See SERVICE_NAME_LEN_MAX_DEFAULT.

len_max is capped at an internal limit, which is currently 30.

pub fn set_ip_check_interval(&self, interval_in_secs: u32) -> Result<()>

Change the interval for checking IP changes automatically.

Setting the interval to 0 disables the IP check.

See IP_CHECK_INTERVAL_IN_SECS_DEFAULT for the default interval.

pub fn get_ip_check_interval(&self) -> Result<u32>

Get the current interval in seconds for checking IP changes automatically.

pub fn enable_interface(&self, if_kind: impl IntoIfKindVec) -> Result<()>

Include interfaces that match if_kind for this service daemon.

For example:

    daemon.enable_interface("en0")?;

pub fn disable_interface(&self, if_kind: impl IntoIfKindVec) -> Result<()>

Ignore/exclude interfaces that match if_kind for this daemon.

For example:

    daemon.disable_interface(IfKind::IPv6)?;

pub fn set_multicast_loop_v4(&self, on: bool) -> Result<()>

Enable or disable the loopback for locally sent multicast packets in IPv4.

By default, multicast loop is enabled for IPv4. When disabled, a querier will not receive announcements from a responder on the same host.

Reference: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

“The Winsock version of the IP_MULTICAST_LOOP option is semantically different than the UNIX version of the IP_MULTICAST_LOOP option:

In Winsock, the IP_MULTICAST_LOOP option applies only to the receive path. In the UNIX version, the IP_MULTICAST_LOOP option applies to the send path.“

Which means, in order NOT to receive localhost announcements, you want to call this API on the querier side on Windows, but on the responder side on Unix.

pub fn set_multicast_loop_v6(&self, on: bool) -> Result<()>

Enable or disable the loopback for locally sent multicast packets in IPv6.

By default, multicast loop is enabled for IPv6. When disabled, a querier will not receive announcements from a responder on the same host.

Reference: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

“The Winsock version of the IP_MULTICAST_LOOP option is semantically different than the UNIX version of the IP_MULTICAST_LOOP option:

In Winsock, the IP_MULTICAST_LOOP option applies only to the receive path. In the UNIX version, the IP_MULTICAST_LOOP option applies to the send path.“

Which means, in order NOT to receive localhost announcements, you want to call this API on the querier side on Windows, but on the responder side on Unix.

pub fn verify(&self, instance_fullname: String, timeout: Duration) -> Result<()>

Proactively confirms whether a service instance still valid.

This call will issue queries for a service instance’s SRV record and Address records.

For timeout, most users should use VERIFY_TIMEOUT_DEFAULT unless there is a reason not to follow RFC.

If no response is received within timeout, the current resource records will be flushed, and if needed, ServiceRemoved event will be sent to active queriers.

Reference: RFC 6762

Trait Implementations

impl Clone for ServiceDaemon

fn clone(&self) -> ServiceDaemon

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.