fuchsia.bluetooth.gatt

Added: 7

PROTOCOLS

Client

Defined in fuchsia.bluetooth.gatt/client.fidl

ConnectToService

Connects the RemoteService with the given identifier.

Request

NameType
id uint64
service server_end<RemoteService>

ListServices

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().

Request

NameType
uuids vector<string>?

Response

NameType
status fuchsia.bluetooth/Status
services vector<ServiceInfo>[65535]

LocalService

Defined in fuchsia.bluetooth.gatt/server.fidl

Interface for communicating with a published service.

NotifyValue

Sends a notification carrying the value of the characteristic with the given characteristic_id to the device with peer_id.

If confirm is true, then this method sends an indication instead. If the peer fails to confirm the indication, the link between the peer and the local adapter will be closed.

This method has no effect if the peer has not enabled notifications or indications on the requested characteristic.

Request

NameType
characteristic_id uint64
peer_id fuchsia.bluetooth/PeerIdString
value vector<uint8>
confirm bool

RemoveService

Removes the service that this interface instance corresponds to. Does nothing if the service is already removed.

Request

<EMPTY>

LocalServiceDelegate

Defined in fuchsia.bluetooth.gatt/server.fidl

Interface for responding to requests on a local service.

OnCharacteristicConfiguration

Notifies the delegate when a remote device with peer_id enables or disables notifications or indications on the characteristic with the given characteristic_id.

Request

NameType
characteristic_id uint64
peer_id fuchsia.bluetooth/PeerIdString
notify bool
indicate bool

OnReadValue

Called when a remote device issues a request to read the value of the of the characteristic or descriptor with given identifier. The delegate must respond to the request by returning the characteristic value. If the read request resulted in an error it should be returned in error_code. On success, error_code should be set to NO_ERROR and a value should be provided.

Request

NameType
id uint64
offset int32

Response

NameType
value vector<uint8>?
status ErrorCode

OnWriteValue

Called when a remote device issues a request to write the value of the characteristic or descriptor with the given identifier.

Request

NameType
id uint64
offset uint16
value vector<uint8>

Response

NameType
status ErrorCode

OnWriteWithoutResponse

Called when a remote device issues a request to write the value of the characteristic with the given identifier. This can be called on a characteristic with the WRITE_WITHOUT_RESPONSE property.

Request

NameType
id uint64
offset uint16
value vector<uint8>

RemoteService

Defined in fuchsia.bluetooth.gatt/client.fidl

DiscoverCharacteristics

Returns the characteristics and characteristic descriptors that belong to this service.

Request

<EMPTY>

Response

NameType
status fuchsia.bluetooth/Status
characteristics vector<Characteristic>[32767]

NotifyCharacteristic

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.

Request

NameType
id uint64
enable bool

Response

NameType
status fuchsia.bluetooth/Status

OnCharacteristicValueUpdated

Events: Called when a characteristic value notification or indication is received.

Response

NameType
id uint64
value vector<uint8>

ReadByType

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.

Request

NameType
uuid fuchsia.bluetooth/Uuid

Response

NameType
payload RemoteService_ReadByType_Result

ReadCharacteristic

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.

Request

NameType
id uint64

Response

NameType
status fuchsia.bluetooth/Status
value vector<uint8>

ReadDescriptor

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.

Request

NameType
id uint64

Response

NameType
status fuchsia.bluetooth/Status
value vector<uint8>

ReadLongCharacteristic

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.

Request

NameType
id uint64
offset uint16
max_bytes uint16

Response

NameType
status fuchsia.bluetooth/Status
value vector<uint8>[512]

ReadLongDescriptor

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.

Request

NameType
id uint64
offset uint16
max_bytes uint16

Response

NameType
status fuchsia.bluetooth/Status
value vector<uint8>

WriteCharacteristic

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.

Request

NameType
id uint64
value vector<uint8>

Response

NameType
status fuchsia.bluetooth/Status

WriteCharacteristicWithoutResponse

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.

Request

NameType
id uint64
value vector<uint8>

WriteDescriptor

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).

Request

NameType
id uint64
value vector<uint8>

Response

NameType
status fuchsia.bluetooth/Status

WriteLongCharacteristic

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.

Request

NameType
id uint64
offset uint16
value vector<uint8>[512]
write_options WriteOptions

Response

NameType
status fuchsia.bluetooth/Status

WriteLongDescriptor

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.

Request

NameType
id uint64
offset uint16
value vector<uint8>[512]

Response

NameType
status fuchsia.bluetooth/Status

Server

Defined in fuchsia.bluetooth.gatt/server.fidl

PublishService

Publishes the given service so that it is available to all remote peers. A LocalServiceDelegate must be provided over which to receive service requests.

The caller must assign distinct identifiers to the characteristics and descriptors listed in info. These identifiers will be used in requests sent to delegate.

service can be used to interact with the pubished service. If this service cannot be published then the handle for service will be closed.

Returns the success or failure status of the call and a unique identifier that can be used to unregister the service.

Request

NameType
info ServiceInfo
delegate LocalServiceDelegate
service server_end<LocalService>

Response

NameType
status fuchsia.bluetooth/Status

STRUCTS

AttributePermissions

Defined in fuchsia.bluetooth.gatt/types.fidl

Specifies the access permissions for a specific attribute value.

FieldTypeDescriptionDefault
read SecurityRequirements?

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 Permissions struct are satisfied.

No default
write 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 Permissions struct are satisfied.

No default
update 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.

No default

Characteristic

Defined in fuchsia.bluetooth.gatt/types.fidl

