sdk/fidl/fuchsia.net.mdns/host_name_resolver.fidl

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.net.mdns;

using fuchsia.net;
using zx;

/// Discoverable protocol for resolving host names to IP addresses.
@available(added=9)
@discoverable
closed protocol HostNameResolver {
    /// Gets the addresses for the specified host.
    ///
    /// + request `host` the simple name of the host.
    /// + request `timeout` specifies how long the service should wait before giving up when
    ///   waiting for a response to a resolution query. In typical use, a timeout of two or three
    ///   seconds is recommended.
    /// + request `options` options to be applied to the resolution.
    /// - response `addresses` the addresses of the specified host, if it was found, an empty vector
    ///   if not.
    strict ResolveHostName(struct {
        host host_name;
        timeout zx.Duration;
        options HostNameResolutionOptions;
    }) -> (struct {
        addresses vector<HostAddress>:MAX_ADDRESSES;
    });
};

/// Options for `HostNameResolver.ResolveHostName`.
@available(added=9)
type HostNameResolutionOptions = table {
    /// The media (wired, wireless, both) of the interfaces on which the host name should be
    /// resolved. The default is both wired and wireless media.
    1: media Media;

    /// The IP versions (V4, V6, both) with which the host name should resolved. The default
    /// value is both IPv4 and IPv6.
    2: ip_versions IpVersions;

    // Whether to exclude the local host when resolving the host name. The default value is false.
    3: exclude_local bool;

    // Whether to exclude local proxies when resolving the host name. The default value is false.
    4: exclude_local_proxies bool;
};

/// An IPv4 or IPv6 host address with the id of the interface through which the address was
/// received.
@available(added=9)
type HostAddress = struct {
    /// IPv4 or IPv6 host address. In the case of the local host, this will be the address of the
    /// interface idenfied by `interface`. In the case of local proxy hosts, this value will be a
    /// non-link-local address.
    address fuchsia.net.IpAddress;

    /// Interface through which the address was received. In the case of the local host, this will
    /// be the interface id of the interface whose address is given by `address`. In the case of
    /// local proxy hosts, this value will be zero.
    interface fuchsia.net.InterfaceId;

    /// Time-to-live of the relevant A or AAAA resource. In the case of the local host or local
    /// proxy hosts, this value will be 2 minutes, the default A/AAAA TTL.
    ttl zx.Duration;
};