| // 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.net.mdns; |
| |
| using fuchsia.net; |
| using zx; |
| |
| // TODO(dalesat): Soft transition in progress. |
| // 1) Add the following definitions: |
| // Subscriber.SubscribeToService2 |
| // ServiceSubscriber2 |
| // Publisher.PublishServiceInstance2 |
| // PublicationResponder2 (completed) |
| // 2) Transition all clients to the '2' versions. (completed) |
| // 3) Change the originals to be identical to the '2' versions. (completed) |
| // 3.1) Implement new features under the original names. (completed) |
| // 4) Transition all clients to the original names. |
| // 5) Remove the '2' versions. |
| |
| // TODO(fxbug.dev/7904): Make these alias comments doc comments. |
| |
| /// Identifies a host. Host names consist of one or more labels separated by |
| /// '.'s. A host name must not end with a '.'. Labels must each be 63 characters |
| /// or less (not including the separator) and are UTF-8-encoded. A complete host |
| /// name, including separators, must be 255 characters or less. |
| alias host_name = string:255; |
| |
| /// Identifies a (type of) service being published. Service names consist of |
| /// two labels, both terminated with a '.'. The first label must start with an |
| /// underscore and be 16 characters or less, including the underscore. The |
| /// second label must be either '_tcp' or '_udp'. Labels do not contain '.'s. |
| /// With underscores and terminators, that makes for a maximum of 22 characters. |
| /// Service names are UTF-8-encoded. |
| alias service_name = string:22; |
| |
| /// Identifies a specific instance of a service being published. Instance names |
| /// consist of a single label, which is at most 63 characters long and which |
| /// contains no '.'s. Instance names are UTF-8-encoded. |
| alias instance_name = string:63; |
| |
| /// Identifies a subtype of a service. Subtype names consist of a single label, |
| /// which is at most 63 characters long and which contains no '.'s. Subtype |
| /// names are UTF-8-encoded. |
| alias subtype_name = string:63; |
| |
| /// Provides description relating to a service instance. In typical use, TXT |
| /// strings consist of a key and value separated by '='. TXT strings must be |
| /// at most 255 characters long and are UTF-8-encoded. |
| alias txt_string = string:255; |
| |
| /// Discoverable protocol for resolving host names to IP addresses. |
| @discoverable |
| protocol Resolver { |
| /// Gets the addresses for the specified host. `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(struct { |
| host host_name; |
| timeout zx.duration; |
| }) -> (struct { |
| v4_address box<fuchsia.net.Ipv4Address>; |
| v6_address box<fuchsia.net.Ipv6Address>; |
| }); |
| }; |
| |
| /// Discoverable protocol for finding service instances. |
| @discoverable |
| protocol Subscriber { |
| /// Subscribes to a service. The subscription lasts until `subscriber` is |
| /// unbound. |
| @transitional |
| SubscribeToService(resource struct { |
| service service_name; |
| subscriber client_end:ServiceSubscriber; |
| }); |
| |
| /// Subscribes to a service. The subscription lasts until `subscriber` is |
| /// unbound. |
| @transitional |
| @deprecated |
| SubscribeToService2(resource struct { |
| service service_name; |
| subscriber client_end:ServiceSubscriber2; |
| }); |
| }; |
| |
| /// Discoverable protocol for publishing service instances. |
| @discoverable |
| protocol Publisher { |
| /// Publishes a service instance. `publication_responder` is consulted via its |
| /// `OnPublication` method for initial announcements and to answer queries. |
| /// The service is published until the `publication_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. |
| /// |
| /// If a service with the same service and instance names is already published, the |
| /// old publication will be terminated, and the responder channel for the old |
| /// publication will be closed. |
| @transitional |
| PublishServiceInstance(resource struct { |
| service service_name; |
| instance instance_name; |
| media Media; |
| perform_probe bool; |
| publication_responder client_end:PublicationResponder; |
| }) -> (struct {}) error Error; |
| |
| /// Publishes a service instance. `publication_responder` is consulted via its |
| /// `OnPublication` method for initial announcements and to answer queries. |
| /// The service is published until the `publication_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. |
| /// |
| /// If a service with the same service and instance names is already published, the |
| /// old publication will be terminated, and the responder channel for the old |
| /// publication will be closed. |
| @transitional |
| @deprecated |
| PublishServiceInstance2(resource struct { |
| service service_name; |
| instance instance_name; |
| perform_probe bool; |
| publication_responder client_end:PublicationResponder2; |
| }) -> (struct {}) error Error; |
| }; |
| |
| /// Specifies network media on which a service instance should be published. |
| type Media = strict bits : uint32 { |
| /// Specifies wired interfaces. |
| WIRED = 1; |
| |
| /// Specifies wireless interfaces. |
| WIRELESS = 2; |
| }; |
| |
| /// Error values for instance publishing. |
| type Error = strict enum : int32 { |
| /// 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 another |
| /// host on the subnet. This result occurs when an initial probe discovers |
| /// a conflicting instance. |
| ALREADY_PUBLISHED_ON_SUBNET = 4; |
| |
| // The specified `Media` value is invalid. |
| INVALID_MEDIA = 5; |
| }; |
| |
| /// 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. |
| OnInstanceDiscovered(struct { |
| instance ServiceInstance; |
| }) -> (); |
| |
| /// Notifies the subscriber that addresses or text for a known service |
| /// instance have changed. |
| OnInstanceChanged(struct { |
| instance ServiceInstance; |
| }) -> (); |
| |
| /// Notifies the subscriber that a known service instance has been lost. |
| OnInstanceLost(struct { |
| service service_name; |
| instance instance_name; |
| }) -> (); |
| |
| /// Notifies the subscriber that a PTR query has been sent. |
| OnQuery(struct { |
| resource_type ResourceType; |
| }) -> (); |
| }; |
| |
| /// 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 ServiceSubscriber2 { |
| /// Notifies the subscriber that a service instance has been discovered. |
| OnInstanceDiscovered(struct { |
| instance ServiceInstance2; |
| }) -> (); |
| |
| /// Notifies the subscriber that addresses or text for a known service |
| /// instance have changed. |
| OnInstanceChanged(struct { |
| instance ServiceInstance2; |
| }) -> (); |
| |
| /// Notifies the subscriber that a known service instance has been lost. |
| OnInstanceLost(struct { |
| service service_name; |
| instance instance_name; |
| }) -> (); |
| |
| /// Notifies the subscriber that a PTR query has been sent. |
| OnQuery(struct { |
| resource_type ResourceType; |
| }) -> (); |
| }; |
| |
| /// DNS resource types. |
| type ResourceType = strict enum { |
| /// Domain name pointer. |
| PTR = 12; |
| /// Any (wildcard) type. |
| ANY = 255; |
| }; |
| |
| /// Describes a service instance. |
| type ServiceInstance = table { |
| /// The name of the service. |
| 1: service service_name; |
| |
| /// The name of the service instance. |
| 2: instance instance_name; |
| |
| /// IPv4 socket address for the service. May be unset. |
| 3: ipv4_endpoint fuchsia.net.Ipv4SocketAddress; |
| |
| /// IPv6 socket address for the service. May be unset. |
| 4: ipv6_endpoint fuchsia.net.Ipv6SocketAddress; |
| |
| /// Text strings describing the instance. |
| 5: text vector<txt_string>:MAX_TEXT_STRINGS; |
| |
| /// The priority of the SRV resource record for this publication. See |
| /// [RFC6763](https://tools.ietf.org/html/rfc6763) for details. |
| 6: srv_priority uint16; |
| |
| /// The weight of the SRV resource record for this publication. See |
| /// [RFC6763](https://tools.ietf.org/html/rfc6763) for details. |
| 7: srv_weight uint16; |
| }; |
| |
| /// Describes a service instance. |
| type ServiceInstance2 = table { |
| /// The name of the service. |
| 1: service service_name; |
| |
| /// The name of the service instance. |
| 2: instance instance_name; |
| |
| /// IPv4 socket address for the service. May be unset. |
| 3: ipv4_endpoint fuchsia.net.Ipv4SocketAddress; |
| |
| /// IPv6 socket address for the service. May be unset. |
| 4: ipv6_endpoint fuchsia.net.Ipv6SocketAddress; |
| |
| /// Text strings describing the instance. |
| 5: text vector<txt_string>:MAX_TEXT_STRINGS; |
| |
| /// The priority of the SRV resource record for this publication. See |
| /// [RFC6763](https://tools.ietf.org/html/rfc6763) for details. |
| 6: srv_priority uint16; |
| |
| /// The weight of the SRV resource record for this publication. See |
| /// [RFC6763](https://tools.ietf.org/html/rfc6763) for details. |
| 7: srv_weight uint16; |
| }; |
| |
| /// Client-supplied publication responder interface. |
| protocol PublicationResponder { |
| /// Provides instance information for initial announcements and query |
| /// responses relating to the service instance specified in |
| /// `Publisher.PublishServiceInstance`. 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. |
| OnPublication(struct { |
| publication_cause PublicationCause; |
| subtype subtype_name:optional; |
| source_addresses vector<fuchsia.net.IpAddress>:64; |
| }) -> (struct { |
| publication box<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. |
| -> SetSubtypes(struct { |
| subtypes vector<subtype_name>:MAX_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 `OnPublication`, which replies with the new port and text |
| /// values. |
| -> Reannounce(); |
| }; |
| |
| /// Describes the cause of a publication. |
| type PublicationCause = strict enum : int32 { |
| /// Indicates the publication is part of an initial announcement. |
| ANNOUNCEMENT = 1; |
| |
| /// Indicates the publication is in response to a question that requests a |
| /// multicast response. |
| QUERY_MULTICAST_RESPONSE = 2; |
| |
| /// Indicates the publication is in response to a question that requests a |
| /// unicast response. |
| QUERY_UNICAST_RESPONSE = 3; |
| }; |
| |
| /// Client-supplied publication responder interface. |
| protocol PublicationResponder2 { |
| /// Provides instance information for initial announcements and query |
| /// responses relating to the service instance specified in |
| /// `Publisher.PublishServiceInstance`. `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. |
| OnPublication(struct { |
| query bool; |
| subtype subtype_name:optional; |
| source_addresses vector<fuchsia.net.IpAddress>:64; |
| }) -> (struct { |
| publication box<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. |
| -> SetSubtypes(struct { |
| subtypes vector<subtype_name>:MAX_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 `OnPublication`, which replies with the new port and text |
| /// values. |
| -> Reannounce(); |
| }; |
| |
| /// Describes an initial instance announcement or query response. In typical |
| /// use, the default SRV priority, SRV weight and 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 `PublicationResponder` |
| /// channel being closed. |
| type Publication = struct { |
| /// The port at which the service instance is addressable. |
| port uint16; |
| |
| /// Text strings describing the instance. |
| text vector<txt_string>:MAX_TEXT_STRINGS; |
| |
| /// The priority of the SRV resource record for this publication. See |
| /// [RFC6763](https://tools.ietf.org/html/rfc6763) for details. |
| srv_priority uint16 = DEFAULT_SRV_PRIORITY; |
| |
| /// The weight of the SRV resource record for this publication. See |
| /// [RFC6763](https://tools.ietf.org/html/rfc6763) for details. |
| srv_weight uint16 = DEFAULT_SRV_WEIGHT; |
| |
| /// Time-to-live for PTR resource records. |
| ptr_ttl zx.duration = DEFAULT_PTR_TTL; |
| |
| /// Time-to-live for SRV resource records. |
| srv_ttl zx.duration = DEFAULT_SRV_TTL; |
| |
| /// Time-to-live for TXT resource records. |
| txt_ttl zx.duration = DEFAULT_TXT_TTL; |
| }; |
| |
| const DEFAULT_SRV_PRIORITY uint16 = 0; |
| const DEFAULT_SRV_WEIGHT uint16 = 0; |
| const DEFAULT_PTR_TTL zx.duration = 120000000000; // 2 minutes |
| const DEFAULT_SRV_TTL zx.duration = 120000000000; // 2 minutes |
| const DEFAULT_TXT_TTL zx.duration = 4500000000000; // 75 minutes |
| const MAX_TEXT_STRINGS uint32 = 256; |
| const MAX_SUBTYPES uint32 = 256; |