From 49f2ab9be72a689e2a34262a3ccc9d762c5d33f7 Mon Sep 17 00:00:00 2001 From: Dimitriy Ryazantcev Date: Wed, 18 Mar 2026 15:16:48 +0200 Subject: [PATCH 1/6] Clarify GetRawInputBuffer alignment and error handling Updated alignment requirements and error handling details for the GetRawInputBuffer function. Clarified the behavior of the function when reading raw input messages from the queue. --- .../winuser/nf-winuser-getrawinputbuffer.md | 24 +++++++++++++------ 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md b/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md index a20234203e8e..c66a0efc0e41 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md +++ b/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md @@ -57,15 +57,15 @@ Performs a buffered read of the raw input messages data found in the calling thr Type: **PRAWINPUT** -A pointer to a buffer of [RAWINPUT](ns-winuser-rawinput.md) structures that contain the raw input data. Pointer should be aligned on a **DWORD** (32-bit) boundary. +A pointer to a buffer of [RAWINPUT](ns-winuser-rawinput.md) structures that contain the raw input data. The pointer must be aligned on a **DWORD** (32-bit) boundary on 32-bit systems, and on a **QWORD** (64-bit) boundary on 64-bit systems. -If **NULL**, size of the first raw input message data (minimum required buffer), in bytes, is returned in \**pcbSize*. +If **NULL**, the size of the first pending raw input message, in bytes, is returned in \**pcbSize*. The queue is not modified. ### -param pcbSize [in, out] Type: **PUINT** -The size, in bytes, of the provided [RAWINPUT](ns-winuser-rawinput.md) buffer. +The size, in bytes, of the provided [RAWINPUT](ns-winuser-rawinput.md) buffer. On return, contains the size of the first element that did not fit, or zero if all elements were read. ### -param cbSizeHeader [in] @@ -79,20 +79,28 @@ Type: **UINT** If *pData* is **NULL** and the function is successful, the return value is zero. If *pData* is not **NULL** and the function is successful, the return value is the number of [RAWINPUT](ns-winuser-rawinput.md) structures written to *pData*. -If an error occurs, the return value is (**UINT**)-1. Call [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) for the error code. +If an error occurs, the return value is (**UINT**)-1. Call [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) for the error code. A common error is **ERROR_INSUFFICIENT_BUFFER**, which means the buffer is too small to hold the first pending element — in this case \**pcbSize* is updated with the required size and the function should be retried with a larger buffer. ## -remarks When an application receives raw input, its message queue gets a [WM_INPUT](/windows/win32/inputdev/wm-input) message and the queue status flag [QS_RAWINPUT](nf-winuser-getqueuestatus.md) is set. -Using **GetRawInputBuffer**, the raw input data is read in the array of variable size [RAWINPUT](ns-winuser-rawinput.md) structures and corresponding [WM_INPUT](/windows/win32/inputdev/wm-input) messages are removed from the calling thread's message queue. You can call this method several times with buffer that cannot fit all message's data until all raw input messages have been read. +**GetRawInputBuffer** reads [WM_INPUT](/windows/win32/inputdev/wm-input) messages directly from the calling thread's raw input queue and removes them as they are read. You can call this function several times until all raw input messages have been read. When all messages have been successfully read and *pData* is not **NULL**, the [QS_RAWINPUT](nf-winuser-getqueuestatus.md) flag is cleared from the calling thread's message queue status. The [NEXTRAWINPUTBLOCK](nf-winuser-nextrawinputblock.md) macro allows an application to traverse an array of [RAWINPUT](ns-winuser-rawinput.md) structures. -If all raw input messages have been successfully read from message queue then [QS_RAWINPUT](nf-winuser-getqueuestatus.md) flag is cleared from the calling thread's message queue status. +**Important:** **GetRawInputBuffer** only sees [WM_INPUT](/windows/win32/inputdev/wm-input) messages that are still present in the raw input queue. When [GetMessage](/windows/win32/api/winuser/nf-winuser-getmessage) retrieves a [WM_INPUT](/windows/win32/inputdev/wm-input) message, it removes that message from the queue before returning — so **GetRawInputBuffer** will not see it. The removed event must be read via [GetRawInputData](/windows/win32/api/winuser/nf-winuser-getrawinputdata) using the **HRAWINPUT** handle passed in *lParam*. Only events that arrived after the current one are visible to **GetRawInputBuffer**. + +Therefore, when using **GetRawInputBuffer** from a [WM_INPUT](/windows/win32/inputdev/wm-input) handler or after [GetMessage](/windows/win32/api/winuser/nf-winuser-getmessage), the correct pattern is: + +1. Read the current event via [GetRawInputData](/windows/win32/api/winuser/nf-winuser-getrawinputdata) using the *lParam* handle. +2. Call **GetRawInputBuffer** in a loop to drain any additional events that accumulated in the queue. +3. Call [DefWindowProc](/windows/win32/api/winproc/nf-winproc-defwndproc) after processing the message. + +See [Performing a Buffered Read of Raw Input](/windows/win32/inputdev/using-raw-input#performing-a-buffered-read-of-raw-input) for complete code samples. > [!NOTE] -> WOW64: To get the correct size of the raw input buffer, do not use \**pcbSize*, use \**pcbSize* \* 8 instead. To ensure **GetRawInputBuffer** behaves properly on WOW64, you must align the [RAWINPUT](ns-winuser-rawinput.md) structure by 8 bytes. The following code shows how to align **RAWINPUT** for WOW64. +> WOW64: To get the correct size of the raw input buffer, do not use \**pcbSize*, use \**pcbSize* \* 8 instead. To ensure **GetRawInputBuffer** behaves properly on WOW64, you must align the [RAWINPUT](ns-winuser-rawinput.md) structure by 8 bytes. ```csharp [StructLayout(LayoutKind.Explicit)] @@ -118,6 +126,8 @@ internal struct RAWINPUT [GetMessage](nf-winuser-getmessage.md) +[GetRawInputData](nf-winuser-getrawinputdata.md) + [NEXTRAWINPUTBLOCK](nf-winuser-nextrawinputblock.md) [RAWINPUT](ns-winuser-rawinput.md) From b5882c0c943af72e0e147cbfc56148a74a77888f Mon Sep 17 00:00:00 2001 From: Dimitriy Ryazantcev Date: Wed, 18 Mar 2026 15:19:58 +0200 Subject: [PATCH 2/6] Update WOW64 note with alignment code example Added code example for aligning RAWINPUT structure on WOW64. --- sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md b/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md index c66a0efc0e41..ae8487c651f9 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md +++ b/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md @@ -100,7 +100,7 @@ Therefore, when using **GetRawInputBuffer** from a [WM_INPUT](/windows/win32/inp See [Performing a Buffered Read of Raw Input](/windows/win32/inputdev/using-raw-input#performing-a-buffered-read-of-raw-input) for complete code samples. > [!NOTE] -> WOW64: To get the correct size of the raw input buffer, do not use \**pcbSize*, use \**pcbSize* \* 8 instead. To ensure **GetRawInputBuffer** behaves properly on WOW64, you must align the [RAWINPUT](ns-winuser-rawinput.md) structure by 8 bytes. +> WOW64: To get the correct size of the raw input buffer, do not use \**pcbSize*, use \**pcbSize* \* 8 instead. To ensure **GetRawInputBuffer** behaves properly on WOW64, you must align the [RAWINPUT](ns-winuser-rawinput.md) structure by 8 bytes. The following code shows how to align **RAWINPUT** for WOW64. ```csharp [StructLayout(LayoutKind.Explicit)] From ff4b12904cb30c7cd3d2ad5c2dc64f9baf62cdc2 Mon Sep 17 00:00:00 2001 From: Dimitriy Ryazantcev Date: Wed, 18 Mar 2026 15:20:24 +0200 Subject: [PATCH 3/6] Fix note on RAWINPUT alignment for WOW64 Corrected a note regarding RAWINPUT alignment for WOW64. --- sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md b/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md index ae8487c651f9..0fd26caae772 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md +++ b/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md @@ -100,7 +100,7 @@ Therefore, when using **GetRawInputBuffer** from a [WM_INPUT](/windows/win32/inp See [Performing a Buffered Read of Raw Input](/windows/win32/inputdev/using-raw-input#performing-a-buffered-read-of-raw-input) for complete code samples. > [!NOTE] -> WOW64: To get the correct size of the raw input buffer, do not use \**pcbSize*, use \**pcbSize* \* 8 instead. To ensure **GetRawInputBuffer** behaves properly on WOW64, you must align the [RAWINPUT](ns-winuser-rawinput.md) structure by 8 bytes. The following code shows how to align **RAWINPUT** for WOW64. +> WOW64: To get the correct size of the raw input buffer, do not use \**pcbSize*, use \**pcbSize* \* 8 instead. To ensure **GetRawInputBuffer** behaves properly on WOW64, you must align the [RAWINPUT](ns-winuser-rawinput.md) structure by 8 bytes. The following code shows how to align **RAWINPUT** for WOW64. ```csharp [StructLayout(LayoutKind.Explicit)] From 8325b7268808d9f30e73e7e9df573fe6acd1d94d Mon Sep 17 00:00:00 2001 From: Dimitriy Ryazantcev Date: Wed, 18 Mar 2026 15:36:51 +0200 Subject: [PATCH 4/6] Update GetRawInputData documentation --- .../winuser/nf-winuser-getrawinputdata.md | 79 ++++++++----------- 1 file changed, 32 insertions(+), 47 deletions(-) diff --git a/sdk-api-src/content/winuser/nf-winuser-getrawinputdata.md b/sdk-api-src/content/winuser/nf-winuser-getrawinputdata.md index cb32925f72cb..21216f5019ea 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getrawinputdata.md +++ b/sdk-api-src/content/winuser/nf-winuser-getrawinputdata.md @@ -56,85 +56,70 @@ req.apiset: ext-ms-win-ntuser-rawinput-l1-1-0 (introduced in Windows 10, version # GetRawInputData function - ## -description -Retrieves the raw input from the specified device. +Retrieves the raw input data from the specified [RAWINPUT](ns-winuser-rawinput.md) handle. ## -parameters ### -param hRawInput [in] -Type: HRAWINPUT +Type: **HRAWINPUT** -A handle to the RAWINPUT structure. This comes from the lParam in WM_INPUT. +A handle to the [RAWINPUT](ns-winuser-rawinput.md) structure. This handle is passed in the *lParam* of a [WM_INPUT](/windows/win32/inputdev/wm-input) message. ### -param uiCommand [in] -Type: UINT - -The command flag. This parameter can be one of the following values. - - - - - - - - - - - - - - -
ValueMeaning
-
RID_HEADER
-
0x10000005
-
-		 -Get the header information from the RAWINPUT structure. - -
-
RID_INPUT
-
0x10000003
-
-		 -Get the raw data from the RAWINPUT structure. - -
+Type: **UINT** + +The command flag specifying which part of the [RAWINPUT](ns-winuser-rawinput.md) structure to retrieve. This parameter can be one of the following values. + +| Value | Meaning | +|-------|---------| +| **RID_HEADER** 0x10000005 | Retrieve only the [RAWINPUTHEADER](ns-winuser-rawinputheader.md) from the [RAWINPUT](ns-winuser-rawinput.md) structure. *pData* must point to a **RAWINPUTHEADER**-sized buffer. | +| **RID_INPUT** 0x10000003 | Retrieve the complete [RAWINPUT](ns-winuser-rawinput.md) structure including device-specific data. | ### -param pData [out, optional] -Type: LPVOID +Type: **LPVOID** + +A pointer to the buffer that receives the data. The type of data depends on the value of *uiCommand*: a [RAWINPUTHEADER](ns-winuser-rawinputheader.md) for **RID_HEADER**, or a complete [RAWINPUT](ns-winuser-rawinput.md) structure for **RID_INPUT**. -A pointer to the data that comes from the RAWINPUT structure. This depends on the value of uiCommand. Pointer should be aligned on a **DWORD** (32-bit) boundary. +If **NULL**, the required size of the buffer is returned in \**pcbSize* and the function returns zero. -If pData is NULL, the required size of the buffer is returned in *pcbSize. +If the buffer is too small, the function returns (**UINT**)-1, sets **ERROR_INSUFFICIENT_BUFFER**, and returns the required size in \**pcbSize*. ### -param pcbSize [in, out] -Type: PUINT +Type: **PUINT** -The size, in bytes, of the data in pData. +On input, the size in bytes of the buffer pointed to by *pData*. On output, if the buffer is too small, receives the required size in bytes. ### -param cbSizeHeader [in] -Type: UINT +Type: **UINT** -The size, in bytes, of the RAWINPUTHEADER structure. +The size, in bytes, of the [RAWINPUTHEADER](ns-winuser-rawinputheader.md) structure. Must be `sizeof(RAWINPUTHEADER)`, otherwise the function fails with **ERROR_INVALID_PARAMETER**. ## -returns -Type: UINT +Type: **UINT** -If pData is NULL and the function is successful, the return value is 0. If pData is not NULL and the function is successful, the return value is the number of bytes copied into pData. +If *pData* is **NULL** and the function is successful, the return value is zero and \**pcbSize* contains the required buffer size. -If there is an error, the return value is (UINT)-1. +If *pData* is not **NULL** and the function is successful, the return value is the number of bytes copied into *pData*. + +If an error occurs, the return value is (**UINT**)-1. Call [GetLastError](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror) for the error code. ## -remarks -GetRawInputData gets the raw input one RAWINPUT structure at a time. In contrast, GetRawInputBuffer gets an array of RAWINPUT structures. +**GetRawInputData** retrieves one [RAWINPUT](ns-winuser-rawinput.md) structure at a time using the **HRAWINPUT** handle passed in *lParam* of a [WM_INPUT](/windows/win32/inputdev/wm-input) message. In contrast, [GetRawInputBuffer](/windows/win32/api/winuser/nf-winuser-getrawinputbuffer) retrieves an array of **RAWINPUT** structures accumulated in the thread's raw input queue. + +**Handle lifetime:** The **HRAWINPUT** handle in *lParam* is valid for the duration of the [WM_INPUT](/windows/win32/inputdev/wm-input) message handler. It is freed internally on the next call to [GetMessage](/windows/win32/api/winuser/nf-winuser-getmessage) or [PeekMessage](/windows/win32/api/winuser/nf-winuser-peekmessagew) with **PM_REMOVE** via a deferred cleanup mechanism. **GetRawInputData** must be called before then. + +**Relationship with GetRawInputBuffer:** [GetMessage](/windows/win32/api/winuser/nf-winuser-getmessage) removes the current [WM_INPUT](/windows/win32/inputdev/wm-input) from the raw input queue before returning. As a result, [GetRawInputBuffer](/windows/win32/api/winuser/nf-winuser-getrawinputbuffer) will not see the current event — only events that arrived after it. + +See [Performing a Buffered Read of Raw Input](/windows/win32/inputdev/using-raw-input#performing-a-buffered-read-of-raw-input) for complete code samples. ## -see-also From 1fd7f7744c60666340b21bcf83cbb8f04210f45e Mon Sep 17 00:00:00 2001 From: Dimitriy Ryazantcev Date: Wed, 18 Mar 2026 15:42:40 +0200 Subject: [PATCH 5/6] Update GetRawInputData documentation --- .../winuser/nf-winuser-getrawinputdata.md | 20 ++++++++----------- 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/sdk-api-src/content/winuser/nf-winuser-getrawinputdata.md b/sdk-api-src/content/winuser/nf-winuser-getrawinputdata.md index 21216f5019ea..15cfe9265635 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getrawinputdata.md +++ b/sdk-api-src/content/winuser/nf-winuser-getrawinputdata.md @@ -113,26 +113,22 @@ If an error occurs, the return value is (**UINT**)-1. Call [GetLastError](/windo ## -remarks -**GetRawInputData** retrieves one [RAWINPUT](ns-winuser-rawinput.md) structure at a time using the **HRAWINPUT** handle passed in *lParam* of a [WM_INPUT](/windows/win32/inputdev/wm-input) message. In contrast, [GetRawInputBuffer](/windows/win32/api/winuser/nf-winuser-getrawinputbuffer) retrieves an array of **RAWINPUT** structures accumulated in the thread's raw input queue. +**GetRawInputData** retrieves one [RAWINPUT](ns-winuser-rawinput.md) structure at a time using the **HRAWINPUT** handle passed in *lParam* of a [WM_INPUT](/windows/win32/inputdev/wm-input) message. In contrast, [GetRawInputBuffer](nf-winuser-getrawinputbuffer.md) retrieves an array of **RAWINPUT** structures accumulated in the thread's raw input queue. -**Handle lifetime:** The **HRAWINPUT** handle in *lParam* is valid for the duration of the [WM_INPUT](/windows/win32/inputdev/wm-input) message handler. It is freed internally on the next call to [GetMessage](/windows/win32/api/winuser/nf-winuser-getmessage) or [PeekMessage](/windows/win32/api/winuser/nf-winuser-peekmessagew) with **PM_REMOVE** via a deferred cleanup mechanism. **GetRawInputData** must be called before then. +**Handle lifetime:** The **HRAWINPUT** handle in *lParam* is valid for the duration of the [WM_INPUT](/windows/win32/inputdev/wm-input) message handler. It is freed internally on the next call to [GetMessage](nf-winuser-getmessage.md) or [PeekMessage](nf-winuser-peekmessagew.md) with **PM_REMOVE** via a deferred cleanup mechanism. **GetRawInputData** must be called before then. -**Relationship with GetRawInputBuffer:** [GetMessage](/windows/win32/api/winuser/nf-winuser-getmessage) removes the current [WM_INPUT](/windows/win32/inputdev/wm-input) from the raw input queue before returning. As a result, [GetRawInputBuffer](/windows/win32/api/winuser/nf-winuser-getrawinputbuffer) will not see the current event — only events that arrived after it. +**Relationship with GetRawInputBuffer:** [GetMessage](nf-winuser-getmessage.md) removes the current [WM_INPUT](/windows/win32/inputdev/wm-input) from the raw input queue before returning. As a result, [GetRawInputBuffer](nf-winuser-getrawinputbuffer.md) will not see the current event — only events that arrived after it. See [Performing a Buffered Read of Raw Input](/windows/win32/inputdev/using-raw-input#performing-a-buffered-read-of-raw-input) for complete code samples. ## -see-also -Conceptual +**Conceptual** -GetRawInputBuffer +[GetRawInputBuffer](nf-winuser-getrawinputbuffer.md) -RAWINPUT +[RAWINPUT](ns-winuser-rawinput.md) -RAWINPUTHEADER +[RAWINPUTHEADER](ns-winuser-rawinputheader.md) -Raw Input - - - -Reference +[Raw Input](/windows/win32/inputdev/raw-input) From 627e4c41507f889f82b2fe38ab38debd14662172 Mon Sep 17 00:00:00 2001 From: Dimitriy Ryazantcev Date: Wed, 18 Mar 2026 15:46:16 +0200 Subject: [PATCH 6/6] Fix links and formatting in GetRawInputBuffer documentation --- sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md b/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md index 0fd26caae772..e5ccdc849b8e 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md +++ b/sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md @@ -89,11 +89,11 @@ When an application receives raw input, its message queue gets a [WM_INPUT](/win The [NEXTRAWINPUTBLOCK](nf-winuser-nextrawinputblock.md) macro allows an application to traverse an array of [RAWINPUT](ns-winuser-rawinput.md) structures. -**Important:** **GetRawInputBuffer** only sees [WM_INPUT](/windows/win32/inputdev/wm-input) messages that are still present in the raw input queue. When [GetMessage](/windows/win32/api/winuser/nf-winuser-getmessage) retrieves a [WM_INPUT](/windows/win32/inputdev/wm-input) message, it removes that message from the queue before returning — so **GetRawInputBuffer** will not see it. The removed event must be read via [GetRawInputData](/windows/win32/api/winuser/nf-winuser-getrawinputdata) using the **HRAWINPUT** handle passed in *lParam*. Only events that arrived after the current one are visible to **GetRawInputBuffer**. +**Important:** **GetRawInputBuffer** only sees [WM_INPUT](/windows/win32/inputdev/wm-input) messages that are still present in the raw input queue. When [GetMessage](nf-winuser-getmessage.md) retrieves a [WM_INPUT](/windows/win32/inputdev/wm-input) message, it removes that message from the queue before returning — so **GetRawInputBuffer** will not see it. The removed event must be read via [GetRawInputData](nf-winuser-getrawinputdata.md) using the **HRAWINPUT** handle passed in *lParam*. Only events that arrived after the current one are visible to **GetRawInputBuffer**. -Therefore, when using **GetRawInputBuffer** from a [WM_INPUT](/windows/win32/inputdev/wm-input) handler or after [GetMessage](/windows/win32/api/winuser/nf-winuser-getmessage), the correct pattern is: +Therefore, when using **GetRawInputBuffer** from a [WM_INPUT](/windows/win32/inputdev/wm-input) handler or after [GetMessage](nf-winuser-getmessage.md), the correct pattern is: -1. Read the current event via [GetRawInputData](/windows/win32/api/winuser/nf-winuser-getrawinputdata) using the *lParam* handle. +1. Read the current event via [GetRawInputData](nf-winuser-getrawinputdata.md) using the *lParam* handle. 2. Call **GetRawInputBuffer** in a loop to drain any additional events that accumulated in the queue. 3. Call [DefWindowProc](/windows/win32/api/winproc/nf-winproc-defwndproc) after processing the message.