IDirectInputDevice::GetDeviceData

The IDirectInputDevice::GetDeviceData method 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, then 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 may be zero or the following flag:

DIGDD_PEEK

Do not remove the items from the buffer. A subsequent IDirectInputDevice::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 may be one of the following error values:

Remarks

Before device data can be obtained, you must set the data format by using the IDirectInputDevice::SetDataFormat method, set the buffer size with IDirectInputDevice::SetProperty method, and acquire the device by using the IDirectInputDevice::Acquire method.

The following 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 = IDirectInputDevice_GetDeviceData( 
    pdid, 
    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 example illustrates how this can be done:

dwItems = INFINITE; 
hres = IDirectInputDevice_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 fragment illustrates how this can be done:

dwItems = INFINITE; 
hres = IDirectInputDevice_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 
        // were successfully captured. 
    } 
} 
 

To query about whether a buffer overflow has occurred, set the rgdod parameter to NULL and the pdwInOut parameter to zero. The following example illustrates how this can be done:

dwItems = 0; 
hres = IDirectInputDevice_GetDeviceData( 
            pdid, 
            sizeof(DIDEVICEOBJECTDATA), 
            NULL, 
            &dwItems, 
            0); 
if (hres == DI_BUFFEROVERFLOW) { 
    // Buffer overflow occurred 
} 
 

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dinput.h.
  Import Library: Use dinput.lib.

See Also

IDirectInputDevice2::Poll, Polling and Events