次の方法で共有

BluetoothGATTGetCharacteristics 関数 (bluetoothleapis.h)

  • [アーティクル]

BluetoothGATTGetCharacteristics 関数は、指定されたサービスで使用できるすべての特性を取得します。

構文

HRESULT BluetoothGATTGetCharacteristics(
  [in]            HANDLE                      hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE        Service,
  [in]            USHORT                      CharacteristicsBufferCount,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC CharacteristicsBuffer,
  [out]           USHORT                      *CharacteristicsBufferActual,
  [in]            ULONG                       Flags
);

パラメーター

[in] hDevice

Bluetooth デバイスまたはサービスを処理します。

[in, optional] Service

取得 する含 まれるサービスの親サービスを含むBTH_LE_GATT_SERVICE構造体のアドレス。 このパラメーターは、デバイス ハンドルが hDevice に渡される場合に必要です。 サービス ハンドルが hDevice に渡された場合、このパラメーターは省略可能です。この場合、サービス ハンドルによって指定されたサービスは親として扱われます。

[in] CharacteristicsBufferCount

CharacteristicsBuffer パラメーターに割り当てられた要素の数。

[out, optional] CharacteristicsBuffer

BTH_LE_GATT_CHARACTERISTIC構造体の配列として特性を返すバッファーへのポインター。

[out] CharacteristicsBufferActual

CharacteristicsBuffer パラメーターで返された実際の特性数を返すバッファーへのポインター。

[in] Flags

BluetoothGATTGetCharacteristics の動作を変更するためのフラグ:

フラグ 説明
BLUETOOTH_GATT_FLAG_NONE クライアントに特定の GATT 要件がありません (既定値)。

戻り値

この関数は、次の値を返します。

リターン コード 説明
S_OK
 操作は正常に完了しました。
ERROR_MORE_DATA
 buffer パラメーターは NULL であり、使用可能な項目の数が代わりに返されます。
ERROR_ACCESS_DENIED
 親サービスとサービス ハンドルの両方が提供され、サービス階層が指定された親サービス ハンドルにロールアップされない場合に返されます。
ERROR_INVALID_PARAMETER
 次のいずれかの条件が発生しました。
  • CharacteristicsBuffer は NULL、 CharacteristicsBufferCount は 0 です
  • CharacteristicsBuffer は NULL 以外ですが、 CharacteristicsBufferCount は NULL です
  • CharacteristicsBuffer は NULL 以外で、 CharacteristicsBufferCount は 0 です
ERROR_INVALID_USER_BUFFER
 バッファーが指定されていますが、バッファー数のサイズが必要なサイズよりもバイト単位で小さくなります。
ERROR_BAD_COMMAND
 キャッシュ内の現在のデータに不整合が見られ、内部エラーが発生しています。
ERROR_NO_SYSTEM_RESOURCES
 操作がメモリ不足でした。

注釈

返される特性は、デバイスから直接特性を正常に取得するとキャッシュされます。 サービス変更イベントを受信しない限り、返される特性の一覧は変更されません。

プロファイル ドライバーでは、返される特性の配列に対して十分に大きなバッファーを事前に割り当てる必要があります。 呼び出し元は、CharacteristicsBufferActual に NULL 以外の値を渡し、CharacteristicsBuffer で NULL を渡すことで、必要なバッファー サイズを決定できます。

返された特性構造を変更し、その後の関数呼び出しで変更された構造体を使用しないでください。 呼び出し元がこれを行う場合、動作は未定義です。

親サービスはキャッシュに存在する必要があります。そうしないと、関数は失敗します。 親サービスは、 BluetoothGATTGetServices または BluetoothGATTGetIncludedServices によって返されるサービスである必要があります。

例

////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Buffer Size
////////////////////////////////////////////////////////////////////////////

        hr = BluetoothGATTGetCharacteristics(
                hCurrService,
                currGattService,
                0,
                NULL,
                &charBufferSize,
                BLUETOOTH_GATT_FLAG_NONE);
        
        if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
            PrintHr("BluetoothGATTGetCharacteristics - Buffer Size", hr);
            goto Done;
        }
        
        if (charBufferSize > 0) {
            pCharBuffer = (PBTH_LE_GATT_CHARACTERISTIC)
                    malloc(charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
        
            if (NULL == pCharBuffer) {
                printf("pCharBuffer out of memory\r\n");
                goto Done;
            } else {
                RtlZeroMemory(pCharBuffer, 
                        charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
            }

////////////////////////////////////////////////////////////////////////////
// Retrieve Characteristics
////////////////////////////////////////////////////////////////////////////
    
            hr = BluetoothGATTGetCharacteristics(
                    hCurrService,
                    currGattService,
                    charBufferSize,
                    pCharBuffer,
                    &numChars,
                    BLUETOOTH_GATT_FLAG_NONE);

            if (S_OK != hr) {
                PrintHr("BluetoothGATTGetCharacteristics - Actual Data", hr);
                goto Done; // Allow continuation
            }

            if (numChars != charBufferSize) {
                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

こちらもご覧ください

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_SERVICE