BluetoothGATTGetDescriptors-Funktion (bluetoothleapis.h)

Artikel
02/26/2024

Die BluetoothGATTGetDescriptors-Funktion ruft alle Deskriptoren ab, die für das angegebene Merkmal verfügbar sind.

Syntax

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

Parameter

[in] hDevice

Verarbeiten sie das Bluetooth-Gerät oder den Bluetooth-Dienst. Wenn ein Diensthandle übergeben wird, muss der Dienst der Großeltern des Deskriptors sein.

[in] Characteristic

Zeiger auf BTH_LE_GATT_CHARACTERISTIC Struktur, die das übergeordnete Merkmal der abzurufenden Deskriptoren enthält.

[in] DescriptorsBufferCount

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

[out, optional] DescriptorsBuffer

Zeiger auf einen Puffer, der eine BTH_LE_GATT_DESCRIPTOR Struktur enthält, in die Deskriptoren zurückgegeben werden sollen.

[out] DescriptorsBufferActual

Zeiger auf den Puffer, in den die tatsächliche Anzahl von Deskriptoren im DescriptorsBuffer-Parameter zurückgegeben wurde.

[in] Flags

Flags zum Ändern des Verhaltens von BluetoothGATTGetDescriptors:

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: DescriptorsBuffer ist NULL und DescriptorsBufferCount ist 0. DescriptorsBuffer ist nicht NULL, aber DescriptorsBufferCount ist NULL. DescriptorsBuffer ist nicht NULL, und DescriptorsBufferCount 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 in DescriptorsBufferActual und NULL in DescriptorsBuffer einen Wert ohne NULL ü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.

Das übergeordnete Merkmal 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 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;
                }
            }

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_DESCRIPTOR

Freigeben über