IDirectInputDevice7::SendDeviceData

The IDirectInputDevice7::SendDeviceData method sends data to a device that accepts output. The device must be in an acquired state.

HRESULT SendDeviceData(
  DWORD cbObjectData, 
  LPCDIDEVICEOBJECTDATA rgdod, 
  LPDWORD pdwInOut, 
  DWORD fl  
);

Parameters

cbObjectData

Size, in bytes, of a single DIDEVICEOBJECTDATA structure.

rgdod

Array of DIDEVICEOBJECTDATA structures containing the data to send to the device. It must consist of *pdwInOut elements.

The dwOfs field of each DIDEVICEOBJECTDATA structure must contain the device object identifier (as obtained from the dwType field of the DIDEVICEOBJECTINSTANCE structure) for the device object to which the data is directed. The dwTimeStamp and dwSequence members must be 0.

pdwInOut

On entry, the variable pointed to by this parameter contains the number of elements in the array pointed to by rgdod. On exit, it contains the number of elements sent to the device.

fl

Flags controlling the manner in which data is sent. This can be 0 or the following value:

DISDD_CONTINUE

The device data sent is overlaid on the previously sent device data. See Remarks.

Return Values

If the method succeeds, the return value is DI_OK.

If the method fails, the return value can be one of the following error values:

Remarks

There is no guarantee that the individual data elements will be sent in a particular order. However, data sent by successive calls to IDirectInputDevice7::SendDeviceData is not interleaved. Furthermore, if multiple pieces of data are sent to the same object with a single call, it is unspecified which piece of data is sent.

Consider, for example, a device that can be sent data in packets, each packet describing two pieces of information; call them A and B. Suppose the application attempts to send three data elements: B = 2, A = 1, and B = 0.

The actual device is sent a single packet. The A field of the packet contains the value 1, and the B field of the packet is either 2 or 0.

If the data must to be sent to the device exactly as specified, three calls to IDirectInputDevice7::SendDeviceData should be performed, each call sending one data element.

In response to the first call, the device is sent a packet in which the A field is blank and the B field contains the value 2.

In response to the second call, the device is sent a packet in which the A field contains the value 1, and the B field is blank.

Finally, in response to the third call, the device is sent a packet in which the A field is blank and the B field contains the value 0.

If the DISDD_CONTINUE flag is set, the device data sent is overlaid on the previously sent device data. Otherwise, the device data sent starts from scratch.

For example, suppose a device supports two button outputs, Button0 and Button1. If an application first calls IDirectInputDevice7::SendDeviceData passing "Button0 pressed", a packet of the form "Button0 pressed, Button1 not pressed" is sent to the device. If the application then makes another call, passing "Button1 pressed" and the DISDD_CONTINUE flag, a packet of the form "Button0 pressed, Button1 pressed" is sent to the device. However, if the application had not passed the DISDD_CONTINUE flag, the packet sent to the device would have been "Button0 not pressed, Button1 pressed".

Requirements

  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.