| Microsoft DirectX 8.1 (C++) |
IDirectInputDevice8::GetDeviceData
Retrieves buffered data from the device.
HRESULT GetDeviceData( DWORD cbObjectData, LPDIDEVICEOBJECTDATA rgdod, LPDWORD pdwInOut, DWORD dwFlags );
Parameters
- cbObjectData
- Size of the DIDEVICEOBJECTDATA structure, in bytes.
- rgdod
- Array of DIDEVICEOBJECTDATA structures to receive the buffered data. The number of elements in this array must be equal to the value of the pdwInOut parameter. If this parameter is NULL, the buffered data is not stored anywhere, but all other side-effects take place.
- pdwInOut
- On entry, the number of elements in the array pointed to by the rgdod parameter. On exit, the number of elements actually obtained.
- dwFlags
- Flags that control the manner in which data is obtained. This value can be 0 or the following flag.
- DIGDD_PEEK
- Do not remove the items from the buffer. A subsequent IDirectInputDevice8::GetDeviceData call will read the same data. Normally, data is removed from the buffer after it is read.
Return Values
If the method succeeds, the return value is DI_OK or DI_BUFFEROVERFLOW.
If the method fails, the return value can be one of the following error values.
| DIERR_INPUTLOST |
| DIERR_INVALIDPARAM |
| DIERR_NOTACQUIRED |
| DIERR_NOTBUFFERED |
| DIERR_NOTINITIALIZED |
Remarks
In the debug version of Microsoft® DirectInput®, if a call is made to IDirectInputDevice8::GetDeviceData and the device has been unacquired, then random bytes will be sent to the device data buffer. To make sure you are not using random device data, always check for the DIERR_UNACQUIRED return code.
Before device data can be obtained, you must set the data format and the buffer size by using the IDirectInputDevice8::SetDataFormat and IDirectInputDevice8::SetProperty methods, or by using the IDirectInputDevice8::SetActionMap method. You must also acquire the device by using the IDirectInputDevice8::Acquire method. The maximum number of events that the buffer will hold is one less than the buffer size set with the IDirectInputDevice8::SetProperty method.
The following code example reads up to ten buffered data elements, removing them from the device buffer as they are read.
DIDEVICEOBJECTDATA rgdod[10];
DWORD dwItems = 10;
hres = IDirectInputDevice8_GetDeviceData(
sizeof(DIDEVICEOBJECTDATA),
rgdod,
&dwItems,
0);
if (SUCCEEDED(hres)) {
// dwItems = number of elements read (could be zero)
if (hres == DI_BUFFEROVERFLOW) {
// Buffer had overflowed.
}
}
Your application can flush the buffer and retrieve the number of flushed items by specifying NULL for the rgdod parameter and a pointer to a variable containing INFINITE for the pdwInOut parameter. The following code example illustrates how this can be done.
dwItems = INFINITE;
hres = IDirectInputDevice8_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
NULL,
&dwItems,
0);
if (SUCCEEDED(hres)) {
// Buffer successfully flushed
// dwItems = number of elements flushed
if (hres == DI_BUFFEROVERFLOW) {
// Buffer had overflowed.
}
}
Your application can query for the number of elements in the device buffer by setting the rgdod parameter to NULL, setting pdwInOut to INFINITE and setting dwFlags to DIGDD_PEEK. The following code example illustrates how this can be done.
dwItems = INFINITE;
hres = IDirectInputDevice8_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
NULL,
&dwItems,
DIGDD_PEEK);
if (SUCCEEDED(hres)) {
// dwItems = number of elements in buffer
if (hres == DI_BUFFEROVERFLOW) {
// Buffer overflow occurred; not all data
// was successfully captured.
}
}
To query about whether a buffer overflow has occurred, set the rgdod parameter to NULL and the pdwInOut parameter to 0. The following code example illustrates how this can be done.
dwItems = 0;
hres = IDirectInputDevice8_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
NULL,
&dwItems,
0);
if (hres == DI_BUFFEROVERFLOW) {
// Buffer overflow occurred.
}
Requirements
Windows NT/2000/XP: Requires Windows 2000.
Windows 98/Me: Requires Windows 98 or later. Available as a redistributable for Windows 98.
Header: Declared in Dinput.h.