Fonction BluetoothGATTGetCharacteristicValue (bluetoothleapis.h)
La fonction BluetoothGATTGetCharacteristicValue obtient la valeur de la caractéristique spécifiée.
Syntaxe
HRESULT BluetoothGATTGetCharacteristicValue(
[in] HANDLE hDevice,
[in] PBTH_LE_GATT_CHARACTERISTIC Characteristic,
[in] ULONG CharacteristicValueDataSize,
[out, optional] PBTH_LE_GATT_CHARACTERISTIC_VALUE CharacteristicValue,
[out, optional] USHORT *CharacteristicValueSizeRequired,
[in] ULONG Flags
);
Paramètres
[in] hDevice
Gérez le service.
[in] Characteristic
Pointeur vers la caractéristique parente de la valeur caractéristique à récupérer.
[in] CharacteristicValueDataSize
Nombre d’octets alloués pour le paramètre CharacteristicValue .
[out, optional] CharacteristicValue
Pointeur vers la mémoire tampon dans laquelle retourner la valeur caractéristique.
[out, optional] CharacteristicValueSizeRequired
Pointeur vers la mémoire tampon dans laquelle stocker le nombre d’octets nécessaires pour retourner des données dans la mémoire tampon pointée par CharacteristicValue.
[in] Flags
Indicateurs permettant de modifier le comportement de BluetoothGATTGetCharacteristicValue :
| 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 caractéristique est à lire 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 caractéristique doit être lue à partir du cache (qu’elle soit présente ou non dans le cache). |
Valeur retournée
La fonction BluetoothGATTGetCharacteristicValue 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. |
|
CharacteristicValue et CharacteristicValueSizeRequired 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. |
|
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é. |
|
La valeur caractéristique n’est pas lisible comme dicté par les propriétés caractéristiques. |
|
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 caractéristique est retournée à partir du cache si l’une d’elles est déjà présente. 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, si elle n’est pas présente, la valeur caractéristique est lue directement à partir de l’appareil et sera mise en cache une fois 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 caractéristique est lue à l’aide de la méthode spécifiée.
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 CharacteristicValueSizeRequired et NULL dans CharacteristicValue.
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
if (currGattChar->IsReadable) {
////////////////////////////////////////////////////////////////////////////
// Determine Characteristic Value Buffer Size
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetCharacteristicValue(
hCurrService,
currGattChar,
0,
NULL,
&charValueDataSize,
BLUETOOTH_GATT_FLAG_NONE);
if (HRESULT_FROM_WIN32(ERROR_MORE_DATA) != hr) {
PrintHr("BluetoothGATTGetCharacteristicValue - Buffer Size", hr);
goto GetDescriptors; // Proceed to retrieving descriptors
}
pCharValueBuffer = (PBTH_LE_GATT_CHARACTERISTIC_VALUE)malloc(charValueDataSize);
if (NULL == pCharValueBuffer) {
printf("pCharValueBuffer out of memory\r\n");
goto Done;
} else {
RtlZeroMemory(pCharValueBuffer, charValueDataSize);
}
////////////////////////////////////////////////////////////////////////////
// Retrieve the Characteristic Value
////////////////////////////////////////////////////////////////////////////
hr = BluetoothGATTGetCharacteristicValue(
hCurrService,
currGattChar,
(ULONG)charValueDataSize,
pCharValueBuffer,
NULL,
BLUETOOTH_GATT_FLAG_NONE);
if (S_OK != hr) {
PrintHr("BluetoothGATTGetCharacteristicValue - Actual Data", hr);
goto GetDescriptors; // Proceed to retrieving descriptors
}
PrintCharacteristicValue(pCharValueBuffer, 2, currGattChar->CharacteristicUuid);
// Free before going to next iteration, or memory leak.
free(pCharValueBuffer);
pCharValueBuffer = NULL;
}
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 |