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	Access to the input device has been lost. It must be reacquired.
DIERR_INVALIDPARAM	An invalid parameter was passed to the returning function, or the object was not in a state that permitted the function to be called. This value is equal to the E_INVALIDARG standard Component Object Model (COM) return value.
DIERR_NOTACQUIRED	The operation cannot be performed unless the device is acquired.
DIERR_NOTBUFFERED	The device is not buffered. Set the DIPROP_BUFFERSIZE property to enable buffering.
DIERR_NOTINITIALIZED	The object has not been initialized.

Remarks

Note  If the method returns DI_BUFFEROVERFLOW, the data in the rgdod array has been truncated.

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 = 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. 
} 

See Also

IDirectInputDevice8::Poll, Polling and Event Notification