GetPointerFrameTouchInfo, fonction (winuser.h)
Obtient l’intégralité du cadre des informations tactiles pour les pointeurs spécifiés (de type PT_TOUCH) associés au message actuel.
Syntaxe
BOOL GetPointerFrameTouchInfo(
[in] UINT32 pointerId,
[in, out] UINT32 *pointerCount,
[out] POINTER_TOUCH_INFO *touchInfo
);
Paramètres
[in] pointerId
Identificateur du pointeur pour lequel récupérer les informations de trame.
[in, out] pointerCount
Pointeur vers une variable qui spécifie le nombre de structures dans la mémoire tampon vers lesquelles touchInfo pointe. Si GetPointerFrameTouchInfo réussit, pointerCount est mis à jour avec le nombre total de pointeurs dans le frame.
[out] touchInfo
Adresse d’un tableau de structures POINTER_TOUCH_INFO pour recevoir les informations du pointeur. Ce paramètre peut être NULL si *pointerCount a la valeur zéro.
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.
GetPointerFrameTouchInfo récupère l’intégralité du frame d’entrée de pointeur associé à un message de pointeur (de type PT_TOUCH). Utilisez GetPointerTouchInfo pour récupérer les informations d’un pointeur unique associé à un message de pointeur.
Le frame contient uniquement les pointeurs qui appartiennent actuellement à la même fenêtre que le pointeur spécifié.
Les informations retournées par GetPointerFrameTouchInfo 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 GetPointerFrameTouchInfoHistory pour récupérer l’historique des messages à 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.
Notez que les informations récupérées sont associées au cadre de pointeur le plus récemment récupéré par le thread appelant. Une fois que le thread appelant a récupéré son message suivant, les informations associées au frame de pointeur précédent peuvent ne plus être 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 à laquelle le message de pointeur a été remis, cette fonction échoue avec la dernière erreur définie sur ERROR_ACCESS_DENIED.
Si le pointeur spécifié n’est pas de type PT_TOUCH, cette fonction échoue avec la dernière erreur définie sur ERROR_DATATYPE_MISMATCH.
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
| Condition requise | Valeur |
|---|---|
| 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) |