sdk/fidl/fuchsia.bluetooth.le/central.fidl - fuchsia - Git at Google

 // Copyright 2018 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 as bt;
 using fuchsia.bluetooth.gatt;

 enum CentralError {
     /// The request was aborted.
     ABORTED = 1;

     /// The request is already in progress.
     IN_PROGRESS = 2;

     /// The provided parameters are invalid.
     INVALID_PARAMETERS = 3;

     /// Advertising could not be initiated due to a hardware or system error.
     FAILED = 4;
 };

 /// Filter parameters for use during a scan. A discovered peer only matches the
 /// filter if it satisfies all of the present filter parameters.
 table Filter {
     /// Filter based on advertised service UUID.
     1: bt.Uuid service_uuid;

     /// Filter based on service data containing the given UUID.
     2: bt.Uuid service_data_uuid;

     /// Filter based on a manufacturer identifier present in the manufacturer
     /// data. If this filter parameter is set, then the advertising payload must
     /// contain manufacturer specific data with the provided company identifier
     /// to satisfy this filter. Manufacturer identifiers can be found at
     /// https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/
     3: uint16 manufacturer_id;

     /// Filter based on whether or not a device is connectable. For example, a
     /// client that is only interested in peripherals that it can connect to can
     /// set this to true. Similarly a client can scan only for broadcasters by
     /// setting this to false.
     4: bool connectable;

     /// Filter results based on a portion of the advertised device name.
     /// Substring matches are allowed.
     5: bt.DeviceName name;

     /// Filter results based on the path loss of the radio wave. A device that
     /// matches this filter must satisfy the following:
     ///   1. Radio transmission power level and received signal strength must be
     ///      available for the path loss calculation;
     ///   2. The calculated path loss value must be less than, or equal to,
     ///      `max_path_loss`.
     ///
     /// NOTE: This field is calculated using the RSSI and TX Power information
     /// obtained from advertising and scan response data during a scan procedure.
     /// It should NOT be confused with information for an active connection
     /// obtained using the "Path Loss Reporting" feature.
     6: int8 max_path_loss;
 };

 /// Parameters used during a scan.
 table ScanOptions {
     /// List of filters for use during a scan. A peripheral that satisfies any
     /// of these filters will be reported. At least 1 filter must be specified.
     /// While not recommended, clients that require that all peripherals be
     /// reported can specify an empty filter.
     1: vector<Filter>:MAX filters;
 };

 /// Represents an active scan procedure. This protocol remains valid for the
 /// duration of a scan and can be used to obtain scan results. The client can
 /// close the protocol to stop scanning. If a scan is stopped by the system, the
 /// protocol will be closed with the epitaph `CANCELED` to communicate this to
 /// the client.
 protocol ScanResultWatcher {
     /// Returns a list of all LE peers that satisfy the filters indicated in
     /// `ScanOptions`. The first response(s) will return matching discovered
     /// peers immediately. Subsequent calls receive a response only when peers
     /// have been scanned or updated since the last call. If a second call to
     /// `Watch` is erronously sent while one call is already pending, the scan
     /// will be canceled and the protocol will be closed.
     ///
     /// - response `updated` Peers that were added or updated since the last
     ///   call to Watch().
     Watch() -> (vector<Peer>:MAX updated);
 };

 [Discoverable]
 protocol Central {
     /// Scans for nearby LE peripherals and broadcasters. If the scan cannot be
     /// initiated, then `result_watcher` will be closed with an epitaph.
     ///
     /// A Central client is allowed to have only one active scan at a time.
     /// Accordingly, only one Scan request can be outstanding at a time.
     /// Additional calls to Scan will fail.
     ///
     /// The lifetime of the scan session is tied to the `result_watcher`
     /// protocol provided. The scan will be stopped if the channel is closed.
     ///
     /// Once a scan is started, the [`fuchsia.bluetooth.le/ScanResultWatcher`]
     /// can be used to watch for scan results.
     ///
     /// + request `options` Options used to configure the scan session.
     /// + request `result_watcher` Protocol that remains valid for the duration
     ///   of this scan session.
     /// - response An empty response will be sent to acknowledge the scan has
     ///   stopped.
     ///
     /// The following epitaphs may be sent by the server on error:
     /// * error `ALREADY_EXISTS`: A scan is already in progress. Each `Central`
     ///   protocol is only allowed 1 active scan.
     /// * error `INVALID_ARGS`: Some of the scan `options` are invalid. See the
     ///   `ScanOptions` documentation.
     /// * error `INTERNAL`: An internal error occurred and a scan could not be
     ///   started.
     Scan(ScanOptions options, request<ScanResultWatcher> result_watcher) -> ();

     /// Connect to the peer with the given identifier.
     ///
     /// The requested [`fuchsia.bluetooth.le/Connection`] represents the
     /// client's interest on the LE connection to the peer. Closing the channel
     /// removes interest, but may not result in disconnection if another client
     /// holds a valid [`fuchsia.bluetooth.le/Connection`] to the same peer.
     ///
     /// The [`fuchsia.bluetooth.le/Connection`] `handle` will be closed by the
     /// system if the connection to the peer is lost or an error occurs.
     ///
     /// The following epitaphs may be sent by the server on error:
     /// + `INVALID_ARGS`: Some of the parameters are invalid.
     /// + `NOT_CONNECTED`: A connection could not be established.
     ///
     /// + request `id` Identifier of the peer to initiate a connection to.
     /// + request `options` Options used to configure the connection.
     /// + request `handle` Handle that remains valid for the duration of this
     ///   connection.
     [Transitional = "Not yet implemented"]
     Connect(bt.PeerId id, ConnectionOptions options, request<Connection> handle);

     /// Returns the list of peripherals that are known to the system from previous scan, connection,
     /// and/or bonding procedures. The results can be filtered based on service UUIDs that are known to
     /// be present on the peripheral.
     ///
     /// This method only returns peripherals (i.e. connectable devices).
     [Deprecated]
     GetPeripherals(vector<bt.UuidString>:MAX? service_uuids) -> (vector<RemoteDevice>:MAX peripherals);

     /// **This method is not implemented by the Fuchsia core stack- TODO(fxbug.dev/1424)**
     ///
     /// Returns information about a single peripheral that is known to the system from previous scan,
     /// connection, and/or bonding procedures based on its unique identifier. Returns null if
     /// `identifier` is not recognized.
     [Deprecated]
     GetPeripheral(bt.PeerIdString identifier) -> (RemoteDevice? peripheral);

     /// Initiates a scan session for nearby peripherals and broadcasters. Discovered devices will be
     /// reported via CentralDelegate.OnDeviceDiscovered(). If a scan session is already in progress,
     /// `filter` will replace the existing session's filter.
     ///
     /// If `filter` is null or empty (i.e. none of its fields has been populated) then the delegate
     /// will be notified for all discoverable devices that are found. This is not recommended; clients
     /// should generally filter results by at least one of `filter.service_uuids`,
     /// `filter.service_data`, and/or `filter.manufacturer_identifier`.
     [Deprecated = "Use Scan instead"]
     StartScan(ScanFilter? filter) -> (fuchsia.bluetooth.Status status);

     /// Terminate a previously started scan session.
     [Deprecated]
     StopScan();

     /// Creates a connection to the peripheral device with the given identifier.
     /// Returns the status of the operation in `status`.
     ///
     /// On success, `gatt_client` will be bound and can be used for GATT client
     /// role procedures. On failure, `gatt_client` will be closed and `status` will
     /// indicate an error.
     [Deprecated = "Use Connect instead"]
     ConnectPeripheral(bt.PeerIdString identifier, ConnectionOptions options,
                       request<fuchsia.bluetooth.gatt.Client> gatt_client)
         -> (fuchsia.bluetooth.Status status);

     /// Disconnects this Central's connection to the peripheral with the given identifier.
     [Deprecated]
     DisconnectPeripheral(bt.PeerIdString identifier) -> (fuchsia.bluetooth.Status status);

     /// Called when the scan state changes, e.g. when a scan session terminates due to a call to
     /// Central.StopScan() or another unexpected condition.
     [Deprecated]
     -> OnScanStateChanged(bool scanning);

     /// Called for each peripheral/broadcaster that is discovered during a scan session. `rssi`
     /// contains the received signal strength of the advertising packet that generated this event, if
     /// available.
     [Deprecated]
     -> OnDeviceDiscovered(RemoteDevice device);

     /// Called when this Central's connection to a peripheral with the given identifier is terminated.
     [Deprecated]
     -> OnPeripheralDisconnected(bt.PeerIdString identifier);
 };
	// Copyright 2018 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 as bt;
	using fuchsia.bluetooth.gatt;

	enum CentralError {
	/// The request was aborted.
	ABORTED = 1;

	/// The request is already in progress.
	IN_PROGRESS = 2;

	/// The provided parameters are invalid.
	INVALID_PARAMETERS = 3;

	/// Advertising could not be initiated due to a hardware or system error.
	FAILED = 4;
	};

	/// Filter parameters for use during a scan. A discovered peer only matches the
	/// filter if it satisfies all of the present filter parameters.
	table Filter {
	/// Filter based on advertised service UUID.
	1: bt.Uuid service_uuid;

	/// Filter based on service data containing the given UUID.
	2: bt.Uuid service_data_uuid;

	/// Filter based on a manufacturer identifier present in the manufacturer
	/// data. If this filter parameter is set, then the advertising payload must
	/// contain manufacturer specific data with the provided company identifier
	/// to satisfy this filter. Manufacturer identifiers can be found at
	/// https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/
	3: uint16 manufacturer_id;

	/// Filter based on whether or not a device is connectable. For example, a
	/// client that is only interested in peripherals that it can connect to can
	/// set this to true. Similarly a client can scan only for broadcasters by
	/// setting this to false.
	4: bool connectable;

	/// Filter results based on a portion of the advertised device name.
	/// Substring matches are allowed.
	5: bt.DeviceName name;

	/// Filter results based on the path loss of the radio wave. A device that
	/// matches this filter must satisfy the following:
	/// 1. Radio transmission power level and received signal strength must be
	/// available for the path loss calculation;
	/// 2. The calculated path loss value must be less than, or equal to,
	/// `max_path_loss`.
	///
	/// NOTE: This field is calculated using the RSSI and TX Power information
	/// obtained from advertising and scan response data during a scan procedure.
	/// It should NOT be confused with information for an active connection
	/// obtained using the "Path Loss Reporting" feature.
	6: int8 max_path_loss;
	};

	/// Parameters used during a scan.
	table ScanOptions {
	/// List of filters for use during a scan. A peripheral that satisfies any
	/// of these filters will be reported. At least 1 filter must be specified.
	/// While not recommended, clients that require that all peripherals be
	/// reported can specify an empty filter.
	1: vector<Filter>:MAX filters;
	};

	/// Represents an active scan procedure. This protocol remains valid for the
	/// duration of a scan and can be used to obtain scan results. The client can
	/// close the protocol to stop scanning. If a scan is stopped by the system, the
	/// protocol will be closed with the epitaph `CANCELED` to communicate this to
	/// the client.
	protocol ScanResultWatcher {
	/// Returns a list of all LE peers that satisfy the filters indicated in
	/// `ScanOptions`. The first response(s) will return matching discovered
	/// peers immediately. Subsequent calls receive a response only when peers
	/// have been scanned or updated since the last call. If a second call to
	/// `Watch` is erronously sent while one call is already pending, the scan
	/// will be canceled and the protocol will be closed.
	///
	/// - response `updated` Peers that were added or updated since the last
	/// call to Watch().
	Watch() -> (vector<Peer>:MAX updated);
	};

	[Discoverable]
	protocol Central {
	/// Scans for nearby LE peripherals and broadcasters. If the scan cannot be
	/// initiated, then `result_watcher` will be closed with an epitaph.
	///
	/// A Central client is allowed to have only one active scan at a time.
	/// Accordingly, only one Scan request can be outstanding at a time.
	/// Additional calls to Scan will fail.
	///
	/// The lifetime of the scan session is tied to the `result_watcher`
	/// protocol provided. The scan will be stopped if the channel is closed.
	///
	/// Once a scan is started, the [`fuchsia.bluetooth.le/ScanResultWatcher`]
	/// can be used to watch for scan results.
	///
	/// + request `options` Options used to configure the scan session.
	/// + request `result_watcher` Protocol that remains valid for the duration
	/// of this scan session.
	/// - response An empty response will be sent to acknowledge the scan has
	/// stopped.
	///
	/// The following epitaphs may be sent by the server on error:
	/// * error `ALREADY_EXISTS`: A scan is already in progress. Each `Central`
	/// protocol is only allowed 1 active scan.
	/// * error `INVALID_ARGS`: Some of the scan `options` are invalid. See the
	/// `ScanOptions` documentation.
	/// * error `INTERNAL`: An internal error occurred and a scan could not be
	/// started.
	Scan(ScanOptions options, request<ScanResultWatcher> result_watcher) -> ();

	/// Connect to the peer with the given identifier.
	///
	/// The requested [`fuchsia.bluetooth.le/Connection`] represents the
	/// client's interest on the LE connection to the peer. Closing the channel
	/// removes interest, but may not result in disconnection if another client
	/// holds a valid [`fuchsia.bluetooth.le/Connection`] to the same peer.
	///
	/// The [`fuchsia.bluetooth.le/Connection`] `handle` will be closed by the
	/// system if the connection to the peer is lost or an error occurs.
	///
	/// The following epitaphs may be sent by the server on error:
	/// + `INVALID_ARGS`: Some of the parameters are invalid.
	/// + `NOT_CONNECTED`: A connection could not be established.
	///
	/// + request `id` Identifier of the peer to initiate a connection to.
	/// + request `options` Options used to configure the connection.
	/// + request `handle` Handle that remains valid for the duration of this
	/// connection.
	[Transitional = "Not yet implemented"]
	Connect(bt.PeerId id, ConnectionOptions options, request<Connection> handle);

	/// Returns the list of peripherals that are known to the system from previous scan, connection,
	/// and/or bonding procedures. The results can be filtered based on service UUIDs that are known to
	/// be present on the peripheral.
	///
	/// This method only returns peripherals (i.e. connectable devices).
	[Deprecated]
	GetPeripherals(vector<bt.UuidString>:MAX? service_uuids) -> (vector<RemoteDevice>:MAX peripherals);

	/// This method is not implemented by the Fuchsia core stack- TODO(fxbug.dev/1424)
	///
	/// Returns information about a single peripheral that is known to the system from previous scan,
	/// connection, and/or bonding procedures based on its unique identifier. Returns null if
	/// `identifier` is not recognized.
	[Deprecated]
	GetPeripheral(bt.PeerIdString identifier) -> (RemoteDevice? peripheral);

	/// Initiates a scan session for nearby peripherals and broadcasters. Discovered devices will be
	/// reported via CentralDelegate.OnDeviceDiscovered(). If a scan session is already in progress,
	/// `filter` will replace the existing session's filter.
	///
	/// If `filter` is null or empty (i.e. none of its fields has been populated) then the delegate
	/// will be notified for all discoverable devices that are found. This is not recommended; clients
	/// should generally filter results by at least one of `filter.service_uuids`,
	/// `filter.service_data`, and/or `filter.manufacturer_identifier`.
	[Deprecated = "Use Scan instead"]
	StartScan(ScanFilter? filter) -> (fuchsia.bluetooth.Status status);

	/// Terminate a previously started scan session.
	[Deprecated]
	StopScan();

	/// Creates a connection to the peripheral device with the given identifier.
	/// Returns the status of the operation in `status`.
	///
	/// On success, `gatt_client` will be bound and can be used for GATT client
	/// role procedures. On failure, `gatt_client` will be closed and `status` will
	/// indicate an error.
	[Deprecated = "Use Connect instead"]
	ConnectPeripheral(bt.PeerIdString identifier, ConnectionOptions options,
	request<fuchsia.bluetooth.gatt.Client> gatt_client)
	-> (fuchsia.bluetooth.Status status);

	/// Disconnects this Central's connection to the peripheral with the given identifier.
	[Deprecated]
	DisconnectPeripheral(bt.PeerIdString identifier) -> (fuchsia.bluetooth.Status status);

	/// Called when the scan state changes, e.g. when a scan session terminates due to a call to
	/// Central.StopScan() or another unexpected condition.
	[Deprecated]
	-> OnScanStateChanged(bool scanning);

	/// Called for each peripheral/broadcaster that is discovered during a scan session. `rssi`
	/// contains the received signal strength of the advertising packet that generated this event, if
	/// available.
	[Deprecated]
	-> OnDeviceDiscovered(RemoteDevice device);

	/// Called when this Central's connection to a peripheral with the given identifier is terminated.
	[Deprecated]
	-> OnPeripheralDisconnected(bt.PeerIdString identifier);
	};