Fuchsia.bluetooth.gatt

添加数量：7

协议

客户端

在 fuchsia.bluetooth.gatt/client.fidl 中定义

ConnectToService

使用指定标识符连接 RemoteService。

请求

名称类型
id uint64
service server_end<RemoteService>

列表服务

枚举在此客户端所代表的对等端上发现的服务。您可以通过在 uuids 中指定 UUID 列表来限制结果。返回的 ServiceInfo 结构将仅包含每项服务的基本信息，并且 characteristics 和 includes 字段将为 null。

为了与服务进一步交互，客户端必须通过调用 ConnectToService() 获取 RemoteService 句柄。

请求

名称类型
uuids vector<string>?

回复

名称类型
status fuchsia.bluetooth/Status
services vector<ServiceInfo>[65535]

LocalService 类中的方法

在 fuchsia.bluetooth.gatt/server.fidl 中定义

用于与已发布的服务进行通信的接口。

通知值

使用 peer_id 向设备发送包含具有给定 characteristic_id 的特征的 value 的通知。

如果 confirm 为 true，则此方法会改为发送指示。如果对等方未能确认指示，对等方与本地适配器之间的关联将关闭。

如果对等方尚未对请求的特征启用通知或指示，则此方法无效。

请求

名称类型
characteristic_id uint64
peer_id fuchsia.bluetooth/PeerIdString
value vector<uint8>
confirm bool

移除服务

移除此接口实例对应的服务。如果服务已被移除，则无需执行任何操作。

请求

<空>

LocalServiceDelegate

在 fuchsia.bluetooth.gatt/server.fidl 中定义

用于响应本地服务上的请求的接口。

OnCharacteristicConfiguration

当具有 peer_id 的远程设备启用或停用具有给定 characteristic_id 的特性的通知或指示时，通知委托。

请求

名称类型
characteristic_id uint64
peer_id fuchsia.bluetooth/PeerIdString
notify bool
indicate bool

OnReadValue

当远程设备发出读取具有指定标识符的特征或描述符值的请求时调用。代理必须通过返回特征值来响应请求。如果读取请求导致错误，它应该在 error_code 中返回。如果运行成功，应将 error_code 设置为 NO_ERROR，并提供 value。

请求

名称类型
id uint64
offset int32

回复

名称类型
value vector<uint8>?
status ErrorCode

OnWriteValue

当远程设备发出写入具有指定标识符的特征或描述符值的请求时调用。

请求

名称类型
id uint64
offset uint16
value vector<uint8>

回复

名称类型
status ErrorCode

OnWriteWithoutResponse

当远程设备发出写入具有指定标识符的特征值的请求时调用。可以使用 WRITE_WITHOUT_CHILD 属性对特征进行调用。

请求

名称类型
id uint64
offset uint16
value vector<uint8>

远程服务

在 fuchsia.bluetooth.gatt/client.fidl 中定义

DiscoverCharacteristics

返回属于此服务的特性和特征描述符。

请求

<空>

回复

名称类型
status fuchsia.bluetooth/Status
characteristics vector<Characteristic>[32767]

NotificationsCharacteristic

订阅或退订具有给定 id 的特征的通知/指示。如果 enable 为 true，系统将启用通知或指示；如果 enable 为 false 且已为此客户端启用通知或指示，则系统会停用通知或指示。

通知或指示将根据特征属性启用。最好使用指示（如果受支持）。

如果特征没有“notify”或“Indic”属性，此操作就会失败。

如果请求包含客户端特征配置描述符，系统会发出写入请求来配置通知/指示的特征。如果写入描述符时出错，此方法将失败。

成功后，每当对等方发送通知或指示时，系统都会发送 OnCharacteristicValueUpdated 事件。本地主机将自动确认指示。

请求

名称类型
id uint64
enable bool

回复

名称类型
status fuchsia.bluetooth/Status

OnCharacteristicValueUpdated

事件：在收到特征值通知或指示时调用。

回复

名称类型
id uint64
value vector<uint8>

