blob: e450125af5b9e57ee616de340d8051a1a2be1ee4 [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.gatt;
using fuchsia.bluetooth;
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> 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<string>? uuids) -> (fuchsia.bluetooth.Status status, vector<ServiceInfo> services);
/// Connects the RemoteService with the given identifier.
ConnectToService(uint64 id, request<RemoteService> service);
};