Fonction BluetoothGATTGetServices (bluetoothleapis.h)

Article
02/26/2024

La fonction BluetoothGATTGetServices obtient tous les services principaux disponibles pour un serveur.

Syntaxe

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

Paramètres

[in] hDevice

Gérez vers l’appareil Bluetooth à partir duquel obtenir la liste des services principaux.

[in] ServicesBufferCount

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

[out, optional] ServicesBuffer

Pointeur vers la mémoire tampon contenant une structure BTH_LE_GATT_SERVICE dans laquelle retourner des services.

[out] ServicesBufferActual

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

[in] Flags

Indicateurs pour modifier le comportement de BluetoothGATTGetServices :

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 : ServicesBuffer a la valeur NULL et ServicesBufferCount est 0 ServicesBuffer n’a pas la valeur NULL, mais ServicesBufferCount a la valeur NULL ServicesBuffer n’a pas la valeur NULL et ServicesBufferCount 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 ServicesBufferActual et NULL dans ServicesBuffer.

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

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