ReadByType

读取具有给定 uuid 的特征和描述符。如果未读取任何值，results 将为空。如果读取某个值导致权限错误，则句柄和错误将包含在 results 中。

注意：results 中的值将截断为 MAX_READ_BY_TYPE_VALUE_LENGTH 个字节。应使用 ReadCharacteristic、ReadLongCharacteristic()、ReadDescriptor 或 ReadLongDescriptor() 读取完整的值。

此方法有助于在发现完成之前读取值，从而缩短延迟时间。

请求

名称类型
uuid fuchsia.bluetooth/Uuid

回复

名称类型
payload RemoteService_ReadByType_Result

读取特性

使用 id 读取特征的值，并在回复中返回该值。如果 status 表示出现错误，value 将为空。

如果特征具有长值（即大于当前 MTU），则此方法将仅返回该值的前 (MTU - 1) 个字节。使用 ReadLongCharacteristic() 读取更大的值，或从非零偏移量开始读取。

请求

名称类型
id uint64

回复

名称类型
status fuchsia.bluetooth/Status
value vector<uint8>

ReadDescriptor

使用 id 读取特征描述符的值，并在回复中返回该值。如果 status 指示错误，则可以忽略 value。

如果描述符有一个长值（即大于当前 MTU），则此方法将仅返回该值的前 (MTU - 1) 个字节。使用 ReadLongDescriptor() 读取较大的值，或从非零偏移量开始读取。

请求

名称类型
id uint64

回复

名称类型
status fuchsia.bluetooth/Status
value vector<uint8>

ReadLongCharacteristic

读取具有指定 id 的特征的完整值。如果已知特征具有无法在单个请求中读取的值，则应采用此过程。

从指定的 offset 开始，最多返回特征值的 max_bytes 个八位字节。

如果出现以下情况，则可能会返回错误： a. max_bytes 为 0； b. offset 无效； c. 特征没有长值； d. 服务器不支持长时间读取过程。

请求

名称类型
id uint64
offset uint16
max_bytes uint16

回复

名称类型
status fuchsia.bluetooth/Status
value vector<uint8>[512]

ReadLongDescriptor

读取具有给定 id 的特征描述符的完整值。如果已知该描述符的某个值无法在单个请求中读取，则应使用此过程。

从指定的 offset 开始，最多返回特征值的 max_bytes 个八位字节。

如果出现以下情况，则可能会返回错误： a. max_bytes 为 0； b. offset 无效； c. 服务器不支持长时间读取过程。

请求

名称类型
id uint64
offset uint16
max_bytes uint16

回复

名称类型
status fuchsia.bluetooth/Status
value vector<uint8>

写入特征

使用 id 将 value 写入特征。如果出现以下情况，此操作可能会返回错误： a. value 的大小超出了当前 MTU。 b.id 引用的特性没有“write”属性。

请求

名称类型
id uint64
value vector<uint8>

回复

名称类型
status fuchsia.bluetooth/Status

WriteCharacteristicWithoutResponse 中

使用 id 将 value 写入特征，而不请求对等方的确认。此方法没有响应，也无法确认其传送情况。

请求

名称类型
id uint64
value vector<uint8>

写入描述符

使用 id 将 value 写入特征描述符。如果出现以下情况，此操作可能会返回错误： a. value 的大小超出了当前 MTU。 b.id 是指内部预留的描述符类型（例如客户端特征配置描述符）。

请求

名称类型
id uint64
value vector<uint8>

回复

名称类型
status fuchsia.bluetooth/Status

WriteLongCharacteristic

使用提供的 write_options 从 offset 开始，使用 id 将 value 写入特征。

如果要写入的值过长，不适合单个请求，或者需要按偏移值写入，则应采用此过程。如果出现以下情况，则可能会返回错误： a. offset 无效； b. 服务器不支持较长的写入过程。

长写入需要向远程服务发送多条消息，并且执行时间比短写入更长。不建议在对同一 ID 和数据范围进行长写入时发送短写入。此函数的响应顺序表示远程服务接收响应的顺序，不一定是调用它的顺序。

