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;

 type CentralError = strict enum {
     /// 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.
 type Filter = table {
     /// Filter based on advertised service UUID.
     1: service_uuid bt.Uuid;

     /// Filter based on service data containing the given UUID.
     2: service_data_uuid bt.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: manufacturer_id uint16;

     /// 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: connectable bool;

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

     /// 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: max_path_loss int8;
 };

 /// Parameters used during a scan.
 type ScanOptions = table {
     /// 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: filters vector<Filter>:MAX;
 };

 /// 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() -> (struct {
         updated vector<Peer>:MAX;
     });
 };

 @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(resource struct {
         options ScanOptions;
         result_watcher server_end:ScanResultWatcher;
     }) -> ();

     /// 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.
     /// + `ALREADY_BOUND`: A Connection to the peer already exists for this Central. The existing
     ///                    Connection should be used.
     /// + `NOT_CONNECTED`: A connection could not be established.
     /// + `CONNECTION_RESET`: The peer disconnected.
     ///
     /// + 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.
     @available(added=HEAD)
     Connect(resource struct {
         id bt.PeerId;
         options ConnectionOptions;
         handle server_end:Connection;
     });

     /// 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(struct {
         service_uuids vector<bt.UuidString>:<MAX, optional>;
     }) -> (struct {
         peripherals vector<RemoteDevice>:MAX;
     });

     /// **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(struct {
         identifier bt.PeerIdString;
     }) -> (struct {
         peripheral box<RemoteDevice>;
     });

     /// 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(struct {
         filter box<ScanFilter>;
     }) -> (struct {
         status bt.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(resource struct {
         identifier bt.PeerIdString;
         options ConnectionOptions;
         gatt_client server_end:fuchsia.bluetooth.gatt.Client;
     }) -> (struct {
         status bt.Status;
     });

     /// Disconnects this Central's connection to the peripheral with the given identifier.
     @deprecated
     DisconnectPeripheral(struct {
         identifier bt.PeerIdString;
     }) -> (struct {
         status bt.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(struct {
         scanning bool;
     });

     /// 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(struct {
         device RemoteDevice;
     });

     /// Called when this Central's connection to a peripheral with the given identifier is terminated.
     @deprecated
     -> OnPeripheralDisconnected(struct {
         identifier bt.PeerIdString;
     });
 };
	// 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;

	type CentralError = strict enum {
	/// 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.
	type Filter = table {
	/// Filter based on advertised service UUID.
	1: service_uuid bt.Uuid;

	/// Filter based on service data containing the given UUID.
	2: service_data_uuid bt.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: manufacturer_id uint16;

	/// 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: connectable bool;

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

	/// 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: max_path_loss int8;
	};

	/// Parameters used during a scan.
	type ScanOptions = table {
	/// 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: filters vector<Filter>:MAX;
	};

	/// 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() -> (struct {
	updated vector<Peer>:MAX;
	});
	};

	@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(resource struct {
	options ScanOptions;
	result_watcher server_end:ScanResultWatcher;
	}) -> ();

	/// 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.
	/// + `ALREADY_BOUND`: A Connection to the peer already exists for this Central. The existing
	/// Connection should be used.
	/// + `NOT_CONNECTED`: A connection could not be established.
	/// + `CONNECTION_RESET`: The peer disconnected.
	///
	/// + 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.
	@available(added=HEAD)
	Connect(resource struct {
	id bt.PeerId;
	options ConnectionOptions;
	handle server_end:Connection;
	});

	/// 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(struct {
	service_uuids vector<bt.UuidString>:<MAX, optional>;
	}) -> (struct {
	peripherals vector<RemoteDevice>:MAX;
	});

	/// 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(struct {
	identifier bt.PeerIdString;
	}) -> (struct {
	peripheral box<RemoteDevice>;
	});

	/// 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(struct {
	filter box<ScanFilter>;
	}) -> (struct {
	status bt.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(resource struct {
	identifier bt.PeerIdString;
	options ConnectionOptions;
	gatt_client server_end:fuchsia.bluetooth.gatt.Client;
	}) -> (struct {
	status bt.Status;
	});

	/// Disconnects this Central's connection to the peripheral with the given identifier.
	@deprecated
	DisconnectPeripheral(struct {
	identifier bt.PeerIdString;
	}) -> (struct {
	status bt.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(struct {
	scanning bool;
	});

	/// 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(struct {
	device RemoteDevice;
	});

	/// Called when this Central's connection to a peripheral with the given identifier is terminated.
	@deprecated
	-> OnPeripheralDisconnected(struct {
	identifier bt.PeerIdString;
	});
	};