| // Copyright 2017 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.bluetooth.le; |
| |
| using fuchsia.bluetooth; |
| |
| enum PeripheralError { |
| /// The operation or parameters requested are not supported on the current hardware. |
| NOT_SUPPORTED = 1; |
| |
| /// The provided advertising data exceeds the maximum allowed length when encoded. |
| ADVERTISING_DATA_TOO_LONG = 2; |
| |
| /// The provided scan response data exceeds the maximum allowed length when encoded. |
| SCAN_RESPONSE_DATA_TOO_LONG = 3; |
| |
| /// The requested parameters are invalid. |
| INVALID_PARAMETERS = 4; |
| |
| /// Advertising could not be initiated due to a hardware or system error. |
| FAILED = 6; |
| }; |
| |
| /// A client can indicate the transmission rate of advertising packets by specifying a mode. The |
| /// mode provides a hint to the system when configuring the controller with advertising interval and |
| /// window parameters. |
| /// |
| /// The mode affects how quickly a scanner or central is able to discover the peripheral; however it |
| /// can have an adverse effect on power consumption. While the system will try to honor a client's |
| /// request, it is not guaranteed to do so. |
| enum AdvertisingModeHint : uint8 { |
| /// Advertise with a very short interval and window for fast discovery at the cost of higher |
| /// power consumption. This corresponds to a 30-60ms interval on the 1M PHYs and 90-180ms on the |
| /// coded PHY. |
| VERY_FAST = 1; |
| |
| /// Advertise with a short interval and window that uses less power than `VERY_FAST`. |
| /// This corresponds to a 100-150ms interval on the 1M PHYs and 300-450ms on the coded PHY. |
| FAST = 2; |
| |
| /// Advertise with a moderate interval and window. This corresponds to 1-1.2s on the 1M PHYs and 3s |
| /// on the coded PHY. |
| SLOW = 3; |
| }; |
| |
| /// Represents the parameters for configuring advertisements. |
| table AdvertisingParameters { |
| /// The fields that will be encoded in the data section of advertising packets. |
| /// |
| /// This field is required. |
| 1: AdvertisingData data; |
| |
| /// The fields that are to be sent in a scan response packet. Clients may use this to send |
| /// additional data that does not fit inside an advertising packet on platforms that do not |
| /// support the advertising data length extensions. |
| /// |
| /// If present advertisements will be configured to be scannable. |
| 2: AdvertisingData scan_response; |
| |
| /// The desired advertising frequency. See [`fuchsia.bluetooth.le/AdvertisingModeHint`]. |
| /// Defaults to [`fuchsia.bluetooth.le/AdvertisingModeHint.SLOW`] if not present. |
| 3: AdvertisingModeHint mode_hint; |
| |
| /// If present and true then the controller will broadcast connectable advertisements which |
| /// allows remote LE centrals to initiate a connection to the Peripheral. If false or otherwise |
| /// not present then the advertisements will be non-connectable. |
| 4: bool connectable; |
| }; |
| |
| /// Capability that is valid for the duration of advertising. The caller can close the handle to |
| /// stop advertising. If the system internally stops advertising for any reason, the handle will be |
| /// closed to communicate this to the client. |
| protocol AdvertisingHandle {}; |
| |
| [Discoverable] |
| protocol Peripheral { |
| /// Start advertising as a LE peripheral. An empty response is sent to indicate when advertising |
| /// has successfully initiated. If advertising cannot be initiated, then the response will |
| /// contain a [`fuchsia.bluetooth.le/PeripheralError`]. |
| /// |
| /// This method can get called any number of times and successive calls can be made to |
| /// reconfigure the advertising parameters. However only the most recent |
| /// [`fuchsia.bluetooth.le/AdvertisingHandle`] will remain valid. |
| /// |
| /// An instance of [`fuchsia.bluetooth.le/Peripheral`] can only have one active advertisement at |
| /// a time. Clients must obtain multiple Peripheral instances for multiple simultaneous |
| /// advertisements. |
| /// |
| /// If the client closes its end of the [`fuchsia.bluetooth.le/AdvertisingHandle`] channel, |
| /// advertising will be stopped. If the handle is closed before the request is fulfilled, |
| /// advertising will be briefly enabled before it is terminated. |
| /// |
| /// + request `parameters` Parameters used while configuring the advertising instance. |
| /// + request `handle` Handle that remains valid for the duration of this advertising session. |
| /// * error Returns a [`fuchsia.bluetooth.le/PeripheralError`] if advertising cannot be |
| /// initiated. In this case the `handle` will be closed. |
| [Transitional] |
| StartAdvertising(AdvertisingParameters parameters, request<AdvertisingHandle> handle) -> () error PeripheralError; |
| |
| /// Event delivered when a remote LE central initiates a connection to this Peripheral when |
| /// connectable advertising is enabled via |
| /// [`fuchsia.bluetooth.le/Peripheral.StartAdvertising`]. |
| /// |
| /// The returned [`fuchsia.bluetooth.le/Connection`] handle can be used to interact with the |
| /// peer. It also represents a peripheral's ownership over the connection: the client can drop |
| /// the handle to request a disconnection. Similarly, the handle is closed by the system to |
| /// indicate that the connection to the peer has been lost. |
| /// |
| /// + request `peer` Information about the central that initiated the connection. |
| /// + request `handle` Represents the connection. |
| [Transitional] |
| -> OnPeerConnected(Peer peer, Connection connection); |
| |
| // TODO(BT-812): All methods and events declared below are deprecated. Remove them once all |
| // clients have transitioned to the new API. |
| |
| // [[DEPRECATED]] |
| // |
| // Starts sending advertisements based on the given parameters. |
| // - `advertising_data`: The advertising data that should be included in the payload. |
| // - `scan_result`: The scan result that will be returned when the advertisement is |
| // scanned. Setting this will mark the advertisement set as scannable. |
| // - `connectable`: when true, this advertisement will be marked as connectable. |
| // NOTE: connections can be made to a GATT server even if this is not set. |
| // - `interval_ms`: The requested interval to advertise this set at in milliseconds. |
| // minimum 20, maximum 10,000,000 (almost 3 hours). A reasonable |
| // default is 1 second (1000). |
| // - `anonymous`: if true, the address of this device will not be included |
| // |
| // If the `tx_power_level` is set in either AdvertisingData, it will be replaced with |
| // the actual TX Power level reported by the adapter, or included in the extended header |
| // of the Advertising PDU to save advertising space. |
| // |
| // If `scan_result` and `advertising_data` are both set, legacy advertising will be used, |
| // which limits the size of the advertising data. |
| // |
| // This request will fail if: |
| // - The `service_uuids` field of `advertising_data` contains a UUID that does not match |
| // a GATT service that was previously registered by this application; |
| // - If the provided advertising data cannot fit within the advertising payload MTU that |
| // is supported on the current platform and parameters. |
| // - If `anonymous` advertising is requested but the controller cannot support it. |
| [Transitional] |
| StartAdvertisingDeprecated(AdvertisingDataDeprecated advertising_data, AdvertisingDataDeprecated? scan_result, |
| bool connectable, uint32 interval_ms, bool anonymous) |
| -> (fuchsia.bluetooth.Status status, string? advertisement_id); |
| |
| // [[DEPRECATED]] |
| // |
| // Stop an advertising session that was previously started by this application. |
| [Transitional] |
| StopAdvertisingDeprecated(string advertisement_id) -> (fuchsia.bluetooth.Status status); |
| |
| // [[DEPRECATED]] |
| // |
| // Called when a remote central device has connected to a connectable advertisement. |
| // TODO(BT-839): Provide a GATT client handle which can be used to interact with GATT service |
| // on the central device. |
| // |
| // When this is called, the Advertisement will have stopped, and StartAdvertising |
| // should be called again to re-start advertising when the peripheral can accept |
| // another connection. |
| // |
| // Note: Centrals can connect to the local device and interact with the GATT server |
| // from an application without Peripheral.StartAdvertising() being called. |
| -> OnCentralConnected(string advertisement_id, RemoteDevice central); |
| |
| // [[DEPRECATED]] |
| // |
| // Called when a remote central previously connected to this application is disconnected. |
| -> OnCentralDisconnected(string device_id); |
| }; |