| // 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. |
| /// |
| /// The values correspond with those in Bluetooth 5.2 Vol. 3 Part G Table 3.4, |
| /// and Supplement to the Bluetooth Core Specification v9 Part B Table 1.1, |
| /// but this is for ease of reference only. Clients should *not* rely on these |
| /// values remaining constant. Omitted values from the spec are handled |
| /// internally and will not be returned to clients. |
| /// |
| /// Only certain errors can be returned by LocalService methods. Those are noted |
| /// in comments. |
| type Error = strict enum { |
| // ATT Errors |
| |
| /// The attribute indicated by the handle is invalid. It may have been removed. |
| /// |
| /// This may be returned by a LocalService method. |
| INVALID_HANDLE = 0x1; |
| |
| /// This attribute is not readable. |
| READ_NOT_PERMITTED = 0x2; |
| |
| /// This attribute is not writable. |
| WRITE_NOT_PERMITTED = 0x3; |
| |
| /// Indicates that the response received from the server was invalid. |
| INVALID_PDU = 0x4; |
| |
| /// This attribute requires authentication, but the client is not authenticated. |
| INSUFFICIENT_AUTHENTICATION = 0x5; |
| |
| /// Indicates that the offset used in a read or write request exceeds the |
| /// bounds of the value. |
| /// |
| /// This may be returned by a LocalService method. |
| INVALID_OFFSET = 0x7; |
| |
| /// This attribute requires authorization, but the client is not authorized. |
| INSUFFICIENT_AUTHORIZATION = 0x8; |
| |
| /// This attribute requires a connection encrypted by a larger encryption key. |
| INSUFFICIENT_ENCRYPTION_KEY_SIZE = 0xC; |
| |
| /// Indicates that the value given in a write request would exceed the maximum |
| /// length allowed for the destionation characteristic or descriptor. |
| /// |
| /// This may be returned by a LocalService method. |
| INVALID_ATTRIBUTE_VALUE_LENGTH = 0xD; |
| |
| /// A general error occurred that can not be classified as one of the more |
| /// specific errors. |
| /// |
| /// This may be returned by a LocalService method. |
| UNLIKELY_ERROR = 0xE; |
| |
| /// This attribute requires encryption, but the connection is not encrypted. |
| INSUFFICIENT_ENCRYPTION = 0xF; |
| |
| /// The server had insufficient resources to complete the task. |
| /// |
| /// This may be returned by a LocalService method. |
| INSUFFICIENT_RESOURCES = 0x11; |
| |
| /// The value was not allowed. |
| /// |
| /// This may be returned by a LocalService method. |
| VALUE_NOT_ALLOWED = 0x13; |
| |
| // Application Errors |
| |
| /// Application Errors. The uses of these are specified at the application |
| /// level. |
| /// |
| /// These may all be returned by a LocalService method. |
| APPLICATION_ERROR_80 = 0x80; |
| APPLICATION_ERROR_81 = 0x81; |
| APPLICATION_ERROR_82 = 0x82; |
| APPLICATION_ERROR_83 = 0x83; |
| APPLICATION_ERROR_84 = 0x84; |
| APPLICATION_ERROR_85 = 0x85; |
| APPLICATION_ERROR_86 = 0x86; |
| APPLICATION_ERROR_87 = 0x87; |
| APPLICATION_ERROR_88 = 0x88; |
| APPLICATION_ERROR_89 = 0x89; |
| APPLICATION_ERROR_8A = 0x8A; |
| APPLICATION_ERROR_8B = 0x8B; |
| APPLICATION_ERROR_8C = 0x8C; |
| APPLICATION_ERROR_8D = 0x8D; |
| APPLICATION_ERROR_8E = 0x8E; |
| APPLICATION_ERROR_8F = 0x8F; |
| APPLICATION_ERROR_90 = 0x90; |
| APPLICATION_ERROR_91 = 0x91; |
| APPLICATION_ERROR_92 = 0x92; |
| APPLICATION_ERROR_93 = 0x93; |
| APPLICATION_ERROR_94 = 0x94; |
| APPLICATION_ERROR_95 = 0x95; |
| APPLICATION_ERROR_96 = 0x96; |
| APPLICATION_ERROR_97 = 0x97; |
| APPLICATION_ERROR_98 = 0x98; |
| APPLICATION_ERROR_99 = 0x99; |
| APPLICATION_ERROR_9A = 0x9A; |
| APPLICATION_ERROR_9B = 0x9B; |
| APPLICATION_ERROR_9C = 0x9C; |
| APPLICATION_ERROR_9D = 0x9D; |
| APPLICATION_ERROR_9E = 0x9E; |
| APPLICATION_ERROR_9F = 0x9F; |
| |
| // Common Profile and Service Error Codes |
| |
| /// Write request was rejected at the profile or service level. |
| WRITE_REQUEST_REJECTED = 0xFC; |
| |
| /// The Client Characteristic Configuration Descriptor was improperly |
| /// configured. |
| CCC_DESCRIPTOR_IMPROPERLY_CONFIGURED = 0xFD; |
| |
| /// Profile or service procedure already in progress. |
| PROCEDURE_ALREADY_IN_PROGRESS = 0xFE; |
| |
| /// A value was out of range at the profile or service level. |
| OUT_OF_RANGE = 0xFF; |
| |
| // Errors not specified by Bluetooth. |
| |
| /// One or more of the FIDL call parameters are invalid. See the parameter |
| /// documentation. |
| INVALID_PARAMETERS = 0x101; |
| |
| /// Indicates that more results were read than can fit in a FIDL response. |
| /// Consider reading attributes individually. |
| TOO_MANY_RESULTS = 0x102; |
| }; |
| |
| /// Errors that can occur during service publication. |
| type PublishServiceError = flexible enum { |
| /// The provided LocalService client_end was not a valid instance of the protocol. |
| INVALID_LOCAL_SERVICE = 1; |
| /// The service handle is invalid or already in use on the Server publishing the service. |
| INVALID_SERVICE_HANDLE = 2; |
| /// Invalid service UUID provided. |
| INVALID_UUID = 3; |
| /// The `ServiceInfo.characteristics` field was formatted invalidly or missing. If the service |
| /// is meant to be empty, the vector should be empty, but present. |
| INVALID_CHARACTERISTICS = 4; |
| /// A general error occurred that can not be classified as one of the more specific errors. |
| UNLIKELY_ERROR = 5; |
| }; |
| |
| // A Handle uniquely identifies a characteristic or descriptor. |
| type Handle = struct { |
| value uint64; |
| }; |
| |
| // A ServiceHandle uniquely identifies a GATT service within a particular scope. |
| type ServiceHandle = struct { |
| value uint64; |
| }; |
| |
| /// The kind ("type") of a GATT Service as outlined in Bluetooth Core Spec v5.3 Vol. 1 Part A 6.5.1. |
| type ServiceKind = strict enum { |
| /// A "service that provides functionality of a device that can be used on its own" (Ibid) |
| PRIMARY = 1; |
| /// A "service that provides additional functionality [...] in association with a primary |
| /// service and is included from at least one primary service" (Ibid) |
| SECONDARY = 2; |
| }; |
| |
| /// 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. If not present or |
| /// false, this attribute permits unencrypted access. |
| 1: encryption_required bool; |
| |
| /// If true, the physical link must be authenticated to access this attribute. If not present or |
| /// false, this attribute permits unauthenticated access. |
| 2: authentication_required bool; |
| |
| /// If true, the client needs to be authorized to access this attribute. If not present or |
| /// false, this attribute permits access without authorization. |
| 3: authorization_required bool; |
| }; |
| |
| /// Specifies the access permissions for a specific attribute value. |
| type AttributePermissions = table { |
| /// Specifies whether an attribute has the read permission. If not present, |
| /// 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 an attribute has the write permission. If not present, |
| /// the attribute value cannot be written. Otherwise, it can 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 must be present. Otherwise, this field |
| /// must not be present. |
| /// |
| /// 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 { |
| /// Unique identifier for this GATT service. |
| /// Always present if this represents a remote service, in which case this is unique across the |
| /// Client that returned this ServiceInfo. |
| /// Required for local services, in which case this must be unique across all services published |
| /// to a single Server instance. Can be used in the `ServiceInfo.includes` of other |
| /// PublishService calls to the Server where this service is published. |
| 1: handle ServiceHandle; |
| |
| /// Indicates whether this is a primary or secondary service. |
| /// Always present for remote services. Optional for local services |
| /// Default: ServiceKind::PRIMARY |
| 2: kind ServiceKind; |
| |
| /// The UUID that identifies the type of this service. |
| /// There may be multiple services with the same UUID. |
| /// Always present for remote services. Required for local services. |
| 3: type bt.Uuid; |
| |
| /// The characteristics of this service. |
| /// Required for local services. Never present for remote services. |
| 4: characteristics vector<Characteristic>:MAX_CHARACTERISTIC_COUNT; |
| |
| /// Handles of other services that are included by this service. |
| /// Optional for local services. Never present for remote services. |
| /// TODO(fxbug.dev/685): This is not currently supported for local services. |
| 5: includes vector<ServiceHandle>: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 not be present 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 not be present 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; |
| }; |