nf-winuser-skippointerframemessages.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:winuser.SkipPointerFrameMessages	SkipPointerFrameMessages function (winuser.h)	Determines which pointer input frame generated the most recently retrieved message for the specified pointer and discards any queued (unretrieved) pointer input messages generated from the same pointer input frame.	SkipPointerFrameMessages SkipPointerFrameMessages function [Input Messages and Notifications] inputmsg.skippointerframemessages winuser/SkipPointerFrameMessages	inputmsg\skippointerframemessages.htm	InputMsg	d67f8d44-3e19-4523-a0f3-38f09f5df91f	12/05/2018	SkipPointerFrameMessages, SkipPointerFrameMessages function [Input Messages and Notifications], inputmsg.skippointerframemessages, winuser/SkipPointerFrameMessages	winuser.h	Windows.h	Windows	Windows 8 [desktop apps only]	Windows Server 2012 [desktop apps only]										User32.lib	User32.dll		Windows			19H1	SkipPointerFrameMessages winuser/SkipPointerFrameMessages	c++	APIRef kbSyntax	DllExport	User32.dll API-MS-Win-RTCore-NTUser-WMPointer-l1-1-1.dll MinUser.dll api-ms-win-rtcore-ntuser-wmpointer-l1-1-0.dll API-Ms-Win-RTCore-NTUser-WMPointer-L1-1-2.dll API-MS-Win-RTCore-NTUser-WMPointer-L1-1-3.dll	SkipPointerFrameMessages

SkipPointerFrameMessages function

-description

Determines which pointer input frame generated the most recently retrieved message for the specified pointer and discards any queued (unretrieved) pointer input messages generated from the same pointer input frame. If an application has retrieved information for an entire frame using the GetPointerFrameInfo function, the GetPointerFrameInfoHistory function or one of their type-specific variants, it can use this function to avoid retrieving and discarding remaining messages from that frame one by one.

-parameters

-param pointerId [in]

Identifier of the pointer. Pending messages will be skipped for the frame that includes the most recently retrieved input for this pointer.

-returns

If the function succeeds, the return value is non-zero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

-remarks

Parallel-mode devices may report pointer input in frames, that is, they may report the state and position of all pointers from that device in a single input report to the system. Ideally, applications should view the entire frame as a single input unless the application-specific requirements dictate otherwise.

The SkipPointerFrameMessages function can be used in conjunction with the GetPointerFrameInfo function (or one of its type-specific variants) to consume entire frames as a single input.

When an application sees a pointer message, it can use the GetPointerFrameInfo function to retrieve the entire pointer input frame to which the pointer message belongs, hence obtaining an updated view of all of the pointers currently owned by the window. Note that the returned frame contains only pointers that are currently owned by the same window as the specified pointer.

Having retrieved the entire frame of information, the application can then call the SkipPointerFrameMessages function to skip remaining pointer messages associated with this frame that are pending retrieval. This saves the application the overhead of retrieving and processing the remaining messages one by one.

Warning  The SkipPointerFrameMessages function should be used only when the caller can be sure that no other entity on the caller’s thread (such as Direct Manipulation) is expecting to retrieve pending pointer messages. For this reason, SkipPointerFrameMessages should not be used in conjunction with Direct Manipulation when processing multiple, simultaneous interactions.

 

Note that the information retrieved is associated with the pointer frame most recently retrieved by the calling thread. Once the calling thread retrieves its next message, the information associated with the previous pointer frame may no longer be available.

If the pointer frame contains no additional pointers besides the specified pointer, this function succeeds with no action.

If the calling thread does not own the window to which the pointer message has been delivered, this function fails with the last error set to ERROR_ACCESS_DENIED.

-see-also

Functions