| // 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; |
| }); |
| }; |