BluetoothGATTGetCharacteristicValue 関数 (bluetoothleapis.h)
BluetoothGATTGetCharacteristicValue 関数は、指定された特性の値を取得します。
構文
HRESULT BluetoothGATTGetCharacteristicValue(
[in] HANDLE hDevice,
[in] PBTH_LE_GATT_CHARACTERISTIC Characteristic,
[in] ULONG CharacteristicValueDataSize,
[out, optional] PBTH_LE_GATT_CHARACTERISTIC_VALUE CharacteristicValue,
[out, optional] USHORT *CharacteristicValueSizeRequired,
[in] ULONG Flags
);
パラメーター
[in] hDevice
サービスへのハンドル。
[in] Characteristic
取得する特性値の親特性へのポインター。
[in] CharacteristicValueDataSize
CharacteristicValue パラメーターに割り当てられたバイト数。
[out, optional] CharacteristicValue
特性値を返すバッファーへのポインター。
[out, optional] CharacteristicValueSizeRequired
CharacteristicValue が指すバッファーにデータを返すために必要なバイト数を格納するバッファーへのポインター。
[in] Flags
BluetoothGATTGetCharacteristicValue の動作を変更するためのフラグ:
| フラグ | 説明 |
|---|---|
| BLUETOOTH_GATT_FLAG_NONE | クライアントに特定の GATT 要件がありません (既定値)。 |
| BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED | クライアントは、暗号化されたチャネル経由でデータを送信するように要求します。 |
| BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED | クライアントは、認証されたチャネル経由でデータを送信するように要求します。 |
| BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE | 特性値は、デバイスから直接読み取られます。 これにより、キャッシュ内のキャッシュ内のファイルが既に存在する場合は上書きされます。 |
| BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE | 特性値は、キャッシュ内に存在するかどうかに関係なく、キャッシュから読み取られます。 |
戻り値
BluetoothGATTGetCharacteristicValue 関数は、次の値を返します。
| リターン コード | 説明 |
|---|---|
|
操作は正常に完了しました。 |
|
buffer パラメーターは NULL で、代わりに使用可能な項目の数が返されます。 |
|
親サービスとサービス ハンドルの両方が指定され、サービス階層が指定された親サービス ハンドルにロールアップされない場合に返されます。 |
|
CharacteristicValue と CharacteristicValueSizeRequired の両方が 0 です。 |
|
バッファーが指定されていますが、バッファー数のサイズは、必要なサイズよりもバイト単位で小さくなります。 |
|
キャッシュ内の現在のデータは矛盾しているように見え、内部エラーが発生しています。 |
|
ターゲット サーバーが適切なネットワーク応答を提供しませんでした。 |
|
要求がタイムアウトしました。 |
|
特性値は、特性プロパティによって指示されているように読み取りできません。 |
|
操作がメモリ不足でした。 |
|
指定された属性ハンドルがこのサーバーでは無効でした。 |
|
属性を読み取ることができません。 |
|
属性を書き込むことができません。 |
|
属性 PDU が無効です。 |
|
属性を読み取ったり書き込んだりするには、認証が必要です。 |
|
属性サーバーは、クライアントから受信した要求をサポートしていません。 |
|
指定されたオフセットが 属性の末尾を超えていました。 |
|
属性は、読み取りまたは書き込み前に承認が必要です。 |
|
キューに入れられていた準備書き込みが多すぎます。 |
|
指定された属性ハンドル範囲内に属性が見つかりません。 |
|
属性は、BLOB の読み取り要求を使用して読み取ったり書き込んだりすることはできません。 |
|
このリンクの暗号化に使用される暗号化キー サイズが不十分です。 |
|
操作の属性値の長さが無効です。 |
|
要求された属性要求で、可能性が低いエラーが発生したため、要求どおりに完了できませんでした。 |
|
属性は、読み取りまたは書き込み前に暗号化が必要です。 |
|
属性の種類は、上位レイヤー仕様で定義されている、サポートされているグループ化属性ではありません。 |
|
要求を完了するためのリソースが不足しています。 |
|
予約範囲内にあるエラーが受信されました。 |
注釈
特性値が既に存在する場合は、キャッシュから返されます。 これはほとんどの場合、ペアリングまたは関連付け時にすべてのデバイス属性がキャッシュされるためです。 ただし、存在しない場合、特性値はデバイスから直接読み取られ、デバイスから正常に読み取られるとキャッシュされます。 BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHEまたはBLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICEが存在する場合は、指定したメソッドを使用して特性値が読み取られます。
返される特性は、デバイスから特性を直接取得するとキャッシュされます。 サービス変更イベントを受信しない限り、返される特性の一覧は変更されるとは限りません。
プロファイル ドライバーでは、返される特性の配列に十分な大きさのバッファーを事前に割り当てる必要があります。 呼び出し元は、CharacteristicValueSizeRequired に NULL 以外の値を渡し、CharacteristicValue に NULL を渡すことで、必要なバッファー サイズを決定できます。
親サービスはキャッシュ内に存在する必要があります。そうしないと、関数は失敗します。 親サービスは、 BluetoothGATTGetServices または BluetoothGATTGetIncludedServices によって返されるサービスである必要があります。
例
if (currGattChar->IsReadable) {
////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Value Buffer Size
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetCharacteristicValue(
hCurrService,
currGattChar,
0,
NULL,
&charValueDataSize,
BLUETOOTH_GATT_FLAG_NONE);
if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
PrintHr("BluetoothGATTGetCharacteristicValue - Buffer Size", hr);
goto GetDescriptors; // Proceed to retrieving descriptors
}
pCharValueBuffer = (PBTH_LE_GATT_CHARACTERISTIC_VALUE)malloc(charValueDataSize);
if (NULL == pCharValueBuffer) {
printf("pCharValueBuffer out of memory\r\n");
goto Done;
} else {
RtlZeroMemory(pCharValueBuffer, charValueDataSize);
}
////////////////////////////////////////////////////////////////////////////
// Retrieve the Characteristic Value
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetCharacteristicValue(
hCurrService,
currGattChar,
(ULONG)charValueDataSize,
pCharValueBuffer,
NULL,
BLUETOOTH_GATT_FLAG_NONE);
if (S_OK != hr) {
PrintHr("BluetoothGATTGetCharacteristicValue - Actual Data", hr);
goto GetDescriptors; // Proceed to retrieving descriptors
}
PrintCharacteristicValue(pCharValueBuffer, 2, currGattChar->CharacteristicUuid);
// Free before going to next iteration, or memory leak.
free(pCharValueBuffer);
pCharValueBuffer = NULL;
}
必要条件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8 以降のバージョンの Windows でサポートされています。 |
| 対象プラットフォーム | ユニバーサル |
| Header | bluetoothleapis.h |
| Library | BluetoothAPIs.lib |
| [DLL] | BluetoothAPIs.dll |