BluetoothGATTGetCharacteristicValue-Funktion (bluetoothleapis.h)

Artikel
02/26/2024

Die BluetoothGATTGetCharacteristicValue-Funktion ruft den Wert des angegebenen Merkmals ab.

Syntax

HRESULT BluetoothGATTGetCharacteristicValue(
  [in]            HANDLE                            hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC       Characteristic,
  [in]            ULONG                             CharacteristicValueDataSize,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC_VALUE CharacteristicValue,
  [out, optional] USHORT                            *CharacteristicValueSizeRequired,
  [in]            ULONG                             Flags
);

Parameter

[in] hDevice

Handle für den Dienst.

[in] Characteristic

Zeiger auf das übergeordnete Merkmal des abzurufenden Merkmalswerts.

[in] CharacteristicValueDataSize

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

[out, optional] CharacteristicValue

Zeiger auf den Puffer, in den der Merkmalswert zurückgegeben werden soll.

[out, optional] CharacteristicValueSizeRequired

Zeiger auf den Puffer, in dem die Anzahl der Bytes gespeichert werden soll, die für die Rückgabe von Daten im Puffer erforderlich sind, auf den characteristicValue verweist.

[in] Flags

Flags zum Ändern des Verhaltens von BluetoothGATTGetCharacteristicValue:

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 Merkmalswert soll direkt vom Gerät gelesen werden. Dadurch wird die im Cache vorhandene überschrieben.
BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE	Der Merkmalswert muss aus dem Cache gelesen werden (unabhängig davon, ob er im Cache vorhanden ist oder nicht).

Rückgabewert

Die BluetoothGATTGetCharacteristicValue-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 CharacteristicValue als auch CharacteristicValueSizeRequired sind 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_BAD_NET_RESP	Der Zielserver hat keine geeignete Netzwerkantwort bereitgestellt.
ERROR_SEM_TIMEOUT	Das Anforderungstimeout.
ERROR_PRIVILEGE_NOT_HELD	Der Merkmalswert ist nicht lesbar, wie von den charakteristischen Eigenschaften vorgegeben.
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 Merkmalswert 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 charakteristische Wert 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 Merkmalswert mithilfe der angegebenen Methode gelesen.

Zurückgegebene Merkmale werden beim erfolgreichen Abruf von Merkmalen direkt vom Gerät zwischengespeichert. Sofern 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 zuordnen, damit das Array von Merkmalen zurückgegeben werden kann. Aufrufer können die erforderliche Puffergröße ermitteln, indem sie einen Wert ungleich NULL in CharacteristicValueSizeRequired und NULL in CharacteristicValue ü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


            if (currGattChar->IsReadable) {
////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Value Buffer Size
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        0,
                        NULL,
                        &charValueDataSize,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Buffer Size", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                pCharValueBuffer = (PBTH_LE_GATT_CHARACTERISTIC_VALUE)malloc(charValueDataSize);

                if (NULL == pCharValueBuffer) {
                    printf("pCharValueBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pCharValueBuffer, charValueDataSize);
                }

////////////////////////////////////////////////////////////////////////////
// Retrieve the Characteristic Value
////////////////////////////////////////////////////////////////////////////

                hr = BluetoothGATTGetCharacteristicValue(
                        hCurrService,
                        currGattChar,
                        (ULONG)charValueDataSize,
                        pCharValueBuffer,
                        NULL,
                        BLUETOOTH_GATT_FLAG_NONE);

                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetCharacteristicValue - Actual Data", hr);
                    goto GetDescriptors; // Proceed to retrieving descriptors
                }

                PrintCharacteristicValue(pCharValueBuffer, 2, currGattChar->CharacteristicUuid);

                // Free before going to next iteration, or memory leak.
                free(pCharValueBuffer);
                pCharValueBuffer = NULL;
            }

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_CHARACTERISTIC_VALUE

Freigeben über