| // Copyright 2017 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.mdns; |
| |
| using fuchsia.netstack; |
| using zx; |
| |
| /// Primary mDNS service interface. |
| /// |
| /// In mDNS, all strings are UTF-8 encoded and limited to 255 bytes, not |
| /// including null termination. Host, service and instance names consist of |
| /// labels separated by '.'. Labels are limited to 63 bytes not including the |
| /// separator. |
| [Discoverable] |
| protocol Controller { |
| /// Gets the addresses for the specified host name. `host_name` may not end |
| /// in a '.'. `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. |
| /// |
| /// A successful resolution may return one or both addresses. An |
| /// unsuccessful resolution is indicated when both addresses are null. |
| ResolveHostName(string:255 host_name, zx.duration timeout) |
| -> (fuchsia.netstack.SocketAddress? v4_address, |
| fuchsia.netstack.SocketAddress? v6_address); |
| |
| /// Subscribes to a service. The subscription lasts until `subscriber` is |
| /// unbound. `service_name` must end in '._tcp.' or '._udp.'. |
| SubscribeToService(string:255 service_name, ServiceSubscriber subscriber); |
| |
| /// Publishes a service instance. `service_name` must end in '._tcp.' or |
| /// '._udp.'. `instance_name` must not end in a '.'. `responder` is |
| /// consulted via its `GetPublication` method for initial announcements and |
| /// to answer queries. The service is published until the `responder` |
| /// channel closes. In addition to announcements and queries for the service |
| /// type, all queries for subtypes are answered subject to filtering through |
| /// the `Responder`. `perform_probe` indicates whether a probe for a |
| /// conflicting instance should be performed before publishing the instance. |
| /// This value should be `true` unless the instance name is known to be |
| /// unique. |
| PublishServiceInstance(string:255 service_name, |
| string:255 instance_name, |
| bool perform_probe, |
| Responder responder) -> (Result result); |
| |
| /// Publishes a service instance available at the specified port. The |
| /// service instance is published until it is unpublished via |
| /// `UnpublishServiceInstance`. `service_name` must end in '._tcp.' or |
| /// '._udp.'. `instance_name` must not end in a '.'. `port` is host-endian. |
| /// `text` contains metadata strings that describe the instance. |
| /// `perform_probe` indicates whether a probe for a conflicting instance |
| /// should be performed before publishing the instance. This value should |
| /// be `true` unless the instance name is known to be unique. |
| // TODO(NET-2188): Remove this after implementing config files. |
| DEPRECATEDPublishServiceInstance(string:255 service_name, |
| string:255 instance_name, |
| uint16 port, |
| vector<string:255> text, |
| bool perform_probe) -> (Result result); |
| |
| /// Ends publication started with `PublishServiceInstance`. `service_name` |
| /// must end in '._tcp.' or '._udp.'. `instance_name` must not end in a '.'. |
| // TODO(NET-2188): Remove this after implementing config files. |
| DEPRECATEDUnpublishServiceInstance(string:255 service_name, |
| string:255 instance_name); |
| |
| /// Specifies whether mDNS traffic should be logged. |
| // TODO(NET-2189): Move to /hub. |
| DEPRECATEDSetVerbose(bool value); |
| }; |
| |
| /// Result values for instance publishing. |
| // TODO(dalesat): Rename 'Error' and use error syntax when generally available. |
| enum Result : int32 { |
| /// Operation succeeded. |
| OK = 0; |
| |
| /// The specified service name is invalid. |
| INVALID_SERVICE_NAME = -1; |
| |
| /// The specified instance name is invalid. |
| INVALID_INSTANCE_NAME = -2; |
| |
| /// The specified service instance is already being published by this |
| /// mDNS implementation. |
| ALREADY_PUBLISHED_LOCALLY = -3; |
| |
| /// The specified service instance is already being published by another |
| /// host on the subnet. This result occurs when an initial probe discovers |
| /// a conflicting instance. |
| ALREADY_PUBLISHED_ON_SUBNET = -4; |
| }; |
| |
| /// Client-implemented interface for subscribers. Method replies are used to |
| /// throttle traffic. The service won't necessarily wait for a reply before |
| /// calling another method. |
| protocol ServiceSubscriber { |
| /// Notifies the subscriber that a service instance has been discovered. |
| InstanceDiscovered(ServiceInstance instance) -> (); |
| |
| /// Notifies the subscriber that addresses or text for a known service |
| /// instance have changed. |
| InstanceChanged(ServiceInstance instance) -> (); |
| |
| /// Notifies the subscriber that a known service instance has been lost. |
| InstanceLost(string:255 service_name, string:255 instance_name) -> (); |
| }; |
| |
| /// Describes a service instance. |
| struct ServiceInstance { |
| string:255 service_name; |
| string:255 instance_name; |
| fuchsia.netstack.SocketAddress? v4_address; |
| fuchsia.netstack.SocketAddress? v6_address; |
| vector<string:255> text; |
| }; |
| |
| /// Client-supplied responder interface. |
| protocol Responder { |
| /// Provides instance information for initial announcements and query |
| /// responses relating to the service instance specified in |
| /// `Controller.AddResponder`. `query` indicates whether data is requested |
| /// for an initial announcement (false) or in response to a query (true). |
| /// If the publication relates to a subtype of the service, `subtype` |
| /// contains the subtype, otherwise it is null. If `publication` is null, |
| /// no announcement or response is transmitted. Strings in `text` are |
| /// transmitted in the TXT record. |
| GetPublication(bool query, string:255? subtype) |
| -> (Publication? publication); |
| |
| /// Sets the subtypes for the service instance. The specified subtypes will |
| /// be announced subject to filtering through the `Responder`. The initial |
| /// subtype collection is empty. |
| -> OnSubtypesChanged(vector<string:255> subtypes); |
| |
| /// Initiates reannouncement of the service instance due to a change in the |
| /// instance's port number or text strings. All announcements are filtered |
| /// through `GetPublication`, which replies with the new port and text |
| /// values. |
| -> OnPublicationChanged(); |
| }; |
| |
| /// Describes an initial instance announcement or query response. `port` is |
| /// host-endian. In typical use, the default TTL values should be used. TTL |
| /// values are rounded down to the nearest second. TTL values less than one |
| /// second are not permitted and will result in the `Responder` channel being |
| /// closed. |
| struct Publication { |
| uint16 port; |
| vector<string:255> text; |
| zx.duration ptr_ttl = 4500000000000; // default 75 minutes |
| zx.duration srv_ttl = 120000000000; // default 2 minutes |
| zx.duration txt_ttl = 4500000000000; // default 75 minutes |
| }; |