Device Object Enumeration

It may be necessary for your application to determine what buttons or axes are available on a given device. To do this you enumerate the device objects in much the same way you enumerate devices.

To some extent IDirectInputDevice::EnumObjects overlaps the functionality of IDirectInputDevice::GetCapabilities. Either method may be used to determine how many buttons or axes are available. However, EnumObjects is really intended for cataloguing all the available objects rather than checking for a particular one. The DIQuick application in the DirectX code samples in the Platform SDK References, for example, uses EnumObjects to populate the list on the Objects page for the selected device.

Like IDirectInput::EnumDevices, the EnumObjects function has a callback function that gives you the chance to do other processing on each object – for example, adding it to a list or creating a corresponding element on a user interface.

Here's a callback function that simply extracts the name of each object so that it can be added to a string list or array. This standard callback is documented under the placeholder name DIEnumDeviceObjectsProc, but you can give it any name you like. Remember, this function is called once for each object enumerated.

char  szName[MAX_PATH]; 
 
BOOL CALLBACK DIEnumDeviceObjectsProc( 
                      LPCDIDEVICEOBJECTINSTANCE lpddoi,
                      LPVOID pvRef) 
{ 
  lstrcpy(szName, lpddoi->tszName); 
  // Now add szName to a list or array 
  . 
  . 
  . 
  return DIENUM_CONTINUE; 
} 
 

The first parameter points to a structure containing information about the object. This structure is created for you by DirectInput.

The second parameter is an application-defined pointer to data, equivalent to the second parameter to EnumObjects. In the example, this parameter is not used.

The return value in this case indicates that enumeration is to continue as long as there are still objects to be enumerated.

Now here's the call to the EnumObjects method, which puts the callback function to work.

lpdiMouse->EnumObjects(DIEnumDeviceObjectsProc, 
                       NULL, DIDFT_ALL); 
 

The first parameter is the address of the callback function.

The second parameter can be a pointer to any data you want to use or modify in the callback. The example does not use this parameter and so passes NULL.

The third parameter is a flag to indicate which type or types of objects are to be included in the enumeration. In the example, all objects are to be enumerated. To restrict the enumeration, you can use one or more of the other DIDFT_* flags listed in the reference for IDirectInput::EnumDevices.

Note  Some of the DIDFT_* flags are combinations of others; for example, DIDFT_AXIS is equivalent to DIDFT_ABSAXIS | DIDFT_RELAXIS.