IDirectInputDevice8::GetDeviceData Method

Retrieves buffered data from the device.

Syntax

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 Value

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 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 Interface 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 = idirectinputdevice9_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 = idirectinputdevice9_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 = idirectinputdevice9_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 = idirectinputdevice9_GetDeviceData( 
            pdid, 
            sizeof(DIDEVICEOBJECTDATA), 
            NULL, 
            &dwItems, 
            0); 
if (hres == DI_BUFFEROVERFLOW) { 
    // Buffer overflow occurred. 
} 

Requirements

Header: Declared in dinput.h.

See Also

IDirectInputDevice8::Poll
Polling and Event Notification