<br />

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.
Added: 7

## **PROTOCOLS**

## RegulatoryRegionConfigurator

*Defined in [fuchsia.location.namedplace/namedplace.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.location.namedplace/namedplace.fidl;l=20)*

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.

<br />

### SetRegion

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);
    service.SetRegion("AA");
    service.SetRegion("BB");

- request `region` the current regulatory region.

#### Request

| Name | Type |
|---|---|
| `region` | `https://fuchsia.dev/reference/fidl/fuchsia.location.namedplace#RegionCode` |

## RegulatoryRegionWatcher

*Defined in [fuchsia.location.namedplace/namedplace.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.location.namedplace/namedplace.fidl;l=58)*

The RegulatoryRegionWatcher protocol provides the mechanism for
radio subsystems to learn the currently applicable regulatory
region, and to be notified when that value changes.

<br />

### GetRegionUpdate

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.

#### Request

\<EMPTY\>

#### Response

| Name | Type |
|---|---|
| `new_region` | `https://fuchsia.dev/reference/fidl/fuchsia.location.namedplace#RegionCode` |

### GetUpdate

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.

#### Request

\<EMPTY\>

#### Response

| Name | Type |
|---|---|
| `new_region` | `https://fuchsia.dev/reference/fidl/fuchsia.location.namedplace#RegionCode` |

## **ALIASES**

| Name | Value | Description |
|---|---|---|
| [RegionCode](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.location.namedplace/namedplace.fidl;l=13) | `string`\[`2`\] | 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. |