fuchsia.bluetooth.gatt

已新增：7

專家

用戶端

定義於 fuchsia.bluetooth.gatt/client.fidl

ConnectTo 服務

連結 RemoteService 與指定的 ID。

要求

名稱類型
id uint64
service server_end<RemoteService>

ListServices

列出此用戶端代表的對等點找到的服務。您可以在 uuids 中指定 UUID 清單，藉此限制結果。傳回的 ServiceInfo 結構只會包含每項服務的基本資訊，characteristics 和 includes 欄位將為空值。

若要進一步與服務互動，用戶端必須透過呼叫 ConnectToService() 取得 RemoteService 控制代碼。

要求

名稱類型
uuids vector<string>?

回應

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

在地服務

定義於 fuchsia.bluetooth.gatt/server.fidl

用於與已發布的服務通訊的介面。

NotificationValue

使用 peer_id 將具備特性與指定 characteristic_id 的 value 傳送至裝置的通知。

如果 confirm 為 true，這個方法會改為傳送指示。如果對等端無法確認指標，則對等點和本機轉接程式之間的連結會關閉。

如果對等端並未針對要求的特性啟用通知或表示功能，這個方法就不會生效。

要求

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

移除服務

移除這個介面執行個體對應的服務。如果服務已移除，則不會有任何動作。

要求

<空白>

本機服務委派

定義於 fuchsia.bluetooth.gatt/server.fidl

用於回應「本機」服務要求的介面。

OnCharacteristicConfiguration

當具有 peer_id 的遠端裝置根據指定的 characteristic_id 啟用或停用與特性相關的通知或指示時，請通知委派對象。

要求

名稱類型
characteristic_id uint64
peer_id fuchsia.bluetooth/PeerIdString
notify bool
indicate bool

OnReadValue

當遠端裝置發出要求，讀取具有指定 ID 的特性或描述元值時，會呼叫此方法。委派項目必須傳回特性值來回應要求。如果讀取要求導致錯誤，則應在 error_code 中傳回。成功後，error_code 應設為 NO_ERROR，且應提供 value。

要求

名稱類型
id uint64
offset int32

回應

名稱類型
value vector<uint8>?
status ErrorCode

OnWriteValue

當遠端裝置發出要求，寫入具有指定 ID 的特性或描述元值時，會呼叫此方法。

要求

名稱類型
id uint64
offset uint16
value vector<uint8>

回應

名稱類型
status ErrorCode

OnWriteWithoutResponse

當遠端裝置發出要求，寫入具有指定 ID 的特性值時，會呼叫此方法。您可以在具有 WRITE_WITHOUT_response 屬性的特性上呼叫這個方法。

要求

名稱類型
id uint64
offset uint16
value vector<uint8>

遠端服務

定義於 fuchsia.bluetooth.gatt/client.fidl

探索特色

傳回屬於這項服務的特性和特性描述元。

要求

<空白>

回應

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

通知主題

使用指定的 id 訂閱或取消訂閱特性的通知/指示。如果 enable 為 true 或 enable 為 false，且已為該用戶端啟用通知或指示，則會啟用通知或指示。

系統會根據特性屬性啟用通知或指示。系統會優先使用指示 (如果支援的話)。

如果特性沒有「notify」或「indicate」屬性，此作業就會失敗。

如果其中包含用戶端特性設定描述元，系統會發出寫入要求來設定通知/指示的特性。如果寫入描述元時發生錯誤，此方法就會失敗。

如果成功的話，每當對等體傳送通知或指示時，就會傳送 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

ReadCharacteristic

使用 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]

讀取 LongDescriptor

使用指定的 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

寫入 LongCharacteristic

使用提供的 write_options，從 offset 開始，將 value 寫入具有 id 的特性。

如果要寫入的值太長，無法在單一要求中呈現，或必須以偏移值寫入，則應使用此程序。如果在下列情況中，這可能會傳回錯誤：offset 無效；b. 伺服器不支援長時間寫入程序。

長寫入作業需要多則訊息傳送至遠端服務，且執行時間比短寫入時間更長。當長時間寫入作業仍在相同的 ID 和資料範圍時，我們不建議傳送短寫入。這個函式的回應順序代表遠端服務接收回應的順序，不一定是呼叫順序。

要求

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

回應

名稱類型
status fuchsia.bluetooth/Status

寫入 LongDescriptor

將 value 寫入具有 id 的特性描述元 (從 offset 開始)。如果要寫入的值太長，無法納入單一要求，或需要在偏移值寫入，則應使用此程序。如果出現以下情況，這可能會傳回錯誤： a. offset 無效；b. 伺服器不支援長時間寫入程序。 c.id 是指內部保留的描述元類型 (例如用戶端特性設定描述元)。

長寫入作業需要多則訊息傳送至遠端服務，且執行時間比短寫入時間更長。當長時間寫入作業仍在相同的 ID 和資料範圍時，我們不建議傳送短寫入。這個函式的回應順序代表遠端服務接收回應的順序，不一定是呼叫順序。

