BluetoothGATTGetDescriptors 関数 (bluetoothleapis.h)
BluetoothGATTGetDescriptors 関数は、指定された特性で使用可能なすべての記述子を取得します。
構文
HRESULT BluetoothGATTGetDescriptors(
[in] HANDLE hDevice,
[in] PBTH_LE_GATT_CHARACTERISTIC Characteristic,
[in] USHORT DescriptorsBufferCount,
[out, optional] PBTH_LE_GATT_DESCRIPTOR DescriptorsBuffer,
[out] USHORT *DescriptorsBufferActual,
[in] ULONG Flags
);
パラメーター
[in] hDevice
Bluetooth デバイスまたはサービスを処理します。 サービス ハンドルが渡される場合、サービスは記述子の祖父母である必要があります。
[in] Characteristic
取得 BTH_LE_GATT_CHARACTERISTIC 記述子の親特性を含む構造体へのポインター。
[in] DescriptorsBufferCount
DescriptorsBuffer パラメーターに割り当てられた要素の数。
[out, optional] DescriptorsBuffer
記述子を返す BTH_LE_GATT_DESCRIPTOR 構造体を含むバッファーへのポインター。
[out] DescriptorsBufferActual
DescriptorsBuffer パラメーターで実際の数の記述子が返されたバッファーへのポインター。
[in] Flags
BluetoothGATTGetDescriptors の動作を変更するためのフラグ:
| フラグ | 説明 |
|---|---|
| BLUETOOTH_GATT_FLAG_NONE | クライアントに特定の GATT 要件がありません (既定値)。 |
戻り値
この関数は、次の値を返します。
| リターン コード | 説明 |
|---|---|
|
操作は正常に完了しました。 |
|
buffer パラメーターは NULL であり、使用可能な項目の数が代わりに返されます。 |
|
親サービスとサービス ハンドルの両方が提供され、サービス階層が指定された親サービス ハンドルにロールアップされない場合に返されます。 |
|
次のいずれかの条件が発生しました。
|
|
バッファーが指定されていますが、バッファー数のサイズが必要なサイズよりもバイト単位で小さくなります。 |
|
キャッシュ内の現在のデータに不整合が見られ、内部エラーが発生しています。 |
|
操作がメモリ不足でした。 |
注釈
返される特性は、デバイスから直接特性を正常に取得するとキャッシュされます。 サービス変更イベントを受信しない限り、返される特性の一覧は変更されません。
プロファイル ドライバーでは、返される特性の配列に対して十分に大きなバッファーを事前に割り当てる必要があります。 呼び出し元は、DescriptorsBufferActual に NULL 以外の値を渡し、DescriptorsBuffer で NULL を渡すことによって、必要なバッファー サイズを決定できます。
返された特性構造を変更し、その後の関数呼び出しで変更された構造体を使用しないでください。 呼び出し元がこれを行う場合、動作は未定義です。
親特性はキャッシュに存在する必要があります。そうしないと、関数は失敗します。 親サービスは、 BluetoothGATTGetServices または BluetoothGATTGetIncludedServices によって返されるサービスである必要があります。
例
////////////////////////////////////////////////////////////////////////////
// Determine Descriptor Buffer Size
////////////////////////////////////////////////////////////////////////////
GetDescriptors:
hr = BluetoothGATTGetDescriptors(
hCurrService,
currGattChar,
0,
NULL,
&descriptorBufferSize,
BLUETOOTH_GATT_FLAG_NONE);
if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
PrintHr("BluetoothGATTGetDescriptors - Buffer Size", hr);
goto Done; // Allow continuation
}
if (descriptorBufferSize > 0) {
pDescriptorBuffer = (PBTH_LE_GATT_DESCRIPTOR)
malloc(descriptorBufferSize
* sizeof(BTH_LE_GATT_DESCRIPTOR));
if (NULL == pDescriptorBuffer) {
printf("pDescriptorBuffer out of memory\r\n");
goto Done;
} else {
RtlZeroMemory(pDescriptorBuffer, descriptorBufferSize);
}
////////////////////////////////////////////////////////////////////////////
// Retrieve Descriptors
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetDescriptors(
hCurrService,
currGattChar,
descriptorBufferSize,
pDescriptorBuffer,
&numDescriptors,
BLUETOOTH_GATT_FLAG_NONE);
if (S_OK != hr) {
PrintHr("BluetoothGATTGetDescriptors - Actual Data", hr);
goto Done;
}
if (numDescriptors != descriptorBufferSize) {
printf("buffer size and buffer size actual size mismatch\r\n");
goto Done;
}
}
必要条件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8 以降のバージョンの Windows でサポートされています。 |
| 対象プラットフォーム | ユニバーサル |
| Header | bluetoothleapis.h |
| Library | BluetoothApis.lib |
| [DLL] | BluetoothAPIs.dll |