Fonction GetPointerFrameInfo (winuser.h)
Obtient l’ensemble du cadre d’informations pour les pointeurs spécifiés associés au message actuel.
Syntaxe
BOOL GetPointerFrameInfo(
[in] UINT32 pointerId,
[in, out] UINT32 *pointerCount,
[out] POINTER_INFO *pointerInfo
);
Paramètres
[in] pointerId
Identificateur du pointeur pour lequel récupérer des informations de trame.
[in, out] pointerCount
Pointeur vers une variable qui spécifie le nombre de structures dans la mémoire tampon vers lesquelles pointe pointerInfo. Si GetPointerFrameInfo réussit, pointerCount est mis à jour avec le nombre total de pointeurs dans le cadre.
[out] pointerInfo
Adresse d’un tableau de structures POINTER_INFO pour recevoir les informations du pointeur. Ce paramètre peut avoir la valeur NULL si *pointerCount est égal à 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 une entrée de pointeur dans des trames, c’est-à-dire qu’ils peuvent signaler l’état et la position de tous les pointeurs de cet appareil dans un rapport d’entrée unique au système. Dans l’idéal, les applications doivent afficher l’ensemble de l’image sous la forme d’une seule entrée, sauf si les exigences spécifiques à l’application dictent le contraire.
GetPointerFrameInfo récupère l’ensemble du cadre d’entrée du pointeur associé à un message de pointeur. Utilisez GetPointerInfo pour récupérer des informations pour un pointeur unique associé à un message de pointeur.
Le cadre contient uniquement des pointeurs qui appartiennent actuellement à la même fenêtre que le pointeur spécifié.
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 à partir du message WM_POINTERUPDATE le plus récent.
Après avoir récupéré l’intégralité du cadre d’informations, l’application peut ensuite appeler la fonction SkipPointerFrameMessages pour ignorer les messages de pointeur restants associés à ce cadre 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 soin et uniquement lorsque l’appelant peut être sûr qu’aucune autre entité sur le thread de l’appelant ne s’attend à voir les messages de pointeur restants un par un au fur et à 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 cadre 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 relatives au pointeur spécifié.
Si les informations associées au cadre de pointeur ne sont plus disponibles, cette fonction échoue avec le dernier paramètre d’erreur défini sur ERROR_NO_DATA.
Si le thread appelant n’est pas propriétaire de la fenêtre (où l’entrée a été remise à l’origine ou où le message a été transféré) vers laquelle le message du 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 à la fois des données clientes et non clientes. Pour différencier 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 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 succès pour déterminer si l’entrée est cliente ou non cliente.
- Pour chaque nouveau contact (POINTER_FLAG_DOWN), test d’accès pour déterminer si l’entrée est cliente ou non cliente et suivre 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 |