BluetoothGATTGetServices-Funktion (bluetoothleapis.h)

Artikel
02/23/2024

Die BluetoothGATTGetServices-Funktion ruft alle primären Dienste ab, die für einen Server verfügbar sind.

Syntax

HRESULT BluetoothGATTGetServices(
  [in]            HANDLE               hDevice,
  [in]            USHORT               ServicesBufferCount,
  [out, optional] PBTH_LE_GATT_SERVICE ServicesBuffer,
  [out]           USHORT               *ServicesBufferActual,
  [in]            ULONG                Flags
);

Parameter

[in] hDevice

Handle an das Bluetooth-Gerät, von dem die Liste der primären Dienste abgerufen werden soll.

[in] ServicesBufferCount

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

[out, optional] ServicesBuffer

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

[out] ServicesBufferActual

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

[in] Flags

Flags zum Ändern des Verhaltens von BluetoothGATTGetServices:

Flag	Beschreibung
BLUETOOTH_GATT_FLAG_NONE	Für den Client gelten 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: ServicesBuffer ist NULL und ServicesBufferCount ist 0. ServicesBuffer ist ungleich NULL, aber ServicesBufferCount ist NULL. ServicesBuffer ist ungleich NULL und ServicesBufferCount ist 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	Dienste wurden zum Abrufen aus dem Cache angegeben, aber es sind keine Dienste im Cache vorhanden.
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 ist der Arbeitsspeicher nicht mehr vorhanden.

Hinweise

Zurückgegebene Dienste werden beim erfolgreichen Abruf von Diensten direkt vom Gerät zwischengespeichert. Es wird davon ausgegangen, dass sich die Liste der zurückgegebenen Dienste ändert, sofern kein Dienständerungsereignis empfangen wird.

Profiltreiber sollten vorab einen ausreichend großen Puffer zuordnen, damit das Array der primären Dienste zurückgegeben werden kann. Aufrufer können die erforderliche Puffergröße ermitteln, indem sie einen Wert ungleich NULL in ServicesBufferActual und NULL in ServicesBuffer übergeben.

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

Beispiel


////////////////////////////////////////////////////////////////////////////
// Determine Services Buffer Size
////////////////////////////////////////////////////////////////////////////

    hr = BluetoothGATTGetServices(
            hLEDevice,
            0,
            NULL,
            &serviceBufferCount,
            BLUETOOTH_GATT_FLAG_NONE);
    
    if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
        PrintHr("BluetoothGATTGetServices - Buffer Size", hr);
        goto Done;
    }

    pServiceBuffer = (PBTH_LE_GATT_SERVICE)
            malloc(sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);
    
    if (NULL == pServiceBuffer) {
        printf("pServiceBuffer out of memory\r\n");
        goto Done;
    } else {
        RtlZeroMemory(pServiceBuffer, 
                sizeof(BTH_LE_GATT_SERVICE) * serviceBufferCount);
    }
    
////////////////////////////////////////////////////////////////////////////
// Retrieve Services
////////////////////////////////////////////////////////////////////////////
    
    hr = BluetoothGATTGetServices(
            hLEDevice,
            serviceBufferCount,
            pServiceBuffer,
            &numServices,
            BLUETOOTH_GATT_FLAG_NONE);
    
    if (S_OK != hr) {
        PrintHr("BluetoothGATTGetServices - Actual Data", hr);
        goto Done;
    }

Anforderungen

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

Weitere Informationen

BTH_LE_GATT_SERVICE

Freigeben über