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