Fonction BluetoothGATTGetCharacteristics (bluetoothleapis.h)

Article
02/23/2024

La fonction BluetoothGATTGetCharacteristics obtient toutes les caractéristiques disponibles pour le service spécifié.

Syntaxe

HRESULT BluetoothGATTGetCharacteristics(
  [in]            HANDLE                      hDevice,
  [in, optional]  PBTH_LE_GATT_SERVICE        Service,
  [in]            USHORT                      CharacteristicsBufferCount,
  [out, optional] PBTH_LE_GATT_CHARACTERISTIC CharacteristicsBuffer,
  [out]           USHORT                      *CharacteristicsBufferActual,
  [in]            ULONG                       Flags
);

Paramètres

[in] hDevice

Gérez l’appareil ou le service Bluetooth.

[in, optional] Service

Adresse d’une structure de BTH_LE_GATT_SERVICE contenant 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] CharacteristicsBufferCount

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

[out, optional] CharacteristicsBuffer

Pointeur vers une mémoire tampon dans laquelle retourner des caractéristiques en tant que tableau de structures BTH_LE_GATT_CHARACTERISTIC .

[out] CharacteristicsBufferActual

Pointeur vers la mémoire tampon dans laquelle est retourné le nombre réel de caractéristiques retournées dans le paramètre CharacteristicsBuffer .

[in] Flags

Indicateurs permettant de modifier le comportement de BluetoothGATTGetCharacteristics :

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 : CaractéristiquesBuffer a la valeur NULL et CaractéristiquesBufferCount est 0 CaractéristiquesBuffer n’a pas la valeur NULL, mais CaractéristiquesBufferCount a la valeur NULL CaractéristiquesBuffer n’a pas la valeur NULL et CaractéristiquesBufferCount 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_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 caractéristiques retournées sont mises en cache lors de la récupération réussie des caractéristiques de l’appareil directement. À moins qu’un événement de modification de service ne soit reçu, la liste des caractéristiques retournées ne devrait pas changer.

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

Ne modifiez pas la structure caractéristique 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.

Le service parent doit être présent dans le cache, sinon la fonction échoue. Le service parent doit être un service retourné par BluetoothGATTGetServices ou BluetoothGATTGetIncludedServices.

Exemple

////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Buffer Size
////////////////////////////////////////////////////////////////////////////

        hr = BluetoothGATTGetCharacteristics(
                hCurrService,
                currGattService,
                0,
                NULL,
                &charBufferSize,
                BLUETOOTH_GATT_FLAG_NONE);
        
        if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
            PrintHr("BluetoothGATTGetCharacteristics - Buffer Size", hr);
            goto Done;
        }
        
        if (charBufferSize > 0) {
            pCharBuffer = (PBTH_LE_GATT_CHARACTERISTIC)
                    malloc(charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
        
            if (NULL == pCharBuffer) {
                printf("pCharBuffer out of memory\r\n");
                goto Done;
            } else {
                RtlZeroMemory(pCharBuffer, 
                        charBufferSize * sizeof(BTH_LE_GATT_CHARACTERISTIC));
            }

////////////////////////////////////////////////////////////////////////////
// Retrieve Characteristics
////////////////////////////////////////////////////////////////////////////
    
            hr = BluetoothGATTGetCharacteristics(
                    hCurrService,
                    currGattService,
                    charBufferSize,
                    pCharBuffer,
                    &numChars,
                    BLUETOOTH_GATT_FLAG_NONE);

            if (S_OK != hr) {
                PrintHr("BluetoothGATTGetCharacteristics - Actual Data", hr);
                goto Done; // Allow continuation
            }

            if (numChars != charBufferSize) {
                printf("buffer size and buffer size actual size mismatch\r\n");
                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_CHARACTERISTIC

BTH_LE_GATT_SERVICE

Partager via