blob: c00b383c9b6716d1bab8c3aeb93fa75b7fdafb37 [file] [log] [blame]
// Copyright 2021 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.gatt2;
using fuchsia.bluetooth as bt;
/// Errors that are returned by bluetooth.gatt2 methods.
type Error = strict enum {
/// A general error occurred that can not be classified as one of the more
/// specific errors.
FAILURE = 1;
/// Indicates that the response received from the server was invalid.
INVALID_RESPONSE = 2;
/// Indicates that more results were read than can fit in a FIDL response.
/// Consider reading attributes individually.
TOO_MANY_RESULTS = 3;
/// This attribute requires authorization, but the client is not authorized.
INSUFFICIENT_AUTHORIZATION = 4;
/// This attribute requires authentication, but the client is not authenticated.
INSUFFICIENT_AUTHENTICATION = 5;
/// This attribute requires a connection encrypted by a larger encryption key.
INSUFFICIENT_ENCRYPTION_KEY_SIZE = 6;
/// This attribute requires encryption, but the connection is not encrypted.
INSUFFICIENT_ENCRYPTION = 7;
/// This attribute is not readable.
READ_NOT_PERMITTED = 8;
/// This attribute is not writable.
WRITE_NOT_PERMITTED = 9;
/// One or more of the parameters are invalid. See the parameter documentation.
INVALID_PARAMETERS = 10;
/// The attribute indicated by the handle is invalid. It may have been removed.
INVALID_HANDLE = 11;
};
// A Handle uniquely identifies a service, characteristic, or descriptor.
type Handle = struct {
value uint64;
};
/// Represents encryption, authentication, and authorization permissions that can
/// be assigned to a specific access permission.
type SecurityRequirements = table {
/// If true, the physical link must be encrypted to access this attribute.
1: encryption_required bool;
/// If true, the physical link must be authenticated to access this
/// attribute.
2: authentication_required bool;
/// If true, the client needs to be authorized before accessing this
/// attribute.
3: authorization_required bool;
};
/// Specifies the access permissions for a specific attribute value.
type AttributePermissions = table {
/// Specifies whether or not an attribute has the read permission. If null,
/// then the attribute value cannot be read. Otherwise, it can be read only if
/// the permissions specified in the SecurityRequirements table are satisfied.
1: read SecurityRequirements;
/// Specifies whether or not an attribute has the write permission. If null,
/// then the attribute value cannot be written. Otherwise, it be written only
/// if the permissions specified in the SecurityRequirements table are satisfied.
2: write SecurityRequirements;
/// Specifies the security requirements for a client to subscribe to
/// notifications or indications on a characteristic. A characteristic's
/// support for notifications or indiciations is specified using the NOTIFY and
/// INDICATE characteristic properties. If a local characteristic has one of
/// these properties then this field can not be null. Otherwise, this field
/// must be left as null.
///
/// This field is ignored for Descriptors.
3: update SecurityRequirements;
};
/// Possible values for the characteristic properties bitfield. These specify the
/// GATT procedures that are allowed for a particular characteristic.
type CharacteristicPropertyBits = strict bits : uint16 {
BROADCAST = 0x1;
READ = 0x2;
WRITE_WITHOUT_RESPONSE = 0x4;
WRITE = 0x8;
NOTIFY = 0x10;
INDICATE = 0x20;
AUTHENTICATED_SIGNED_WRITES = 0x40;
RELIABLE_WRITE = 0x100;
WRITABLE_AUXILIARIES = 0x200;
};
/// Represents a local or remote GATT service.
type ServiceInfo = table {
/// Uniquely identifies this GATT service. Always present if this represents
/// a remote service. Ignored if present for local services.
1: handle Handle;
/// Indicates whether this is a primary or secondary service.
/// Always present for remote services. Optional for local services
/// Default: true
2: primary bool;
/// The UUID that identifies the type of this service.
/// Always present for remote services. Required for local services.
3: type bt.Uuid;
/// The characteristics of this service.
/// Always present for remote services. Required for local services.
4: characteristics vector<Characteristic>:MAX_CHARACTERISTIC_COUNT;
/// Handles of other services that are included by this service.
/// Only present for remote services if non-empty. Optional for local
/// services.
5: includes vector<Handle>:MAX_SERVICE_COUNT;
};
/// Represents a local or remote GATT characteristic.
type Characteristic = table {
/// Uniquely identifies this characteristic within a service.
/// For local characteristics, the specified handle must be unique across
/// all characteristic and descriptor handles in this service.
///
/// Always present. For local characteristics, this value is mandatory.
1: handle Handle;
/// The UUID that identifies the type of this characteristic.
/// Always present. Mandatory for local characteristics.
2: type bt.Uuid;
/// The characteristic properties bitfield. See `CharacteristicPropertyBits`
/// above for possible values.
/// Always present. Mandatory for local characteristics.
3: properties uint32;
/// The attribute permissions of this characteristic. For remote
/// characteristics, this value will be null until the permissions are
/// discovered via read and write requests.
///
/// For local characteristics, this value is mandatory.
4: permissions AttributePermissions;
/// The descriptors of this characteristic.
/// Present only if non-empty. Optional for local characteristics.
5: descriptors vector<Descriptor>:MAX_DESCRIPTOR_COUNT;
};
/// Represents a local or remote GATT characteristic descriptor.
type Descriptor = table {
/// Uniquely identifies this descriptor within a service.
/// For local descriptors, the specified handle must be unique
/// across all characteristic and descriptor handles in this service.
///
/// Always present. For local descriptors, this value is mandatory.
1: handle Handle;
/// The UUID that identifies the type of this descriptor.
/// Always present. For local descriptors, this value is mandatory.
2: type bt.Uuid;
/// The attribute permissions of this descriptor. For remote
/// descriptors, this value will be null until the permissions are
/// discovered via read and write requests.
///
/// For local descriptors, this value is mandatory.
3: permissions AttributePermissions;
};
/// Represents the supported options to read a long characteristic or descriptor
/// value from a server. Long values are those that may not fit in a single
/// message (longer than 22 bytes).
type LongReadOptions = table {
/// The byte to start the read at. Must be less than the length of the value.
/// Optional.
/// Default: 0
1: offset uint16;
/// The maximum number of bytes to read.
/// Optional.
/// Default: `MAX_VALUE_LENGTH`
2: max_bytes uint16;
};
/// Represents the options for reading a short characteristic or descriptor
/// value from a server. Short values are those that fit in a single message,
/// which is at least 22 bytes. This is an empty placeholder for now, as there
/// are no options.
type ShortReadOptions = struct {};
/// Represents the supported options to read a characteristic or descriptor
/// value from a server.
type ReadOptions = flexible union {
/// Perform a short read, which may be truncated (as indicated by the
/// maybe_truncated in the result)
/// Most reads in GATT services are short reads (<= 22 bytes).
1: short_read ShortReadOptions;
/// If present, perform a long read using the indicated options.
/// Optional.
/// Default: A short read will be performed.
2: long_read LongReadOptions;
};
/// Represents the supported write modes for writing characteristics &
/// descriptors to the server.
type WriteMode = flexible enum {
/// In `DEFAULT` mode, wait for a response from the server before returning
/// and do not verify the echo response.
/// Supported for both characteristics and descriptors.
DEFAULT = 1;
/// In `RELIABLE` mode, every value blob is verified against an echo
/// response from the server. The procedure is aborted if a value blob has
/// not been reliably delivered to the peer.
/// Only supported for characteristics.
RELIABLE = 2;
/// In `WITHOUT_RESPONSE` mode, delivery will not be confirmed before
/// returning. Writing without a response is only supported for short
/// characteristics with the `WRITE_WITHOUT_RESPONSE` property. The value
/// must fit into a single message. It is guaranteed that at least 20 bytes
/// will fit into a single message. If the value does not fit, a `FAILURE`
/// error will be produced. The value will be written at offset 0.
/// Only supported for characteristics.
WITHOUT_RESPONSE = 3;
};
/// Represents the supported options to write a characteristic/descriptor value
/// to a server.
type WriteOptions = table {
/// The mode of the write operation. For descriptors, only
/// [`WriteMode.DEFAULT`] is supported
/// Optional.
/// Default: [`WriteMode.DEFAULT`]
1: write_mode WriteMode;
/// Request a write starting at the byte indicated.
/// Must be missing or 0 if `write_mode` is [`WriteMode.WITHOUT_RESPONSE`].
/// Optional.
/// Default: 0
2: offset uint16;
};