BluetoothGATTGetIncludedServices-Funktion (bluetoothleapis.h)

Artikel
08/22/2023

Die BluetoothGATTGetIncludedServices-Funktion ruft alle enthaltenen Dienste ab, die für einen bestimmten Dienst verfügbar sind.

Syntax

HRESULT BluetoothGATTGetIncludedServices(
  [in]            HANDLE               hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE ParentService,
  [in]            USHORT               IncludedServicesBufferCount,
  [out, optional] PBTH_LE_GATT_SERVICE IncludedServicesBuffer,
  [out]           USHORT               *IncludedServicesBufferActual,
  [in]            ULONG                Flags
);

Parameter

[in] hDevice

Behandeln Sie das Bluetooth-Gerät oder den übergeordneten Dienst.

[in, optional] ParentService

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] IncludedServicesBufferCount

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

[out, optional] IncludedServicesBuffer

Adresse eines Puffers, der eine BTH_LE_GATT_SERVICE Struktur enthält, in die eingeschlossene Dienste zurückgegeben werden sollen.

[out] IncludedServicesBufferActual

Zeiger auf den Puffer, in den die tatsächliche Anzahl der enthaltenen Dienste im IncludedServicesBuffer-Parameter zurückgegeben wurde.

[in] Flags

Flags zum Ändern des Verhaltens von BluetoothGATTGetIncludedServices:

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: IncludedServicesBuffer ist NULL und IncludedServicesBufferCount ist 0. IncludedServicesBuffer ist nicht NULL, aber IncludedServicesBufferCount ist NULL. IncludedServicesBuffer ist nicht NULL und IncludedServicesBufferCount 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 angegeben, um aus dem Cache abgerufen zu werden, 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 war der Arbeitsspeicher nicht mehr vorhanden.

Hinweise

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

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

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

Beispiel


////////////////////////////////////////////////////////////////////////////
// Determine Included Services Buffer Size
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetIncludedServices(
     hLEDevice,
     gattService,
     0,
     NULL,
     &inclServicesBufferSize,
     BLUETOOTH_GATT_FLAG_NONE);

     if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
         PrintHr("BluetoothGATTGetIncludedServices - Buffer Size", hr);
         goto Done;
     }

     if (inclServicesBufferSize > 0) {
         pInclServicesBuffer = (PBTH_LE_GATT_ PBTH_LE_GATT_SERVICE)
                    malloc(inclServicesBufferSize * sizeof(BTH_LE_GATT_SERVICE));

         if (NULL == pInclServicesBuffer) {
             printf("pInclServicesBuffer out of memory\r\n");
             goto Done;
         } else {
             RtlZeroMemory(pInclServicesBuffer, 
                    inclServicesBufferSize * sizeof(BTH_LE_GATT_SERVICE));
         }

         ////////////////////////////////////////////////////////////////////////////
         // Retrieve Included Services
         ////////////////////////////////////////////////////////////////////////////

         hr = BluetoothGATTGetIncludedServices (
              hLEDevice,
              gattService,
              inclServicesBufferSize,
              pInclServicesBuffer,
              &numIncludedServices
              BLUETOOTH_GATT_FLAG_NONE);

         if (S_OK != hr) {
             PrintHr("BluetoothGATTGetIncludedServices - Actual Data", hr);
             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_SERVICE

Freigeben über