BluetoothGATTGetCharacteristics-Funktion (bluetoothleapis.h)

Artikel
03/14/2023

Die BluetoothGATTGetCharacteristics-Funktion ruft alle für den angegebenen Dienst verfügbaren Merkmale ab.

Syntax

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
);

Parameter

[in] hDevice

Verarbeiten sie das Bluetooth-Gerät oder den Bluetooth-Dienst.

[in, optional] Service

Adresse einer BTH_LE_GATT_SERVICE-Struktur , die den übergeordneten Dienst der abzurufenden dienste enthält. Dieser Parameter ist erforderlich, wenn ein Gerätehandle an hDevice übergeben wird. Dieser Parameter ist optional, wenn ein Diensthandle an hDevice übergeben wurde. In diesem Fall wird der vom Diensthandle angegebene Dienst als übergeordneter Dienst behandelt.

[in] CharacteristicsBufferCount

Die Anzahl der Elemente, die dem CharacteristicsBuffer-Parameter zugeordnet sind.

[out, optional] CharacteristicsBuffer

Zeiger auf einen Puffer, in den Merkmale als Array von BTH_LE_GATT_CHARACTERISTIC Strukturen zurückgegeben werden sollen.

[out] CharacteristicsBufferActual

Zeiger zum Puffer, in den die tatsächliche Anzahl von Merkmalen zurückgegeben wird, die im CharacteristicsBuffer-Parameter zurückgegeben wurden.

[in] Flags

Flags zum Ändern des Verhaltens von BluetoothGATTGetCharacteristics:

Flag	Beschreibung
BLUETOOTH_GATT_FLAG_NONE	Der Client hat keine spezifischen GATT-Anforderungen (Standard).

Rückgabewert

Diese Funktion gibt die folgenden Werte zurück:

Rückgabecode	BESCHREIBUNG
S_OK	Der Vorgang wurde erfolgreich abgeschlossen.
ERROR_MORE_DATA	Der Pufferparameter ist NULL , und stattdessen wird die Anzahl der verfügbaren Elemente zurückgegeben.
ERROR_ACCESS_DENIED	Wird zurückgegeben, wenn sowohl ein übergeordneter Dienst als auch ein Diensthandle bereitgestellt werden und die Diensthierarchie kein Rollup zum bereitgestellten übergeordneten Diensthandle durchführt.
ERROR_INVALID_PARAMETER	Eine der folgenden Bedingungen ist aufgetreten: CharacteristicsBuffer ist NULL, und CharacteristicsBufferCount ist 0. CharacteristicsBuffer ist nicht NULL, aber CharacteristicsBufferCount ist NULL. CharacteristicsBuffer ist nicht NULL, und CharacteristicsBufferCount ist 0.
ERROR_INVALID_USER_BUFFER	Es wird ein Puffer angegeben, aber die Pufferanzahl ist kleiner als die erforderliche Größe in Bytes.
ERROR_BAD_COMMAND	Die aktuellen Daten im Cache scheinen inkonsistent zu sein und führen zu internen Fehlern.
ERROR_NO_SYSTEM_RESOURCES	Für den Vorgang war der Arbeitsspeicher nicht mehr vorhanden.

Hinweise

Zurückgegebene Merkmale werden beim erfolgreichen Abruf von Merkmalen direkt vom Gerät zwischengespeichert. Solange kein Dienständerungsereignis empfangen wird, wird davon ausgegangen, dass sich die Liste der zurückgegebenen Merkmale nicht ändert.

Profiltreiber sollten vorab einen ausreichend großen Puffer zuweisen, damit das Array von Merkmalen zurückgegeben werden kann. Aufrufer können die erforderliche Puffergröße ermitteln, indem sie einen Wert ohne NULL in CharacteristicsBufferActual und NULL in CharacteristicsBuffer übergeben.

Ändern Sie nicht die zurückgegebene Merkmalsstruktur, und verwenden Sie die geänderte Struktur dann in nachfolgenden Funktionsaufrufen. Das Verhalten ist nicht definiert, wenn der Aufrufer dies tut.

Der übergeordnete Dienst muss im Cache vorhanden sein, andernfalls schlägt die Funktion fehl. Der übergeordnete Dienst muss ein Dienst sein, der entweder von BluetoothGATTGetServices oder BluetoothGATTGetIncludedServices zurückgegeben wird.

Beispiel

////////////////////////////////////////////////////////////////////////////
// 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;
            }
        }

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Wird in Windows 8 und höheren Versionen von Windows unterstützt.
Zielplattform	Universell
Header	bluetoothleapis.h
Bibliothek	BluetoothApis.lib
DLL	BluetoothApis.dll

Weitere Informationen

BTH_LE_GATT_CHARACTERISTIC

BTH_LE_GATT_SERVICE

Freigeben über