Platform SDK: DirectX |
The DirectInputDevice.SendDeviceData method sends data to a device that accepts output. The device must be in an acquired state.
object.SendDeviceData(count As Long, _ data() As DIDEVICEOBJECTDATA, _ flags As CONST_DESDDFLAGS) As Long
The lOfs field of each DIDEVICEOBJECTDATA type must contain the instance identifier (not the data offset) for the device object to which the data is directed. (See DirectInputDeviceObjectInstance.GetType.) The lTimeStamp and lSequence members must be 0.
If the method fails, an error is raised and Err.Number may be one of the following error codes:
DIERR_INPUTLOST |
DIERR_NOTACQUIRED |
DIERR_REPORTFULL |
DIERR_UNPLUGGED |
There is no guarantee that the individual data elements will be sent in a particular order. However, data sent by successive calls to SendDeviceData will not be 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 will be sent a single packet. The A field of the packet will contain the value 1, and the B field of the packet will be either 2 or 0.
If the data must to be sent to the device exactly as specified, then three calls to SendDeviceData should be performed, each call sending one data element.
In response to the first call, the device will be sent a packet where the A field is blank and the B field contains the value 2.
In response to the second call, the device will be sent a packet where the A field contains the value 1, and the B field is blank.
Finally, in response to the third call, the device will be sent a packet where the A field is blank and the B field contains the value 0.
If the DISDD_CONTINUE flag is set, then the device data sent will be overlaid on the previously sent device data. Otherwise, the device data sent will start from scratch.
For example, suppose a device supports two button outputs, Button0 and Button1. If an application first calls SendDeviceData passing "Button0 pressed", then 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, then 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".