请求

名称类型
id uint64
offset uint16
value vector<uint8>[512]
write_options WriteOptions

回复

名称类型
status fuchsia.bluetooth/Status

WriteLongDescriptor

使用 id 将 value 写入特征描述符，从 offset 开始。如果要写入的值过长，不适合单个请求，或者需要按偏移值写入，则应采用此过程。如果出现以下情况，则可能会返回错误： a. offset 无效； b. 服务器不支持较长的写入过程。 c.id 是指内部预留的描述符类型（例如客户端特征配置描述符）。

长写入需要向远程服务发送多条消息，并且执行时间比短写入更长。不建议在对同一 ID 和数据范围进行长写入时发送短写入。此函数的响应顺序表示远程服务接收响应的顺序，不一定是调用它的顺序。

请求

名称类型
id uint64
offset uint16
value vector<uint8>[512]

回复

名称类型
status fuchsia.bluetooth/Status

服务器

在 fuchsia.bluetooth.gatt/server.fidl 中定义

PublishService

发布给定服务，使其可供所有远程对等方使用。必须提供 LocalServiceDelegate 才能接收服务请求。

调用方必须为 info 中列出的特征和描述符分配不同的标识符。这些标识符将用于发送到 delegate 的请求。

service 可用于与发布的服务交互。如果无法发布此服务，则 service 的句柄将关闭。

返回调用的成功或失败状态以及可用于取消注册服务的唯一标识符。

请求

名称类型
info ServiceInfo
delegate LocalServiceDelegate
service server_end<LocalService>

回复

名称类型
status fuchsia.bluetooth/Status

结构

AttributePermissions

在 fuchsia.bluetooth.gatt/types.fidl 中定义

指定对特定属性值的访问权限。

字段类型说明默认
read SecurityRequirements?

指定某个属性是否具有读取权限。如果为 null，则无法读取属性值。否则，只有在满足 Permissions 结构体中指定的权限时，才能读取该 ID。

 无默认值
write SecurityRequirements?

指定某个属性是否具有写入权限。如果为 null，则无法写入属性值。否则，仅在满足 Permissions 结构体中指定的权限时写入数据。

 无默认值
update SecurityRequirements?

指定客户端要订阅某个特征的通知或指示的安全要求。特征是否支持通知或指示是使用 NOTIFY 和 INDICATE 特征属性指定的。如果局部特征具有其中一个属性，则此字段不能为 null。否则，此字段必须保留为 null。

对于描述符，将忽略此字段。

 无默认值

特征

在 fuchsia.bluetooth.gatt/types.fidl 中定义

表示本地或远程 GATT 特征。

字段类型说明默认
id uint64

此特征在服务中的唯一标识符。

 无默认值
type fuchsia.bluetooth/UuidString

用于标识此特征类型的 128 位 UUID。这是一个采用规范 8-4-4-4-12 格式的字符串。

 无默认值
properties uint32

特征属性位字段。请参阅上文的 kProperty* 了解可能的值。

 无默认值
permissions AttributePermissions?

此特征的属性权限。对于远程特性，此值将为 null，直到通过读取和写入请求发现权限为止。

对于本地特征，此值是必填项。

 无默认值
descriptors vector<Descriptor>[65532]?

此特征的描述符。

 无默认值

Descriptor

在 fuchsia.bluetooth.gatt/types.fidl 中定义

表示本地或远程 GATT 特征描述符。

字段类型说明默认
id uint64

此描述符在所属特征中唯一标识。

 无默认值
type fuchsia.bluetooth/UuidString

用于标识此描述符类型的 128 位 UUID。这是一个采用规范 8-4-4-4-12 格式的字符串。

 无默认值
permissions AttributePermissions?

此描述符的属性权限。对于远程描述符，此值将为 null，直到通过读取和写入请求发现权限为止。

对于本地描述符，此值为必填值。

 无默认值

RemoteService_ReadByType_Response

在 fuchsia.bluetooth.gatt/client.fidl 中定义