Represents a local or remote GATT characteristic.

FieldTypeDescriptionDefault
id uint64

Uniquely identifies this characteristic within a service.

No default
type fuchsia.bluetooth/UuidString

The 128-bit UUID that identifies the type of this characteristic. This is a string in the canonical 8-4-4-4-12 format.

No default
properties uint32

The characteristic properties bitfield. See kProperty* above for possible values.

No default
permissions AttributePermissions?

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.

No default
descriptors vector<Descriptor>[65532]?

The descriptors of this characteristic.

No default

Descriptor

Defined in fuchsia.bluetooth.gatt/types.fidl

Represents a local or remote GATT characteristic descriptor.

FieldTypeDescriptionDefault
id uint64

Uniquely identifies this descriptor within the characteristic that it belongs to.

No default
type fuchsia.bluetooth/UuidString

The 128-bit UUID that identifies the type of this descriptor. This is a string in the canonical 8-4-4-4-12 format.

No default
permissions AttributePermissions?

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.

No default

RemoteService_ReadByType_Response

Defined in fuchsia.bluetooth.gatt/client.fidl

FieldTypeDescriptionDefault
results vector<ReadByTypeResult>[189] No default

SecurityRequirements

Defined in fuchsia.bluetooth.gatt/types.fidl

Represents encryption, authentication, and authorization permissions that can be assigned to a specific access permission.

FieldTypeDescriptionDefault
encryption_required bool

If true, the physical link must be encrypted to access this attribute.

No default
authentication_required bool

If true, the physical link must be authenticated to access this attribute.

No default
authorization_required bool

If true, the client needs to be authorized before accessing this attribute.

No default

ServiceInfo

Defined in fuchsia.bluetooth.gatt/types.fidl

Represents a local or remote GATT service.

FieldTypeDescriptionDefault
id uint64

Uniquely identifies this GATT service. This value will be ignored for local services. Remote services will always have an identifier.

No default
primary bool

Indicates whether this is a primary or secondary service.

No default
type fuchsia.bluetooth/UuidString

The 128-bit UUID that identifies the type of this service. This is a string in the canonical 8-4-4-4-12 format.

No default
characteristics vector<Characteristic>[32767]?

The characteristics of this service.

No default
includes vector<uint64>[65535]?

Ids of other services that are included by this service.

No default

ENUMS

Error strict

Type: uint32

Defined in fuchsia.bluetooth.gatt/types.fidl

Errors that are returned by bluetooth.gatt methods.

NameValueDescription
1

A general error occurred that can not be classified as one of the more specific statuses.

2

Indicates that the response received from the server was invalid.

3

Indicates that more results were read than can fit in a FIDL response. Consider reading attributes individually.

4

This attribute requires authorization, but the client is not authorized.

5

This attribute requires authentication, but the client is not authenticated.

6

This attribute requires a connection encrypted by a larger encryption key.

7

This attribute requires encryption, but the connection is not encrypted.

8

This attribute is not readable.

ErrorCode strict

Type: uint32

Defined in fuchsia.bluetooth.gatt/types.fidl

Codes that can be returned in the protocol_error_code field of a bluetooth.Error.

NameValueDescription
0

Indicates that the operation was successful.

1

Indicates that the offset used in a read or write request exceeds the bounds of the value.

2

Indicates that the value given in a write request would exceed the maximum length allowed for the destionation characteristic or descriptor.

3

Indicates that a read or write request is not permitted.

ReliableMode strict

Type: uint32

Defined in fuchsia.bluetooth.gatt/types.fidl

Represents the reliability mode during long and prepared write operations.

If enabled, 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.

NameValueDescription
1
2

TABLES

ReadByTypeResult

Defined in fuchsia.bluetooth.gatt/client.fidl

OrdinalFieldTypeDescription
id uint64

Characteristic or descriptor id.

value vector<uint8>[253]

Truncated value of characteristic or descriptor, if it was read successfully.

error Error

Reason the value could not be read, if reading it resulted in an error.

WriteOptions

Defined in fuchsia.bluetooth.gatt/types.fidl

Represents the supported options to write a characteristic value to a server.

OrdinalFieldTypeDescription
reliable_mode ReliableMode

The reliable mode of the write operation.

Defaults to fuchsia.bluetooth.gatt/ReliableMode.DISABLED if not present.

UNIONS

RemoteService_ReadByType_Result strict

Defined in fuchsia.bluetooth.gatt/client.fidl

OrdinalVariantTypeDescription
response RemoteService_ReadByType_Response
err Error

CONSTANTS

NameValueTypeDescription
MAX_ATTRIBUTE_COUNT 65535 uint16
MAX_CHARACTERISTIC_COUNT 32767 uint16
MAX_DESCRIPTOR_COUNT 65532 uint16
MAX_READ_BY_TYPE_RESULTS 189 uint16
MAX_READ_BY_TYPE_VALUE_LENGTH 253 uint16
MAX_SERVICE_COUNT MAX_ATTRIBUTE_COUNT uint16
MAX_VALUE_LENGTH 512 uint16
kPropertyAuthenticatedSignedWrites 64 uint32
kPropertyBroadcast 1 uint32

Possible values for the characteristic properties bitfield. These specify the GATT procedures that are allowed for a particular characteristic.

kPropertyIndicate 32 uint32
kPropertyNotify 16 uint32
kPropertyRead 2 uint32
kPropertyReliableWrite 256 uint32
kPropertyWritableAuxiliaries 512 uint32
kPropertyWrite 8 uint32
kPropertyWriteWithoutResponse 4 uint32