Fonction BluetoothGATTGetDescriptorValue (bluetoothleapis.h)
La fonction BluetoothGATTGetDescriptorValue obtient la valeur du descripteur spécifié.
Syntaxe
HRESULT BluetoothGATTGetDescriptorValue(
[in] HANDLE hDevice,
[in] PBTH_LE_GATT_DESCRIPTOR Descriptor,
[in] ULONG DescriptorValueDataSize,
[out, optional] PBTH_LE_GATT_DESCRIPTOR_VALUE DescriptorValue,
[out, optional] USHORT *DescriptorValueSizeRequired,
[in] ULONG Flags
);
Paramètres
[in] hDevice
Gérez le service.
[in] Descriptor
Pointeur vers BTH_LE_GATT_DESCRIPTOR structure contenant le descripteur parent de la valeur de descripteur à récupérer.
[in] DescriptorValueDataSize
Nombre d’octets alloués pour le paramètre DescriptorValue .
[out, optional] DescriptorValue
Pointeur vers BTH_LE_GATT_DESCRIPTOR_VALUE structure dans laquelle retourner la valeur de descripteur.
[out, optional] DescriptorValueSizeRequired
Pointeur vers la mémoire tampon dans laquelle stocker le nombre d’octets supplémentaires nécessaires pour retourner des données dans la mémoire tampon pointée par DescriptorValue.
[in] Flags
Indicateurs permettant de modifier le comportement de BluetoothGATTGetDescriptorValue :
| Indicateur | Description |
|---|---|
| BLUETOOTH_GATT_FLAG_NONE | Le client n’a pas d’exigences GATT spécifiques (par défaut). |
| BLUETOOTH_GATT_FLAG_CONNECTION_ENCRYPTED | Le client demande que les données soient transmises sur un canal chiffré. |
| BLUETOOTH_GATT_FLAG_CONNECTION_AUTHENTICATED | Le client demande que les données soient transmises sur un canal authentifié. |
| BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE | La valeur du descripteur doit être lue directement à partir de l’appareil. Cela remplace celui dans le cache si l’un d’eux est déjà présent. |
| BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE | La valeur du descripteur doit être lue à partir du cache (qu’elle soit présente ou non dans le cache). |
Valeur retournée
La fonction BluetoothGATTGetDescriptorValue retourne les valeurs suivantes :
| Code de retour | Description |
|---|---|
|
L’opération s’est terminée avec succès. |
|
Le paramètre de mémoire tampon est NULL et le nombre d’éléments disponibles est retourné à la place. |
|
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. |
|
DescriptorValue et DescriptorValueSizeRequired sont tous deux 0. |
|
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. |
|
Une valeur de descripteur a été spécifiée pour être récupérée à partir du cache, mais la valeur du descripteur n’est pas présente dans le cache. |
|
Les données actuelles dans le cache semblent incohérentes et entraînent des erreurs internes. |
|
Le serveur cible n’a pas fourni de réponse réseau appropriée. |
|
La requête a expiré. |
|
L’opération a manqué de mémoire. |
|
Le handle d’attribut donné n’était pas valide sur ce serveur. |
|
Impossible de lire l’attribut. |
|
L’attribut ne peut pas être écrit. |
|
L’attribut PDU n’était pas valide. |
|
L’attribut nécessite une authentification avant de pouvoir être lu ou écrit. |
|
Le serveur d’attributs ne prend pas en charge la demande reçue du client. |
|
Le décalage spécifié a dépassé la fin de l’attribut. |
|
L’attribut nécessite une autorisation avant de pouvoir être lu ou écrit. |
|
Trop d’écritures de préparation ont été mises en file d’attente. |
|
Aucun attribut trouvé dans la plage de handle d’attribut donnée. |
|
L’attribut ne peut pas être lu ou écrit à l’aide de la demande de lecture d’objet blob. |
|
La taille de clé de chiffrement utilisée pour chiffrer ce lien est insuffisante. |
|
La longueur de la valeur de l’attribut n’est pas valide pour l’opération. |
|
La demande d’attribut demandée a rencontré une erreur peu probable et n’a donc pas pu être effectuée comme demandé. |
|
L’attribut nécessite un chiffrement avant de pouvoir être lu ou écrit. |
|
Le type d’attribut n’est pas un attribut de regroupement pris en charge tel que défini par une spécification de couche supérieure. |
|
Ressources insuffisantes pour terminer la demande. |
|
Une erreur qui se trouve dans la plage réservée a été reçue. |
Remarques
La valeur de descripteur est retournée à partir du cache si l’un d’eux est déjà présent. Ce serait le cas la plupart du temps, car tous les attributs d’appareil sont mis en cache au moment de l’appairage ou de l’association. Toutefois, s’il n’est pas présent, la valeur du descripteur est lue directement à partir de l’appareil et sera mise en cache après la lecture réussie à partir de l’appareil. Si BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_CACHE ou BLUETOOTH_GATT_FLAG_FORCE_READ_FROM_DEVICE est présent, la valeur du descripteur est lue à l’aide de la méthode spécifiée.
Les valeurs de descripteurs retournées sont mises en cache lors de la récupération réussie des valeurs de descripteur directement de l’appareil. Sauf si un événement de modification de service est reçu, les valeurs de descripteur ne sont pas censées changer.
Les pilotes de profil doivent préallouer une mémoire tampon suffisamment grande pour que le tableau de valeurs de descripteur soit retourné. Les appelants peuvent déterminer la taille de mémoire tampon nécessaire en transmettant une valeur non NULL dans DescriptorValueSizeRequired et NULL dans DescriptorValue.
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 Descriptor Value Buffer Size
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetDescriptorValue(
hCurrService,
currGattDescriptor,
0,
NULL,
&descValueDataSize,
BLUETOOTH_GATT_FLAG_NONE);
if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
PrintHr("BluetoothGATTGetDescriptorValue - Buffer Size", hr);
goto Done; // allow continuation
}
pDescValueBuffer = (PBTH_LE_GATT_DESCRIPTOR_VALUE)malloc(descValueDataSize);
if (NULL == pDescValueBuffer) {
printf("pDescValueBuffer out of memory\r\n");
goto Done;
} else {
RtlZeroMemory(pDescValueBuffer, descValueDataSize);
}
////////////////////////////////////////////////////////////////////////////
// Retrieve the Descriptor Value
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetDescriptorValue(
hCurrService,
currGattDescriptor,
(ULONG)descValueDataSize,
pDescValueBuffer,
NULL,
BLUETOOTH_GATT_FLAG_NONE);
if (S_OK != hr) {
PrintHr("BluetoothGATTGetDescriptorValue - Actual Data", hr);
goto Done; // allow continuation
}
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 |