Fonction BluetoothGATTGetIncludedServices (bluetoothleapis.h)

Article
02/23/2024

La fonction BluetoothGATTGetIncludedServices obtient tous les services inclus disponibles pour un service donné.

Syntaxe

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

Paramètres

[in] hDevice

Gérez l’appareil Bluetooth ou le service parent.

[in, optional] ParentService

Adresse d’une structure BTH_LE_GATT_SERVICE qui contient le service parent des services inclus à récupérer. Ce paramètre est requis si un handle d’appareil est passé à hDevice. Ce paramètre est facultatif si un handle de service a été passé à hDevice, auquel cas le service spécifié par le handle de service sera traité comme le parent.

[in] IncludedServicesBufferCount

Nombre d’éléments alloués pour le paramètre IncludedServicesBuffer .

[out, optional] IncludedServicesBuffer

Adresse d’une mémoire tampon contenant une structure BTH_LE_GATT_SERVICE dans laquelle retourner des services inclus.

[out] IncludedServicesBufferActual

Pointeur vers la mémoire tampon dans laquelle le nombre réel de services inclus a été retourné dans le paramètre IncludedServicesBuffer .

[in] Flags

Indicateurs pour modifier le comportement de BluetoothGATTGetIncludedServices :

Indicateur	Description
BLUETOOTH_GATT_FLAG_NONE	Le client n’a pas d’exigences GATT spécifiques (par défaut).

Valeur retournée

Cette fonction retourne les valeurs suivantes :

Code de retour	Description
S_OK	L’opération s’est terminée avec succès.
ERROR_MORE_DATA	Le paramètre de mémoire tampon est NULL et le nombre d’éléments disponibles est retourné à la place.
ERROR_ACCESS_DENIED	Retourné si un service parent et un handle de service sont fournis et que la hiérarchie de service ne se cumule pas sur le handle de service parent fourni.
ERROR_INVALID_PARAMETER	L’une des conditions suivantes s’est produite : IncludedServicesBuffer a la valeur NULL et IncludedServicesBufferCount est 0. IncludedServicesBuffer n’a pas la valeur NULL, mais IncludedServicesBufferCount a la valeur NULL. IncludedServicesBuffer n’a pas la valeur NULL et IncludedServicesBufferCount est 0.
ERROR_INVALID_USER_BUFFER	Une mémoire tampon est spécifiée, mais la taille du nombre de mémoires tampons est inférieure à ce qui est requis, en octets.
ERROR_INVALID_FUNCTION	Les services ont été spécifiés pour être récupérés à partir du cache, mais aucun service n’est présent dans le cache.
ERROR_BAD_COMMAND	Les données actuelles dans le cache semblent incohérentes et entraînent des erreurs internes.
ERROR_NO_SYSTEM_RESOURCES	L’opération a manqué de mémoire.

Remarques

Les services retournés sont mis en cache lors de la récupération réussie des services à partir de l’appareil directement. À moins qu’un événement de modification de service ne soit reçu, la liste des services retournés ne devrait pas changer.

Les pilotes de profil doivent préallouer une mémoire tampon suffisamment grande pour que le tableau de services principaux soit retourné. Les appelants peuvent déterminer la taille de mémoire tampon nécessaire en transmettant une valeur non NULL dans IncludedServicesBufferActual et NULL dans IncludedServicesBuffer.

Ne modifiez pas la structure de service retournée, puis utilisez la structure modifiée dans les appels de fonction suivants. Le comportement n’est pas défini si l’appelant effectue cette opération.

Exemple


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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans Windows 8 et versions ultérieures de Windows.
Plateforme cible	Universal
En-tête	bluetoothleapis.h
Bibliothèque	BluetoothApis.lib
DLL	BluetoothAPIs.dll

Voir aussi

BTH_LE_GATT_SERVICE

Partager via