blob: 78795089b798e0d3665fd3886a2830728d801056 [file] [log] [blame]
// 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;
enum PeripheralError {
/// The operation or parameters requested are not supported on the current hardware.
/// The provided advertising data exceeds the maximum allowed length when encoded.
/// The provided scan response data exceeds the maximum allowed length when encoded.
/// The requested parameters are invalid.
/// The request to start advertising was aborted, for example by issuing a new request with new
/// parameters.
/// Advertising could not be initiated due to a hardware or system error.
/// 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.
/// 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;
/// [[DEPRECATED]]: Prefer to use the ConnectionOptions field for new code.
/// 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;
/// If present, the controller will broadcast connectable advertisements which allow remote LE
/// centrals to initiate connections to the Peripheral. The fields of ConnectionOptions will
/// configure any connections set up from advertising.
5: ConnectionOptions connection_options;
/// 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 {
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.
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.
-> OnPeerConnected(Peer peer, Connection connection);