Poll routine
The Poll callback is the polling routine used in DirectX 5.0 and later. This replaces the polling routine documented in the PollingCallback section.
Syntax
HRESULT Poll(
DWORD dwDeviceID,
LPDWORD lpdwMask,
LPVJPOLLDATA lpPollData
);
Parameters
dwDeviceID
Indicates the joystick ID number being used.lpdwMask
Points to a DWORD mask that describes the data requested on entry, and the data returned on exit. The mask is a combination of the following:JOYPD_X
Bitmask for the dwX member of the VJPOLLDATA structure.JOYPD_Y
Bitmask for the dwY member of the VJPOLLDATA structure.JOYPD_Z
Bitmask for the dwZ member of the VJPOLLDATA structure.JOYPD_R
Bitmask for the dwR member of the VJPOLLDATA structure.JOYPD_U
Bitmask for the dwU member of the VJPOLLDATA structure.JOYPD_V
Bitmask for the dwV member of the VJPOLLDATA structure.JOYPD_POV0
Bitmask for the dwPOV0 member of the VJPOLLDATA structure.JOYPD_POV1
Bitmask for the dwPOV1 member of the VJPOLLDATA structure.JOYPD_POV2
Bitmask for the dwPOV2 member of the VJPOLLDATA structure.JOYPD_POV3
Bitmask for the dwPOV3 member of the VJPOLLDATA structure.JOYPD_BTN0
Bitmask for the dwBTN0 member of the VJPOLLDATA structure.JOYPD_BTN1
Bitmask for the dwBTN1 member of the VJPOLLDATA structure.JOYPD_BTN2
Bitmask for the dwBTN2 member of the VJPOLLDATA structure.JOYPD_BTN3
Bitmask for the dwBTN3 member of the VJPOLLDATA structure.JOYPD_RESERVED0
Bitmask for the dwReserved0 member of the VJPOLLDATA structure.JOYPD_RESERVED1
Bitmask for the dwReserved1 member of the VJPOLLDATA structure.JOYPD_ELEMENT_MASK
Bitmask for all members of the VJPOLLDATA structure.JOYPD_POSITION
Bitmask for the position attribute of the device.JOYPD_VELOCITY
Bitmask for the velocity attribute of the device.JOYPD_ACCELERATION
Bitmask for the acceleration attribute of the device.JOYPD_FORCE
Bitmask for the force attribute of the device.JOYPD_ATTRIB_MASK
Bitmask for all possible attributes of the device.
lpPollData
Points to the polling data.
Return value
Returns S_OK if the poll was completed successfully; returns S_FALSE if returned data is (partially or wholly) out of date; otherwise, returns an error code.
Remarks
The upper and lower words of the lpdwMask parameter are treated separately. The lower word is a simple bitmask of the elements in the VJPOLLDATA structure. The upper word describes the attributes for which these elements are requested. The lpPollData parameter to the poll contains an array of at least as many VJPOLLDATA structures as there are bits set in the upper word of the mask.
The first VJPOLLDATA structure should contain the position information. The next three VJPOLLDATA structures should contain information about the acceleration, velocity, and force, in that order. For example, if the device only supports position and force, the first structure contains position data, the second and third structures are empty and, therefore, are skipped, and the fourth structure contains force information.
The minidriver should always set the mask to what it can return, even if the poll fails because the device is unplugged. So if the device has less than 33 buttons, X, Y, and R, for position only, it should perform an operation such as the following before searching for the available data:
*pdwMask &= ( JOYPD_POSITION | JOYPD_BTN0 | JOYPD_X | JOYPD_Y | JOYPD_R );
If the device can return data for more than one attribute, the upper word has a bit set for each attribute and the lower word should have the bit set for any element that can be returned for any of the supported attributes. So even though force is an unlikely value for the button masks (which are single-bit), if the device reports buttons in the position data and force for X and Y, then position, force, X, Y, and buttons should all have their bits set.