Fonction BluetoothGATTGetDescriptors (bluetoothleapis.h)

Article
08/22/2023

La fonction BluetoothGATTGetDescriptors obtient tous les descripteurs disponibles pour la caractéristique spécifiée.

Syntaxe

HRESULT BluetoothGATTGetDescriptors(
  [in]            HANDLE                      hDevice,
  [in]            PBTH_LE_GATT_CHARACTERISTIC Characteristic,
  [in]            USHORT                      DescriptorsBufferCount,
  [out, optional] PBTH_LE_GATT_DESCRIPTOR     DescriptorsBuffer,
  [out]           USHORT                      *DescriptorsBufferActual,
  [in]            ULONG                       Flags
);

Paramètres

[in] hDevice

Gérez l’appareil ou le service Bluetooth. Si un handle de service est transmis, le service doit être le grand-parent du descripteur.

[in] Characteristic

Pointeur vers BTH_LE_GATT_CHARACTERISTIC structure contenant la caractéristique parente des descripteurs à récupérer.

[in] DescriptorsBufferCount

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

[out, optional] DescriptorsBuffer

Pointeur vers la mémoire tampon contenant une structure BTH_LE_GATT_DESCRIPTOR dans laquelle retourner des descripteurs.

[out] DescriptorsBufferActual

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

[in] Flags

Indicateurs pour modifier le comportement de BluetoothGATTGetDescriptors :

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 : DescriptorsBuffer a la valeur NULL et DescriptorsBufferCount est 0. DescriptorsBuffer n’a pas la valeur NULL, mais DescriptorsBufferCount a la valeur NULL. DescriptorsBuffer n’a pas la valeur NULL et DescriptorsBufferCount 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 DescriptorsBufferActual et NULL dans DescriptorsBuffer.

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.

La caractéristique parente doit être présente dans le cache, sinon la fonction échoue. Le service parent doit être un service retourné par BluetoothGATTGetServices ou BluetoothGATTGetIncludedServices.

Exemple


////////////////////////////////////////////////////////////////////////////
// Determine Descriptor Buffer Size
////////////////////////////////////////////////////////////////////////////
GetDescriptors:
            hr = BluetoothGATTGetDescriptors(
                    hCurrService,
                    currGattChar,
                    0,
                    NULL,
                    &descriptorBufferSize,
                    BLUETOOTH_GATT_FLAG_NONE);
            
            if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
                PrintHr("BluetoothGATTGetDescriptors - Buffer Size", hr);
                goto Done; // Allow continuation
            }
            
            if (descriptorBufferSize > 0) {
                pDescriptorBuffer = (PBTH_LE_GATT_DESCRIPTOR)
                        malloc(descriptorBufferSize 
                            * sizeof(BTH_LE_GATT_DESCRIPTOR));
            
                if (NULL == pDescriptorBuffer) {
                    printf("pDescriptorBuffer out of memory\r\n");
                    goto Done;
                } else {
                    RtlZeroMemory(pDescriptorBuffer, descriptorBufferSize);
                }
            
////////////////////////////////////////////////////////////////////////////
// Retrieve Descriptors
////////////////////////////////////////////////////////////////////////////
    
                hr = BluetoothGATTGetDescriptors(
                        hCurrService,
                        currGattChar,
                        descriptorBufferSize,
                        pDescriptorBuffer,
                        &numDescriptors,
                        BLUETOOTH_GATT_FLAG_NONE);
            
                if (S_OK != hr) {
                    PrintHr("BluetoothGATTGetDescriptors - Actual Data", hr);
                    goto Done;
                }

                if (numDescriptors != descriptorBufferSize) {
                    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_DESCRIPTOR

Partager via