字段类型说明默认
results vector<ReadByTypeResult>[189] 无默认值

安全性要求

在 fuchsia.bluetooth.gatt/types.fidl 中定义

表示可分配给特定访问权限的加密、身份验证和授权权限。

字段类型说明默认
encryption_required bool

如果为 true，则必须对实体链接进行加密才能访问此属性。

 无默认值
authentication_required bool

如果为 true，则物理链接必须通过身份验证才能访问此属性。

 无默认值
authorization_required bool

如果为 true，则需要先对客户端授权，然后才能访问此属性。

 无默认值

服务信息

在 fuchsia.bluetooth.gatt/types.fidl 中定义

表示本地或远程 GATT 服务。

字段类型说明默认
id uint64

此 GATT 服务的唯一标识符。对于本地服务，系统会忽略此值。远程服务将始终具有标识符。

 无默认值
primary bool

指明这是主要服务还是辅助服务。

 无默认值
type fuchsia.bluetooth/UuidString

用于标识此服务类型的 128 位 UUID。这是一个采用规范 8-4-4-4-12 格式的字符串。

 无默认值
characteristics vector<Characteristic>[32767]?

此服务的特征。

 无默认值
includes vector<uint64>[65535]?

此服务包含的其他服务的 ID。

 无默认值

枚举

错误严格

类型：uint32

在 fuchsia.bluetooth.gatt/types.fidl 中定义

bluetooth.gatt 方法返回的错误。

名称值说明
1

发生了无法归类为某一更具体的状态的常规错误。
2

表示从服务器收到的响应无效。
3

表示读取的结果数超出了 FIDL 响应可容纳的数量。请考虑单独读取属性。
4

此属性需要授权，但客户端未获得授权。
5

此属性要求进行身份验证，但客户端未进行身份验证。
6

此属性要求连接由较大的加密密钥加密。
7

此属性需要加密，但连接未加密。
8

此属性不可读。

ErrorCode 严格

类型：uint32

在 fuchsia.bluetooth.gatt/types.fidl 中定义

可在 bluetooth.Error 的 protocol_error_code 字段中返回的代码。

名称值说明
0

表示操作成功。
1

表示读取或写入请求中使用的偏移量超出了值的边界。
2

表示写入请求中给定的值会超过目的地特征或描述符允许的最大长度。
3

表示不允许执行读取或写入请求。

ReliableMode 严格

类型：uint32

在 fuchsia.bluetooth.gatt/types.fidl 中定义

表示长时间的准备写入操作期间的可靠性模式。

启用后，系统会根据服务器的 echo 响应验证每个值 blob。如果值 blob 未可靠地传送到对等端，则该过程会被取消。

名称值说明
1
2

表格

ReadByTypeResult

在 fuchsia.bluetooth.gatt/client.fidl 中定义

序数字段类型说明
id uint64

特征或描述符 ID。
value vector<uint8>[253]

特征或描述符的截断值（如果读取成功）。
error Error

无法读取值的原因（如果读取该值会导致错误）。

WriteOptions

在 fuchsia.bluetooth.gatt/types.fidl 中定义

表示支持的选项，用于将特征值写入服务器。

序数字段类型说明
reliable_mode ReliableMode

写入操作的可靠模式。

如果不存在，则默认为 fuchsia.bluetooth.gatt/ReliableMode.DISABLED。

联合

RemoteService_ReadByType_Result 严格

在 fuchsia.bluetooth.gatt/client.fidl 中定义

序数变体类型说明
response RemoteService_ReadByType_Response
err Error

常量

名称值类型说明
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

特征属性位字段的可能值。这些属性用于指定特定特性允许使用的 GATT 流程。
kPropertyIndicate 32 uint32
kPropertyNotifications 16 uint32
kPropertyRead 2 uint32
kPropertyReliableWrite 256 uint32
kPropertyWritableAuxiliaries 512 uint32
kPropertyWrite 8 uint32
kPropertyWriteWithoutResponse 4 uint32