BluetoothGATTGetDescriptorValue-Funktion (bluetoothleapis.h)

Artikel
08/22/2023

Die BluetoothGATTGetDescriptorValue-Funktion ruft den Wert des angegebenen Deskriptors ab.

Syntax

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

Parameter

[in] hDevice

Handle für den Dienst.

[in] Descriptor

Zeiger auf BTH_LE_GATT_DESCRIPTOR Struktur, die den übergeordneten Deskriptor des abzurufenden Deskriptorwerts enthält.

[in] DescriptorValueDataSize

Die Anzahl der Bytes, die dem DescriptorValue-Parameter zugeordnet sind.

[out, optional] DescriptorValue

Zeiger auf BTH_LE_GATT_DESCRIPTOR_VALUE Struktur, in die der Deskriptorwert zurückgegeben werden soll.

[out, optional] DescriptorValueSizeRequired

Zeiger auf den Puffer, in dem die Anzahl zusätzlicher Bytes gespeichert werden soll, die erforderlich sind, um Daten im Puffer zurückzugeben, auf den descriptorValue verweist.

[in] Flags

Flags zum Ändern des Verhaltens von BluetoothGATTGetDescriptorValue:

Flag	Beschreibung
BLUETOOTH_GATT_FLAG_NONE	Für den Client gelten keine spezifischen GATT-Anforderungen (Standard).
BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED	Der Client fordert die Übertragung der Daten über einen verschlüsselten Kanal an.
BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED	Der Client fordert die Übertragung der Daten über einen authentifizierten Kanal an.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE	Der Deskriptorwert muss direkt vom Gerät gelesen werden. Dadurch wird die im Cache vorhandene überschrieben.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE	Der Deskriptorwert muss aus dem Cache gelesen werden (unabhängig davon, ob er im Cache vorhanden ist oder nicht).

Rückgabewert

Die BluetoothGATTGetDescriptorValue-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	Sowohl DescriptorValue als auch DescriptorValueSizeRequired sind 0.
ERROR_INVALID_USER_BUFFER	Es wird ein Puffer angegeben, aber die Pufferanzahl ist kleiner als die erforderliche Größe in Bytes.
ERROR_INVALID_FUNCTION	Es wurde ein Deskriptorwert angegeben, der aus dem Cache abgerufen werden soll, aber der Deskriptorwert ist nicht im Cache vorhanden.
ERROR_BAD_COMMAND	Die aktuellen Daten im Cache scheinen inkonsistent zu sein und führen zu internen Fehlern.
ERROR_BAD_NET_RESP	Der Zielserver hat keine geeignete Netzwerkantwort bereitgestellt.
ERROR_SEM_TIMEOUT	Das Anforderungstimeout.
ERROR_NO_SYSTEM_RESOURCES	Für den Vorgang ist der Arbeitsspeicher nicht mehr vorhanden.
E_BLUETOOTH_ATT_INVALID_HANDLE	Das angegebene Attributhandle war auf diesem Server ungültig.
E_BLUETOOTH_ATT_READ_NOT_PERMITTED	Das Attribut kann nicht gelesen werden.
E_BLUETOOTH_ATT_WRITE_NOT_PERMITTED	Das Attribut kann nicht geschrieben werden.
E_BLUETOOTH_ATT_INVALID_PDU	Die Attribut-PDU war ungültig.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHENTICATION	Das Attribut erfordert eine Authentifizierung, bevor es gelesen oder geschrieben werden kann.
E_BLUETOOTH_ATT_REQUEST_NOT_SUPPORTED	Der Attributserver unterstützt die vom Client empfangene Anforderung nicht.
E_BLUETOOTH_ATT_INVALID_OFFSET	Der angegebene Offset lag nach dem Ende des Attributs.
E_BLUETOOTH_ATT_INSUFFICIENT_AUTHORIZATION	Das Attribut erfordert eine Autorisierung, bevor es gelesen oder geschrieben werden kann.
E_BLUETOOTH_ATT_PREPARE_QUEUE_FULL	Zu viele Vorbereitungsschreibvorgänge wurden in die Warteschlange eingereiht.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_FOUND	Innerhalb des angegebenen Attributhandlesbereichs wurde kein Attribut gefunden.
E_BLUETOOTH_ATT_ATTRIBUTE_NOT_LONG	Das Attribut kann nicht mit der Blob-Leseanforderung gelesen oder geschrieben werden.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE	Die für die Verschlüsselung dieses Links verwendete Verschlüsselungsschlüsselgröße ist unzureichend.
E_BLUETOOTH_ATT_INVALID_ATTRIBUTE_VALUE_LENGTH	Die Länge des Attributwerts ist für den Vorgang ungültig.
E_BLUETOOTH_ATT_UNLIKELY	Bei der angeforderten Attributanforderung ist ein Fehler aufgetreten, der unwahrscheinlich war und daher nicht wie angefordert abgeschlossen werden konnte.
E_BLUETOOTH_ATT_INSUFFICIENT_ENCRYPTION	Das Attribut erfordert eine Verschlüsselung, bevor es gelesen oder geschrieben werden kann.
E_BLUETOOTH_ATT_UNSUPPORTED_GROUP_TYPE	Der Attributtyp ist kein unterstütztes Gruppierungsattribut, wie durch eine Spezifikation höherer Ebenen definiert.
E_BLUETOOTH_ATT_INSUFFICIENT_RESOURCES	Unzureichende Ressourcen zum Abschließen der Anforderung.
E_BLUETOOTH_ATT_UNKNOWN_ERROR	Ein Fehler, der im reservierten Bereich liegt, wurde empfangen.

Hinweise

Der Deskriptorwert wird aus dem Cache zurückgegeben, wenn bereits ein Wert vorhanden ist. Dies wäre meistens der Fall, da alle Geräteattribute zum Zeitpunkt der Kopplung oder Zuordnung zwischengespeichert werden. Wenn er jedoch nicht vorhanden ist, wird der Deskriptorwert direkt vom Gerät gelesen und beim erfolgreichen Lesen vom Gerät zwischengespeichert. Wenn BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE oder BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE vorhanden ist, wird der Deskriptorwert mithilfe der angegebenen Methode gelesen.

Zurückgegebene Deskriptorwerte werden beim erfolgreichen Abruf von Deskriptorwerten direkt vom Gerät zwischengespeichert. Es wird davon ausgegangen, dass sich die Deskriptorwerte ändern, sofern kein Dienständerungsereignis empfangen wird.

Profiltreiber sollten vorab einen ausreichend großen Puffer zuordnen, damit das Array von Deskriptorwerten zurückgegeben werden kann. Aufrufer können die erforderliche Puffergröße ermitteln, indem sie einen Wert ungleich NULL in DescriptorValueSizeRequired und NULL in DescriptorValue übergeben.

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

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_DESCRIPTOR

BTH_LE_GATT_DESCRIPTOR_VALUE

Freigeben über