blob: b5a69d64decfce6dc3dff3a3672d7b9b52333aec [file] [log] [blame]
// 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.
@available(added=7)
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(struct {
region RegionCode;
});
};
/// 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() -> (struct {
new_region RegionCode;
});
/// 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() -> (struct {
new_region RegionCode:optional;
});
};