// 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 zx;

/// Discoverable protocol for resolving service instances.
@discoverable
closed protocol ServiceInstanceResolver {
    /// Resolves a specific service instance by sending an SRV query and returns
    /// the endpoints, target and text records.
    ///
    /// + request `service` name of the type of service to be resolved. For example, cast uses
    ///   '_googlecast._tcp.'.
    /// + request `instance` name of the instance to be resolved. This is often a descriptive name
    ///   such as `Office Printer` or a name containing a large random number.
    /// + request `timeout` specifies how long the service should wait before giving up when
    ///   waiting for a response to a resolution query.
    /// + request `options` options to be applied to the resolution.
    ///
    /// A successful resolution will return target and at least one endpoint.
    /// Unsuccessful resolution occurs when either the service instance doesn't respond or
    /// there is no endpoint (IP & port).
    strict ResolveServiceInstance(struct {
        service service_name;
        instance instance_name;
        timeout zx.Duration;
        options ServiceInstanceResolutionOptions;
    }) -> (struct {
        instance ServiceInstance;
    });
};

/// Options for `ServiceInstanceResolver.ResolveServiceInstance`.
type ServiceInstanceResolutionOptions = table {
    /// The media (wired, wireless, both) of the interfaces on which the service instance should be
    /// resolved. The default is both wired and wireless media.
    1: media Media;

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

    // Whether to exclude services published locally when resolving the instance. The default
    // value is false.
    @available(added=9)
    3: exclude_local bool;

    // Whether to exclude services published via local proxies when resolving the instance. The
    // default value is false.
    @available(added=9)
    4: exclude_local_proxies bool;
};