Share via

bluetoothGATTSetCharacteristicValue 函式 (bluetoothleapis.h)

  • 發行項

BluetoothGATTSetCharacteristicValue函式會將指定的特性值寫入藍牙裝置。

語法

HRESULT BluetoothGATTSetCharacteristicValue(
  [in]           HANDLE                             hDevice,
  [in]           PBTH_LE_GATT_CHARACTERISTIC        Characteristic,
  [in]           PBTH_LE_GATT_CHARACTERISTIC_VALUE  CharacteristicValue,
  [in, optional] BTH_LE_GATT_RELIABLE_WRITE_CONTEXT ReliableWriteContext,
  [in]           ULONG                              Flags
);

參數

[in] hDevice

服務控制碼。

[in] Characteristic

包含父特性 之BTH_LE_GATT_CHARACTERISTIC 結構的指標。

[in] CharacteristicValue

包含特性值的 BTH_LE_GATT_CHARACTERISTIC_VALUE 結構的指標。

[in, optional] ReliableWriteContext

BTH_LE_GATT_RELIABLE_WRITE_CONTEXT 結構，其中包含描述從先前呼叫 BluetoothGATTBeginReliableWrite傳回之可靠寫入作業的內容。

[in] Flags

用來修改 BluetoothGATTSetCharacteristicValue 行為的旗標：

旗標 描述
BLUETOOTH_GATT_FLAG_NONE 用戶端沒有特定的 GATT 需求， (預設) 。
BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED 用戶端會要求透過加密通道傳輸的資料。
BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED 用戶端會要求透過已驗證通道傳輸的資料。
BLUETOOTH_GATT_FLAG_WRITE_WITHOUT_RESPONSE 沒有回應的寫入。
BLUETOOTH_GATT_FLAG_SIGNED_WRITE 帶正負號的寫入。 設定檔驅動程式必須與 BLUETOOTH_GATT_FLAG_WRITE_WITHOUT_RESPONSE 搭配使用，才能在沒有回應的情況下產生已簽署的寫入。

傳回值

BluetoothGATTSetCharacteristicValue函式會傳回下列值：

傳回碼 描述
S_OK
 作業已成功完成。
ERROR_ACCESS_DENIED
 如果同時提供父服務與服務控制碼，且服務階層不會匯總至提供的父服務控制碼，則會傳回 。
ERROR_INVALID_PARAMETER
 參數無效。
ERROR_BAD_NET_RESP
 目標伺服器未提供適當的網路回應。
ERROR_SEM_TIMEOUT
 要求逾時。
ERROR_NO_SYSTEM_RESOURCES
 作業記憶體不足。
ERROR_INVALID_FUNCTION
 可靠的寫入作業目前正在進行中。
E_BLUETOOTH_ATT_INVALID_HANDLE
 指定的屬性控制碼在此伺服器上無效。
E_BLUETOOTH_ATT_READ_NOT_PERMITTED
 無法讀取屬性。
E_BLUETOOTH_ATT_WRITE_NOT_PERMITTED
 無法寫入屬性。
E_BLUETOOTH_ATT_INVALID_PDU
 PDU 屬性無效。
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHENTICATION
 屬性需要驗證，才能讀取或寫入。
E_BLUETOOTH_ATT_REQUEST_NOT_SUPPORTED
 屬性伺服器不支援從用戶端收到的要求。
E_BLUETOOTH_ATT_INVALID_OFFSET
 指定的位移超過屬性的結尾。
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHORIZATION
 屬性需要授權，才能讀取或寫入。
E_BLUETOOTH_ATT_PREPARE_QUEUE_FULL
 太多準備寫入已排入佇列。
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_FOUND
 在指定的屬性控制碼範圍內找不到任何屬性。
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_LONG
 屬性無法使用讀取 Blob 要求來讀取或寫入。
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE
 用於加密此連結的加密金鑰大小不足。
E_BLUETOOTH_ATT_INVALID_ATTRIBUTE_VALUE_LENGTH
 屬性值長度對作業無效。
E_BLUETOOTH_ATT_UNLIKELY
 所要求的屬性要求發生不太可能的錯誤，因此無法如要求完成。
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION
 屬性需要加密，才能讀取或寫入。
E_BLUETOOTH_ATT_UNSUPPORTED_GROUP_TYPE
 屬性類型不是由較高層規格所定義的支援群組屬性。
E_BLUETOOTH_ATT_INSUFFICIENT_RESOURCES
 資源不足，無法完成要求。
E_BLUETOOTH_ATT_UNKNOWN_ERROR
 收到位於保留範圍中的錯誤。

備註

在BluetoothGATTBeginReliableWrite之後呼叫BluetoothGATTSetCharacteristicValue，通知遠端藍牙裝置將此要求儲存在裝置上的準備佇列中。

如果需要簽署，則作業不需回應，且不得透過安全通道進行。

父特性是從先前呼叫 BluetoothGATTGetCharacteristics傳回，而且不得改變。 如果呼叫端執行此動作，則行為未定義。

範例


BTH_LE_GATT_CHARACTERISTIC_VALUE newValue;

RtlZeroMemory(&newValue,(sizeof(newValue)));

newValue.DataSize = sizeof(valueData);
newValue.Data = (UCHAR*)&valueData;

// Set the new characteristic value
hr = BluetoothGATTSetCharacteristicValue(hDevice,
                                    parentCharacteristic,
                                    &newValue,
                                    NULL,
                                    BLUETOOTH_GATT_FLAG_NONE);

需求

   
最低支援的用戶端 Windows 8 和更新版本的 Windows 支援。
目標平台 Universal
標頭 bluetoothleapis.h
程式庫 BluetoothAPIs.lib
Dll BluetoothAPIs.dll

另請參閱

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_CHARACTERISTIC_VALUE