// Copyright 2019 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.

/// Protocols and types related to named places. Named places include cities,
/// countries, regions, etc. This specifically excludes protocols and types
/// related to latitude and longitude.
library fuchsia.location.namedplace;

/// Represents a regulatory region. These values should generally be chosen
/// from [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) codes. However,
/// some radios may support extensions beyond the set of ISO 3166-2 codes.
alias RegionCode = string:2;

/// The RegulatoryRegionConfigurator protocol provides mechanisms to
/// inform Location Services of the inputs that should be used to
/// determine the regulatory region whose rules should govern the
/// operation of radios on the system.
[Discoverable]
protocol RegulatoryRegionConfigurator {
    /// Sets the region.
    ///
    /// Clients should take care that their calls to this API arrive in a
    /// well-defined order. For example, when using Zircon channels as the
    /// underlying transport, the code below may not behave as intended.
    ///
    /// ```
    /// // DANGER: The service may receive "BB" before "AA".
    /// service1 = Open(RegulatoryRegionConfigurator);
    /// service1.SetRegion("AA");
    /// service1.Close();
    /// service2 = Open(RegulatoryRegionConfigurator);
    /// service2.SetRegion("BB");
    /// service2.Close();
    /// ```
    ///
    /// A client can avoid this problem by holding a single channel open to
    /// the service, for the lifetime of the client.
    ///
    /// ```
    /// // We use a single channel to ensure that calls arrive in a
    /// // well-defined order.
    /// service = Open(RegulatoryRegionConfigurator);
    /// service1.SetRegion("AA");
    /// service2.SetRegion("BB");
    /// ```
    ///
    /// + request `region` the current regulatory region.
    SetRegion(RegionCode region);
};

/// The RegulatoryRegionWatcher protocol provides the mechanism for
/// radio subsystems to learn the currently applicable regulatory
/// region, and to be notified when that value changes.
[Discoverable]
protocol RegulatoryRegionWatcher {
    /// This call is deprecated. Use GetRegionUpdate instead.
    ///
    /// Returns the new RegionCode, when it changes.
    ///
    /// Notes:
    /// * The first call returns immediately, if the region is already known.
    /// * The client is _not_ guaranteed to observe the effects of every call
    ///   to `SetRegion()`.
    /// * The client can, however, achieve _eventual_ consistency by always
    ///   issuing a new request when a request completes.
    /// * Clients should _not_ issue concurrent requests to this method.
    ///   * At present, concurrent requests
    ///     * May yield the same value, or different values.
    ///     * May complete out-of-order.
    ///   * In the future, concurrent requests will cause the channel to be
    ///     closed with `ZX_ERR_BAD_STATE`.
    ///
    /// - response `new_region` the current regulatory region.
    GetUpdate() -> (RegionCode new_region);

    /// Returns the new RegionCode, when it changes.
    ///
    /// Notes:
    /// * The first call returns immediately.
    /// * The client is _not_ guaranteed to observe the effects of every call
    ///   to `SetRegion()`.
    /// * The client can, however, achieve _eventual_ consistency by always
    ///   issuing a new request when a request completes.
    /// * Clients should _not_ issue concurrent requests to this method.
    ///   * At present, concurrent requests
    ///     * May yield the same value, or different values.
    ///     * May complete out-of-order.
    ///   * In the future, concurrent requests will cause the channel to be
    ///     closed with `ZX_ERR_BAD_STATE`.
    ///
    /// - response `new_region` the current regulatory region.
    GetRegionUpdate() -> (RegionCode? new_region);
};