GetPointerFrameInfoHistory, fonction (winuser.h)
Obtient l’intégralité de la trame d’informations (y compris les trames d’entrée coalescées) pour les pointeurs spécifiés associés au message actuel.
Syntaxe
BOOL GetPointerFrameInfoHistory(
[in] UINT32 pointerId,
[in, out] UINT32 *entriesCount,
[in, out] UINT32 *pointerCount,
[out] POINTER_INFO *pointerInfo
);
Paramètres
[in] pointerId
Identificateur du pointeur pour lequel récupérer les informations de trame.
[in, out] entriesCount
Pointeur vers une variable qui spécifie le nombre de lignes dans le tableau à deux dimensions vers lequel pointe pointerInfo. Si GetPointerFrameInfoHistory réussit, entriesCount est mis à jour avec le nombre total d’images disponibles dans l’historique.
[in, out] pointerCount
Pointeur vers une variable qui spécifie le nombre de colonnes dans le tableau à deux dimensions vers lequel pointe pointerInfo. Si GetPointerFrameInfoHistory réussit, pointerCount est mis à jour avec le nombre total de pointeurs dans chaque image.
[out] pointerInfo
Adresse d’un tableau à deux dimensions de structures POINTER_INFO pour recevoir les informations de pointeur. Ce paramètre peut être NULL si *entriesCount et *pointerCount sont tous deux zéro.
Ce tableau est interprété comme POINTER_INFO[*entriesCount][*pointerCount].
Valeur retournée
Si la fonction réussit, la valeur de retour est différente de zéro.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Remarques
Les appareils en mode parallèle peuvent signaler l’entrée de pointeur dans les trames, c’est-à-dire qu’ils peuvent signaler l’état et la position de tous les pointeurs de cet appareil dans un seul rapport d’entrée au système. Dans l’idéal, les applications doivent afficher la trame entière comme une seule entrée, sauf si les exigences spécifiques à l’application l’exigent autrement.
Les informations retournées par GetPointerFrameInfo sont associées au message de pointeur le plus récent récupéré par le thread appelant. Lorsque le message suivant est récupéré par le thread appelant, les informations associées au message précédent peuvent ne plus être disponibles.
Si l’application ne traite pas les messages d’entrée de pointeur aussi rapidement qu’ils sont générés, certains messages peuvent être fusionnés en un message WM_POINTERUPDATE . Utilisez GetPointerFrameInfoHistory pour récupérer l’historique des messages (y compris les trames d’entrée coalescées) à partir du message WM_POINTERUPDATE le plus récent.
Après avoir récupéré l’intégralité de la trame d’informations, l’application peut ensuite appeler la fonction SkipPointerFrameMessages pour ignorer les messages de pointeur restants associés à ce frame qui sont en attente de récupération. Cela permet à l’application d’économiser la surcharge liée à la récupération et au traitement des messages restants un par un. Toutefois, la fonction SkipPointerFrameMessages doit être utilisée avec précaution et uniquement lorsque l’appelant peut s’assurer qu’aucune autre entité sur le thread de l’appelant ne s’attend à voir les messages de pointeur restants un par un à mesure qu’ils sont récupérés.
Le frame contient uniquement les pointeurs qui appartiennent actuellement à la même fenêtre que le pointeur spécifié.
Les informations récupérées représentent un tableau à deux dimensions avec une ligne pour chaque entrée d’historique et une colonne pour chaque pointeur dans le cadre.
Les informations récupérées apparaissent dans l’ordre chronologique inverse, avec l’entrée la plus récente dans la première ligne du tableau retourné. L’entrée la plus récente est la même que celle retournée par la fonction GetPointerFrameInfo .
Si le nombre de lignes dans la mémoire tampon fournie est insuffisant pour contenir toutes les entrées d’historique disponibles, cette fonction réussit avec la mémoire tampon contenant les entrées les plus récentes et *entriesCount contenant le nombre total d’entrées disponibles.
Si le cadre de pointeur ne contient aucun pointeur supplémentaire en dehors du pointeur spécifié, cette fonction réussit et retourne uniquement les informations du pointeur spécifié.
Si les informations associées au cadre de pointeur ne sont plus disponibles, cette fonction échoue avec la dernière erreur définie sur ERROR_NO_DATA.
Si le thread appelant ne possède pas la fenêtre (où l’entrée a été remise à l’origine ou où le message a été transféré) à laquelle le message de pointeur a été remis, cette fonction échoue avec la dernière erreur définie sur ERROR_ACCESS_DENIED.
Pour les applications qui ont à la fois des zones client et non client, la trame d’entrée peut inclure des données client et non client. Pour faire la différence entre les données client et non client, vous devez effectuer des tests d’accès sur la fenêtre cible.
Nous vous recommandons ce qui suit si vous souhaitez filtrer les données à partir de la trame d’entrée :
- Pour chaque mise à jour qui n’inclut pas de contact de pointeur (un POINTER_FLAG_UPDATE sans POINTER_FLAG_INCONTACT), test de positionnement pour déterminer si l’entrée est cliente ou non cliente.
- Pour chaque nouveau contact (POINTER_FLAG_DOWN), effectuez un test de positionnement pour déterminer si l’entrée est cliente ou non cliente et suivez ces informations.
- Pour chaque mise à jour qui inclut un contact de pointeur (un POINTER_FLAG_UPDATE avec POINTER_FLAG_INCONTACT), utilisez les informations de suivi pour déterminer si l’entrée est cliente ou non cliente.
- Pour chaque POINTER_FLAG_UP, utilisez les informations de suivi pour déterminer si l’entrée est cliente ou non cliente, puis effacez ce pointeur des données de suivi.
Configuration requise
| Client minimal pris en charge | Windows 8 [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2012 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winuser.h (inclure Windows.h) |
| Bibliothèque | User32.lib |
| DLL | User32.dll |
| Ensemble d’API | ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0 (introduit dans Windows 10, version 10.0.14393) |