要求

名稱類型
id uint64
offset uint16
value vector<uint8>[512]

回應

名稱類型
status fuchsia.bluetooth/Status

伺服器

定義於 fuchsia.bluetooth.gatt/server.fidl

發布服務

發布指定的服務，供所有遠端對等互連存取。必須提供 LocalService 委派，以便接收服務要求。

呼叫端必須將專屬 ID 指派給 info 中列出的特性和描述元。這些 ID 會用於傳送至 delegate 的要求。

service 可用來與已禁止的服務互動。如果無法發布這項服務，系統會關閉 service 的帳號代碼。

傳回呼叫的成功或失敗狀態，以及可用於取消註冊服務的專屬 ID。

要求

名稱類型
info ServiceInfo
delegate LocalServiceDelegate
service server_end<LocalService>

回應

名稱類型
status fuchsia.bluetooth/Status

結構

屬性權限

定義於 fuchsia.bluetooth.gatt/types.fidl

指定特定屬性值的存取權限。

欄位類型說明預設
read SecurityRequirements?

指定屬性是否具有讀取權限。如果為空值，系統將無法讀取屬性值。否則，只有在滿足權限結構中指定的權限時，才能讀取。

 無預設
write SecurityRequirements?

指定屬性是否具有寫入權限。如果為空值，則無法寫入屬性值。否則，只有在滿足權限結構中指定的權限時，才會寫入。

 無預設
update SecurityRequirements?

指定用戶端訂閱通知或指示特性的安全性要求。使用 NOTIFY 和 INDICATE 特性屬性，就能指定對通知或索引的特性支援。如果當地特性具有上述任一屬性，則這個欄位不得為空值。否則，這個欄位必須保留為空值。

系統會忽略此欄位。

 無預設

特色

定義於 fuchsia.bluetooth.gatt/types.fidl

代表本機或遠端 GATT 的特性。

欄位類型說明預設
id uint64

在服務中識別此特性。

 無預設
type fuchsia.bluetooth/UuidString

128 位元 UUID，可識別此特性的類型。這是標準 8-4-4-4-12 格式的字串。

 無預設
properties uint32

特性屬性位元欄位。如要瞭解可能的值，請參閱上方的 kProperty*。

 無預設
permissions AttributePermissions?

這個特性的屬性權限。對於遠端特性，此值將為空值，直到透過讀取和寫入要求發現權限為止。

如為地區性特徵，此為必填值。

 無預設
descriptors vector<Descriptor>[65532]?

這個特性的描述元。

 無預設

描述元

定義於 fuchsia.bluetooth.gatt/types.fidl

代表本機或遠端 GATT 的特性描述元。

欄位類型說明預設
id uint64

請在所屬的特性中明確識別這個描述元。

 無預設
type fuchsia.bluetooth/UuidString

128 位元 UUID，可識別此描述元的類型。這是標準 8-4-4-4-12 格式的字串。

 無預設
permissions AttributePermissions?

這個描述元的屬性權限。如果是遠端描述元，此值將為空值，直到透過讀取和寫入要求發現權限為止。

如果是本機描述元，此值是必填項目。

 無預設

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 服務。本機服務會忽略此值。遠端服務一律會有 ID。

 無預設
primary bool

用於表示這是主要或次要服務。

 無預設
type fuchsia.bluetooth/UuidString

128 位元 UUID，用於識別這項服務的類型。此為標準 8-4-4-4-12 格式的字串。

 無預設
characteristics vector<Characteristic>[32767]?

這項服務的特性。

 無預設
includes vector<uint64>[65535]?

這項服務內其他服務的 ID。

 無預設

表情符號

錯誤 strict 錯誤

類型：uint32

定義於 fuchsia.bluetooth.gatt/types.fidl

由 Bluetoothtooth.gatt 方法傳回的錯誤。

名稱值說明
1

發生一般錯誤，無法歸類為其中一種更具體的狀態。
2

表示從伺服器收到的回應無效。
3

表示讀取的結果數量超過 FIDL 回應所能容納的範圍。請考慮個別讀取屬性。
4

這項屬性需要授權，但用戶端未獲得授權。
5

這個屬性需要驗證，但用戶端未通過驗證。
6

這項屬性需要以較大型的加密金鑰加密的連線。
7

這項屬性需要加密，但連線未加密。
8

無法讀取這項屬性。

ErrorCode strict

類型：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

無法讀取值的原因 (如果讀取到發生錯誤)。

寫入選項

定義於 fuchsia.bluetooth.gatt/types.fidl

代表可將特性值寫入伺服器的支援選項。

序數欄位類型說明
reliable_mode ReliableMode

寫入作業的穩定模式。

如果沒有，則預設值為 fuchsia.bluetooth.gatt/ReliableMode.DISABLED。

聯合國

RemoteService_ReadByType_Result strict

定義於 fuchsia.bluetooth.gatt/client.fidl

序數Variant類型說明
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_結果 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