Skip to content

Clarify Raw Input buffer semantics, alignment, and handle lifetime #2190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DJm00n wants to merge 6 commits into
base: docs
Choose a base branch
from
Open

Clarify Raw Input buffer semantics, alignment, and handle lifetime #2190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
49f2ab9
Clarify GetRawInputBuffer alignment and error handling
DJm00n Mar 18, 2026
b5882c0
Update WOW64 note with alignment code example
DJm00n Mar 18, 2026
ff4b129
Fix note on RAWINPUT alignment for WOW64
DJm00n Mar 18, 2026
8325b72
Update GetRawInputData documentation
DJm00n Mar 18, 2026
1fd7f77
Update GetRawInputData documentation
DJm00n Mar 18, 2026
627e4c4
Fix links and formatting in GetRawInputBuffer documentation
DJm00n Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 16 additions & 6 deletions sdk-api-src/content/winuser/nf-winuser-getrawinputbuffer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]

Expand All @@ -79,17 +79,25 @@ 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](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](nf-winuser-getmessage.md), the correct pattern is:

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.

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.
Expand Down Expand Up @@ -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)
Expand Down
89 changes: 35 additions & 54 deletions sdk-api-src/content/winuser/nf-winuser-getrawinputdata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,98 +56,79 @@ 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: <b>HRAWINPUT</b>
Type: **HRAWINPUT**

A handle to the <a href="/windows/desktop/api/winuser/ns-winuser-rawinput">RAWINPUT</a> structure. This comes from the <i>lParam</i> in <a href="/windows/desktop/inputdev/wm-input">WM_INPUT</a>.
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: <b>UINT</b>

The command flag. This parameter can be one of the following values.

<table>
<tr>
<th>Value</th>
<th>Meaning</th>
</tr>
<tr>
<td width="40%"><a id="RID_HEADER"></a><a id="rid_header"></a><dl>
<dt><b>RID_HEADER</b></dt>
<dt>0x10000005</dt>
</dl>
</td>
<td width="60%">
Get the header information from the <a href="/windows/desktop/api/winuser/ns-winuser-rawinput">RAWINPUT</a> structure.

</td>
</tr>
<tr>
<td width="40%"><a id="RID_INPUT"></a><a id="rid_input"></a><dl>
<dt><b>RID_INPUT</b></dt>
<dt>0x10000003</dt>
</dl>
</td>
<td width="60%">
Get the raw data from the <a href="/windows/desktop/api/winuser/ns-winuser-rawinput">RAWINPUT</a> structure.

</td>
</tr>
</table>
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: <b>LPVOID</b>
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 <a href="/windows/desktop/api/winuser/ns-winuser-rawinput">RAWINPUT</a> structure. This depends on the value of <i>uiCommand</i>. 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 <i>pData</i> is <b>NULL</b>, the required size of the buffer is returned in *<i>pcbSize</i>.
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: <b>PUINT</b>
Type: **PUINT**

The size, in bytes, of the data in <i>pData</i>.
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: <b>UINT</b>
Type: **UINT**

The size, in bytes, of the <a href="/windows/desktop/api/winuser/ns-winuser-rawinputheader">RAWINPUTHEADER</a> 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: <b>UINT</b>
Type: **UINT**

If <i>pData</i> is <b>NULL</b> and the function is successful, the return value is 0. If <i>pData</i> is not <b>NULL</b> 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 (<b>UINT</b>)-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

<b>GetRawInputData</b> gets the raw input one <a href="/windows/desktop/api/winuser/ns-winuser-rawinput">RAWINPUT</a> structure at a time. In contrast, <a href="/windows/desktop/api/winuser/nf-winuser-getrawinputbuffer">GetRawInputBuffer</a> gets an array of <b>RAWINPUT</b> 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](nf-winuser-getrawinputbuffer.md) retrieves an array of **RAWINPUT** structures accumulated in the thread's raw input queue.

## -see-also
**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.

<b>Conceptual</b>
**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.

<a href="/windows/desktop/api/winuser/nf-winuser-getrawinputbuffer">GetRawInputBuffer</a>
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.

<a href="/windows/desktop/api/winuser/ns-winuser-rawinput">RAWINPUT</a>
## -see-also

<a href="/windows/desktop/api/winuser/ns-winuser-rawinputheader">RAWINPUTHEADER</a>
**Conceptual**

<a href="/windows/desktop/inputdev/raw-input">Raw Input</a>
[GetRawInputBuffer](nf-winuser-getrawinputbuffer.md)

[RAWINPUT](ns-winuser-rawinput.md)

[RAWINPUTHEADER](ns-winuser-rawinputheader.md)

<b>Reference</b>
[Raw Input](/windows/win32/inputdev/raw-input)