sdk/fidl/fuchsia.bluetooth.gatt/client.fidl - fuchsia - Git at Google

 // 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.gatt;

 using fuchsia.bluetooth as bt;

 table ReadByTypeResult {
     /// Characteristic or descriptor id.
     1: uint64 id;
     /// Truncated value of characteristic or descriptor, if it was read successfully.
     2: bytes:MAX_READ_BY_TYPE_VALUE_LENGTH value;
     /// Reason the value could not be read, if reading it resulted in an error.
     3: Error error;
 };

 protocol RemoteService {
     /// Returns the characteristics and characteristic descriptors that belong to
     /// this service.
     DiscoverCharacteristics() -> (fuchsia.bluetooth.Status status, vector<Characteristic>:MAX_CHARACTERISTIC_COUNT characteristics);

     /// Reads the value of the characteristic with `id` and returns it in the
     /// reply. If `status` indicates an error `value` will be empty.
     ///
     /// If the characteristic has a long value (i.e. larger than the current MTU)
     /// this method will return only the first (MTU - 1) bytes of the value. Use
     /// ReadLongCharacteristic() to read larger values or starting at a non-zero
     /// offset.
     ReadCharacteristic(uint64 id) -> (fuchsia.bluetooth.Status status, bytes value);

     /// Reads the complete value of a characteristic with the given `id`. This
     /// procedure should be used if the characteristic is known to have a value
     /// that can not be read in a single request.
     ///
     /// Returns up to `max_bytes` octets of the characteristic value starting at
     /// the given `offset`.
     ///
     /// This may return an error if:
     ///   a. `max_bytes` is 0;
     ///   b. The `offset` is invalid;
     ///   c. The characteristic does not have a long value;
     ///   d. The server does not support the long read procedure.
     ReadLongCharacteristic(uint64 id, uint16 offset, uint16 max_bytes) -> (fuchsia.bluetooth.Status status, bytes:MAX_VALUE_LENGTH value);

     /// Writes `value` to the characteristic with `id`. This operation may return
     /// an error if:
     ///   a. The size of `value` exceeds the current MTU.
     ///   b. The characteristic referred to by `id` does not have the 'write'
     ///      property.
     WriteCharacteristic(uint64 id, bytes value) -> (fuchsia.bluetooth.Status status);

     /// Writes `value` to the characteristic with `id`, beginning at `offset` using
     /// the provided `write_options`.
     ///
     /// This procedure should be used if the value to be written is too long to
     /// fit in a single request or needs to be written at an offset. This may
     /// return an error if:
     ///   a. The `offset` is invalid;
     ///   b. The server does not support the long write procedure.
     ///
     /// Long Writes require multiple messages to the remote service and take longer
     /// to execute than Short Writes. It is not recommended to send a short write
     /// while a long write is in process to the same id and data range. The order
     /// of the responses from this function signify the order in which the remote
     /// service received them, not necessarily the order in which it is called.
     WriteLongCharacteristic(uint64 id, uint16 offset, bytes:MAX_VALUE_LENGTH value, WriteOptions write_options)
         -> (fuchsia.bluetooth.Status status);

     /// Writes `value` to the characteristic with `id` without soliciting an
     /// acknowledgement from the peer. This method has no response and its delivery
     /// cannot be confirmed.
     WriteCharacteristicWithoutResponse(uint64 id, bytes value);

     /// Reads the value of the characteristic descriptor with `id` and returns it
     /// in the reply. If `status` indicates an error, `value` can be ignored.
     ///
     /// If the descriptor has a long value (i.e. larger than the current MTU)
     /// this method will return only the first (MTU - 1) bytes of the value. Use
     /// ReadLongDescriptor() to read larger values or starting at a non-zero
     /// offset.
     ReadDescriptor(uint64 id) -> (fuchsia.bluetooth.Status status, bytes value);

     /// Reads the complete value of a characteristic descriptor with the given `id`.
     /// This procedure should be used if the descriptor is known to have a value
     /// that can not be read in a single request.
     ///
     /// Returns up to `max_bytes` octets of the characteristic value starting at
     /// the given `offset`.
     ///
     /// This may return an error if:
     ///   a. `max_bytes` is 0;
     ///   b. The `offset` is invalid;
     ///   c. The server does not support the long read procedure.
     ReadLongDescriptor(uint64 id, uint16 offset, uint16 max_bytes) -> (fuchsia.bluetooth.Status status, bytes value);

     /// Writes `value` to the characteristic descriptor with `id`. This operation
     /// may return an error if:
     ///   a. The size of `value` exceeds the current MTU.
     ///   b. `id` refers to an internally reserved descriptor type (e.g. the Client
     ///      Characteristic Configuration descriptor).
     WriteDescriptor(uint64 id, bytes value) -> (fuchsia.bluetooth.Status status);

     /// Writes `value` to the characteristic descriptor with `id`, beginning at
     /// `offset`. This procedure should be used if the value to be written is too
     /// long to fit in a single request or needs to be written at an offset. This
     /// may return an error if:
     ///   a. The `offset` is invalid;
     ///   b. The server does not support the long write procedure.
     ///   c. `id` refers to an internally reserved descriptor type (e.g. the Client
     ///      Characteristic Configuration descriptor).
     ///
     /// Long Writes require multiple messages to the remote service and take longer
     /// to execute than Short Writes. It is not recommended to send a short write
     /// while a long write is in process to the same id and data range. The order
     /// of the responses from this function signify the order in which the remote
     /// service received them, not necessarily the order in which it is called.
     WriteLongDescriptor(uint64 id, uint16 offset, bytes:MAX_VALUE_LENGTH value) -> (fuchsia.bluetooth.Status status);

     /// Reads characteristics and descriptors with the given `uuid`. If no values are
     /// read, `results` will be empty. If reading a value results in a permission error,
     /// the handle and error will be included in `results`.
     ///
     /// NOTE: Values in `results` will be truncated to `MAX_READ_BY_TYPE_VALUE_LENGTH`
     /// bytes. `ReadCharacteristic`, `ReadLongCharacteristic()`, `ReadDescriptor`, or
     /// `ReadLongDescriptor()` should be used to read the complete values.
     ///
     /// This method is useful for reading values before discovery has completed, thereby
     /// reducing latency.
     ReadByType(fuchsia.bluetooth.Uuid uuid)
         -> (vector<ReadByTypeResult>:MAX_READ_BY_TYPE_RESULTS results) error Error;

     /// Subscribe or unsubscribe to notifications/indications from the characteristic with
     /// the given `id`. Notifications or indications will be enabled if `enable` is
     /// true or disabled if `enable` is false and they have been enabled for this
     /// client.
     ///
     /// Either notifications or indications will be enabled depending on
     /// characteristic properties. Indications will be preferred if they are
     /// supported.
     ///
     /// This operation fails if the characteristic does not have the "notify" or
     /// "indicate" property.
     ///
     /// A write request will be issued to configure the characteristic for notifications/indications
     /// if it contains a Client Characteristic Configuration descriptor. This method fails if an
     /// error occurs while writing to the descriptor.
     ///
     /// On success, the OnCharacteristicValueUpdated event will be sent whenever
     /// the peer sends a notification or indication. The local host will
     /// automically confirm indications.
     NotifyCharacteristic(uint64 id, bool enable) -> (fuchsia.bluetooth.Status status);

     /// Events:
     /// Called when a characteristic value notification or indication is received.
     -> OnCharacteristicValueUpdated(uint64 id, bytes value);
 };

 protocol Client {
     /// Enumerates services found on the peer that this Client represents. Results
     /// can be restricted by specifying a list of UUIDs in `uuids`. The returned
     /// ServiceInfo structures will contain only basic information about each
     /// service and the `characteristics` and `includes` fields will be null.
     ///
     /// To further interact with services, clients must obtain a RemoteService
     /// handle by calling ConnectToService().
     ListServices(vector<bt.UuidString>:MAX? uuids) -> (fuchsia.bluetooth.Status status, vector<ServiceInfo>:MAX_SERVICE_COUNT services);

     /// Connects the RemoteService with the given identifier.
     ConnectToService(uint64 id, request<RemoteService> service);
 };
	// 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.gatt;

	using fuchsia.bluetooth as bt;

	table ReadByTypeResult {
	/// Characteristic or descriptor id.
	1: uint64 id;
	/// Truncated value of characteristic or descriptor, if it was read successfully.
	2: bytes:MAX_READ_BY_TYPE_VALUE_LENGTH value;
	/// Reason the value could not be read, if reading it resulted in an error.
	3: Error error;
	};

	protocol RemoteService {
	/// Returns the characteristics and characteristic descriptors that belong to
	/// this service.
	DiscoverCharacteristics() -> (fuchsia.bluetooth.Status status, vector<Characteristic>:MAX_CHARACTERISTIC_COUNT characteristics);

	/// Reads the value of the characteristic with `id` and returns it in the
	/// reply. If `status` indicates an error `value` will be empty.
	///
	/// If the characteristic has a long value (i.e. larger than the current MTU)
	/// this method will return only the first (MTU - 1) bytes of the value. Use
	/// ReadLongCharacteristic() to read larger values or starting at a non-zero
	/// offset.
	ReadCharacteristic(uint64 id) -> (fuchsia.bluetooth.Status status, bytes value);

	/// Reads the complete value of a characteristic with the given `id`. This
	/// procedure should be used if the characteristic is known to have a value
	/// that can not be read in a single request.
	///
	/// Returns up to `max_bytes` octets of the characteristic value starting at
	/// the given `offset`.
	///
	/// This may return an error if:
	/// a. `max_bytes` is 0;
	/// b. The `offset` is invalid;
	/// c. The characteristic does not have a long value;
	/// d. The server does not support the long read procedure.
	ReadLongCharacteristic(uint64 id, uint16 offset, uint16 max_bytes) -> (fuchsia.bluetooth.Status status, bytes:MAX_VALUE_LENGTH value);

	/// Writes `value` to the characteristic with `id`. This operation may return
	/// an error if:
	/// a. The size of `value` exceeds the current MTU.
	/// b. The characteristic referred to by `id` does not have the 'write'
	/// property.
	WriteCharacteristic(uint64 id, bytes value) -> (fuchsia.bluetooth.Status status);

	/// Writes `value` to the characteristic with `id`, beginning at `offset` using
	/// the provided `write_options`.
	///
	/// This procedure should be used if the value to be written is too long to
	/// fit in a single request or needs to be written at an offset. This may
	/// return an error if:
	/// a. The `offset` is invalid;
	/// b. The server does not support the long write procedure.
	///
	/// Long Writes require multiple messages to the remote service and take longer
	/// to execute than Short Writes. It is not recommended to send a short write
	/// while a long write is in process to the same id and data range. The order
	/// of the responses from this function signify the order in which the remote
	/// service received them, not necessarily the order in which it is called.
	WriteLongCharacteristic(uint64 id, uint16 offset, bytes:MAX_VALUE_LENGTH value, WriteOptions write_options)
	-> (fuchsia.bluetooth.Status status);

	/// Writes `value` to the characteristic with `id` without soliciting an
	/// acknowledgement from the peer. This method has no response and its delivery
	/// cannot be confirmed.
	WriteCharacteristicWithoutResponse(uint64 id, bytes value);

	/// Reads the value of the characteristic descriptor with `id` and returns it
	/// in the reply. If `status` indicates an error, `value` can be ignored.
	///
	/// If the descriptor has a long value (i.e. larger than the current MTU)
	/// this method will return only the first (MTU - 1) bytes of the value. Use
	/// ReadLongDescriptor() to read larger values or starting at a non-zero
	/// offset.
	ReadDescriptor(uint64 id) -> (fuchsia.bluetooth.Status status, bytes value);

	/// Reads the complete value of a characteristic descriptor with the given `id`.
	/// This procedure should be used if the descriptor is known to have a value
	/// that can not be read in a single request.
	///
	/// Returns up to `max_bytes` octets of the characteristic value starting at
	/// the given `offset`.
	///
	/// This may return an error if:
	/// a. `max_bytes` is 0;
	/// b. The `offset` is invalid;
	/// c. The server does not support the long read procedure.
	ReadLongDescriptor(uint64 id, uint16 offset, uint16 max_bytes) -> (fuchsia.bluetooth.Status status, bytes value);

	/// Writes `value` to the characteristic descriptor with `id`. This operation
	/// may return an error if:
	/// a. The size of `value` exceeds the current MTU.
	/// b. `id` refers to an internally reserved descriptor type (e.g. the Client
	/// Characteristic Configuration descriptor).
	WriteDescriptor(uint64 id, bytes value) -> (fuchsia.bluetooth.Status status);

	/// Writes `value` to the characteristic descriptor with `id`, beginning at
	/// `offset`. This procedure should be used if the value to be written is too
	/// long to fit in a single request or needs to be written at an offset. This
	/// may return an error if:
	/// a. The `offset` is invalid;
	/// b. The server does not support the long write procedure.
	/// c. `id` refers to an internally reserved descriptor type (e.g. the Client
	/// Characteristic Configuration descriptor).
	///
	/// Long Writes require multiple messages to the remote service and take longer
	/// to execute than Short Writes. It is not recommended to send a short write
	/// while a long write is in process to the same id and data range. The order
	/// of the responses from this function signify the order in which the remote
	/// service received them, not necessarily the order in which it is called.
	WriteLongDescriptor(uint64 id, uint16 offset, bytes:MAX_VALUE_LENGTH value) -> (fuchsia.bluetooth.Status status);

	/// Reads characteristics and descriptors with the given `uuid`. If no values are
	/// read, `results` will be empty. If reading a value results in a permission error,
	/// the handle and error will be included in `results`.
	///
	/// NOTE: Values in `results` will be truncated to `MAX_READ_BY_TYPE_VALUE_LENGTH`
	/// bytes. `ReadCharacteristic`, `ReadLongCharacteristic()`, `ReadDescriptor`, or
	/// `ReadLongDescriptor()` should be used to read the complete values.
	///
	/// This method is useful for reading values before discovery has completed, thereby
	/// reducing latency.
	ReadByType(fuchsia.bluetooth.Uuid uuid)
	-> (vector<ReadByTypeResult>:MAX_READ_BY_TYPE_RESULTS results) error Error;

	/// Subscribe or unsubscribe to notifications/indications from the characteristic with
	/// the given `id`. Notifications or indications will be enabled if `enable` is
	/// true or disabled if `enable` is false and they have been enabled for this
	/// client.
	///
	/// Either notifications or indications will be enabled depending on
	/// characteristic properties. Indications will be preferred if they are
	/// supported.
	///
	/// This operation fails if the characteristic does not have the "notify" or
	/// "indicate" property.
	///
	/// A write request will be issued to configure the characteristic for notifications/indications
	/// if it contains a Client Characteristic Configuration descriptor. This method fails if an
	/// error occurs while writing to the descriptor.
	///
	/// On success, the OnCharacteristicValueUpdated event will be sent whenever
	/// the peer sends a notification or indication. The local host will
	/// automically confirm indications.
	NotifyCharacteristic(uint64 id, bool enable) -> (fuchsia.bluetooth.Status status);

	/// Events:
	/// Called when a characteristic value notification or indication is received.
	-> OnCharacteristicValueUpdated(uint64 id, bytes value);
	};

	protocol Client {
	/// Enumerates services found on the peer that this Client represents. Results
	/// can be restricted by specifying a list of UUIDs in `uuids`. The returned
	/// ServiceInfo structures will contain only basic information about each
	/// service and the `characteristics` and `includes` fields will be null.
	///
	/// To further interact with services, clients must obtain a RemoteService
	/// handle by calling ConnectToService().
	ListServices(vector<bt.UuidString>:MAX? uuids) -> (fuchsia.bluetooth.Status status, vector<ServiceInfo>:MAX_SERVICE_COUNT services);

	/// Connects the RemoteService with the given identifier.
	ConnectToService(uint64 id, request<RemoteService> service);
	};