GWLPUSERDATA

GWLP_USERDATA is a Windows API constant used with the GetWindowLongPtr and SetWindowLongPtr functions to access a per-window user data value. It provides a single pointer-sized field associated with a specific window instance, allowing applications to attach and retrieve application-defined data to window handles.

Usage and purpose:

- Setting data: SetWindowLongPtr(hWnd, GWLP_USERDATA, (LONG_PTR)pData) stores a pointer-sized value tied to that window.

- Retrieving data: pData = (Type*)GetWindowLongPtr(hWnd, GWLP_USERDATA) reads back the pointer-sized value.

- Common pattern: store a pointer to a C++ object or a structure that holds per-window state, enabling the window procedure to access instance data without global maps.

Relation to window memory:

GWLP_USERDATA refers to a slot in the window’s extra memory area, which is defined by the window class through cbWndExtra. Each window of that class can have its own GWLP_USERDATA value, separate from other windows.

Platform considerations:

GWLP_USERDATA is the portable, pointer-sized variant of GWL_USERDATA. Use GetWindowLongPtr and SetWindowLongPtr to be 64-bit safe; on 32-bit systems these map to the corresponding 32-bit functions. Do not cast between sign and pointer types carelessly, and ensure the data’s lifetime matches the window’s lifetime.

Notes and practices:

- The value is not automatically managed; it is the programmer’s responsibility to allocate, store, and release any associated data.

- If the window is destroyed, the stored pointer does not get freed unless explicitly handled in cleanup code.

- This mechanism is commonly used in object-oriented wrappers and custom window procedures to associate per-window state with the window handle.