| // 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. |
| |
| library fuchsia.wlan.policy; |
| |
| using fuchsia.wlan.common; |
| using zx; |
| |
| /// The ClientProvider API provides a mechanism for wlan control and is intended |
| /// to be called by applications or entities representing the user (ex, Settings). |
| /// This API is not intended to be called by other applications to change wlan |
| /// state without explicit user control. |
| /// |
| /// The second aim of this API design is to eliminate the "last-caller wins" |
| /// paradigm by limiting the number of controlling applications. A single caller |
| /// at a time is permitted to make API calls that impact wlan state. |
| [Discoverable] |
| protocol ClientProvider { |
| /// Control channel used by a single caller to trigger wlan client mode state |
| /// changes. The caller also provides a channel to receive wlan updates. |
| /// Only one caller can have the control channel open at a time. Attempts to |
| /// register as a controller while there is an active control registration |
| /// will result in the new caller's provided channel being closed. |
| GetController(request<ClientController> requests, ClientStateUpdates updates); |
| }; |
| |
| /// The ClientListener API provides a mechanism for callers to receive state change |
| /// updates about wlan operation. |
| [Discoverable] |
| protocol ClientListener { |
| /// Registration for callers to receive wlan client mode state updates. |
| GetListener(ClientStateUpdates updates); |
| }; |
| |
| /// ClientControllers allow the caller to trigger wlan state changes. This includes |
| /// whether connections will be attempted, scan triggers and saved network |
| /// configuration changes. |
| /// |
| /// Individual calls provided by the API are triggered after registering with |
| /// the wlan ClientProvider via the OpenControlChannel call. |
| protocol ClientController { |
| /// Enables wlan to initiate connections to networks (either autoconnect to |
| /// saved networks or act on incoming calls triggering connections). Depending |
| /// on the underlying capabilities of the device, this call may impact other |
| /// device operation (for example, acting as an access point). |
| StartClientConnections() -> (fuchsia.wlan.common.RequestStatus status); |
| |
| /// Disables connections to wlan networks and tears down any existing connections. |
| StopClientConnections() -> (fuchsia.wlan.common.RequestStatus status); |
| |
| /// Triggers a network scan. Note, even in normal operation, some scan requests |
| /// may be rejected due to timing with connection establishment or other critical |
| /// connection maintenance. If the scan is cancelled or errors, the caller is |
| /// notified via a status update in the ScanResultIterator. |
| ScanForNetworks(request<ScanResultIterator> iterator); |
| |
| /// Saves a network and any credential information needed to connect. Multiple |
| /// entries for the same NetworkIdentifier can exist if the credentials are |
| /// different. If a caller attempts to save a NetworkConfig with the same |
| /// NetworkIdentifier and same Credentials as a previously saved network |
| /// the method will effectively be a no-op. |
| SaveNetwork(NetworkConfig config) -> () error NetworkConfigChangeError; |
| |
| /// Removes a saved network configuration, if one exists. This method will |
| /// automatically trigger a disconnection if the NetworkConfig was used to |
| /// establish the connection. |
| RemoveNetwork(NetworkConfig config) -> () error NetworkConfigChangeError; |
| |
| /// Retrieve the currently saved networks using the provided iterator. |
| GetSavedNetworks(request<NetworkConfigIterator> iterator); |
| |
| /// Request to attempt a connection to the specified network. The target of the |
| /// connect call must already be a saved network. This call is not a |
| /// blocking call for the duration of the connection attempt. If the call cannot |
| /// be immediately attempted, a failure status will be returned. If the connection |
| /// request will be attempted, an acknowledgment status will be returned. Updates |
| /// to the connection status are disseminated via the ClientStateUpdates protocol. |
| /// If the connect attempt fails, the service will fall back to default behavior |
| /// with scanning and connecting via network selection. |
| Connect(NetworkIdentifier id) -> (fuchsia.wlan.common.RequestStatus status); |
| }; |
| |
| /// Iterator used to send back scan results to the caller. The corresponding channel |
| /// will be closed after the scan is complete and results are returned or fails due |
| /// to an error. |
| protocol ScanResultIterator { |
| /// Allows caller to request the next set of scan results. When all scan results |
| /// have been handled, GetNext will return an empty vector and the channel will |
| /// be closed. If an error is encountered during the scan, it will be returned |
| /// after all scan results have been retrieved. |
| GetNext() -> (vector<ScanResult> scan_results) error ScanErrorCode; |
| }; |
| |
| /// Wlan scan error codes. |
| enum ScanErrorCode { |
| /// Unexpected scan error without a specific cause. |
| GENERAL_ERROR = 1; |
| /// Scan was cancelled and stopped. This can happen due to operating state changes, |
| /// higher priority operations or conflicting requests. |
| CANCELLED = 2; |
| }; |
| |
| |
| /// Information from an observed wlan network. This includes the |
| /// network name, security type, detected access point information and network |
| /// compatibility information. |
| table ScanResult { |
| /// Network properties used to distinguish between networks and to group |
| /// individual APs. |
| 1: NetworkIdentifier id; |
| |
| /// Individual access points offering the specified network. |
| 2: vector<Bss> entries; |
| |
| /// Indication if the detected network is supported by the implementation. |
| 3: Compatibility compatibility; |
| }; |
| |
| /// Information for a particular ScanResult entry. |
| table Bss { |
| /// MAC address for the AP interface. |
| 1: array<uint8>:6 bssid; |
| |
| /// Calculated received signal strength for the beacon/probe response. |
| 2: int8 rssi; |
| |
| /// Operating frequency for this network (in MHz). |
| 3: uint32 frequency; |
| |
| /// Realtime timestamp for this scan result entry. |
| 4: zx.time timestamp_nanos; |
| }; |
| |
| /// Iterator used by callers to retrieve saved network information. |
| protocol NetworkConfigIterator { |
| |
| /// Method allowing the next block of saved networks to be handled. |
| GetNext() -> (vector<NetworkConfig> configs); |
| }; |
| |
| /// Wlan status changes for client connections and the associated network state. |
| /// These updates contain information about whether or not the device will attempt |
| /// to connect to networks, saved network configuration change information, |
| /// individual connection state information by NetworkIdentifier and connection |
| /// attempt information. The connection and network related calls are based on |
| /// NetworkIdentifier to allow multiple simultaneous connections on supporting |
| /// devices. |
| protocol ClientStateUpdates { |
| |
| /// Updates registered listeners with the current summary of wlan client state. |
| /// This will be called when there is any change to the state and the |
| /// registered listeners are responsible for deciding what information has |
| /// changed (since this is dependent on when they last acknowledged the update). |
| OnClientStateUpdate(ClientStateSummary summary) -> (); |
| }; |
| |
| /// Information about the current client state for the device. This includes if the |
| /// device will attempt to connect to access points (when applicable), any existing |
| /// connections and active connection attempts and their outcomes. |
| table ClientStateSummary { |
| /// State indicating whether wlan will attempt to connect to networks or not. |
| 1: WlanClientState state; |
| |
| /// Active connections, connection attempts or failed connections. |
| 2: vector<NetworkState> networks; |
| }; |
| |
| /// Information about current network connections and attempts. |
| table NetworkState { |
| /// Network id for the current connection (or attempt). |
| 1: NetworkIdentifier id; |
| |
| /// Current state for the connection. |
| 2: ConnectionState state; |
| |
| /// Extra information for debugging or Settings display |
| 3: DisconnectStatus status; |
| }; |
| |
| /// Wlan operating state for client connections |
| enum WlanClientState { |
| CONNECTIONS_DISABLED = 1; |
| CONNECTIONS_ENABLED = 2; |
| }; |
| |
| /// High level compatibility for the scan result. Not all network security protocols |
| /// are supported. New protocols may be detected before they are connectable |
| /// and deprecated protocols may explicitly be unsupported due to security and |
| /// privacy concerns. |
| enum Compatibility { |
| /// Denotes that the network is supported and connections can be attempted (given |
| /// appropriate credentials when required). |
| SUPPORTED = 1; |
| |
| /// The network uses a deprecated security protocol and is explicitly not supported. |
| DISALLOWED_INSECURE = 2; |
| |
| /// The network uses a currently unsupported security protocol. |
| DISALLOWED_NOT_SUPPORTED = 3; |
| }; |
| |
| /// Potential error cases for saving and removing network configurations. This is |
| /// intentionally sparse and will be expanded as use cases develop. |
| enum NetworkConfigChangeError { |
| GENERAL_ERROR = 1; |
| }; |
| |
| /// Connection states used to update registered wlan observers. |
| enum ConnectionState { |
| /// The connection attempt was terminated due to an error. |
| FAILED = 1; |
| |
| /// The network is disconnected. |
| DISCONNECTED = 2; |
| |
| /// The device is attempting a connection to a network. |
| CONNECTING = 3; |
| |
| /// The connection is now established. Note: This does not make any guarantees |
| /// about higher level network reachability. |
| CONNECTED = 4; |
| }; |
| |
| /// Disconnect and connection attempt failure status codes |
| enum DisconnectStatus { |
| /// The requested connection attempt failed due to timeout. |
| TIMED_OUT = 1; |
| |
| /// The requested connection attempt failed due to suspected credential failure. |
| CREDENTIALS_FAILED = 2; |
| |
| /// The existing connection was explicitly disconnected by an action of wlan |
| /// service on this device. This can be the result of wlan connections being |
| /// disabled, network configuration being removed or a connection attempt to a |
| /// different network (as examples). |
| CONNECTION_STOPPED = 3; |
| |
| /// The existing connection failed unexpectedly in a way that is not an |
| /// explicitly triggered disconnect by the device (or user). Examples |
| /// of unexpected disconnections include: an underlying error (driver, |
| /// firmware, etc.), beacon loss, access point failure. |
| CONNECTION_FAILED = 4; |
| }; |