To some extent, IDirectInputDevice7::EnumObjects overlaps the functionality of IDirectInputDevice7::GetCapabilities. Either method can be used to determine how many buttons or axes are available. However, EnumObjects is intended for cataloging all the available objects, rather than checking for a particular one. The DirectInput QuickTest application provided with the DirectX SDK, for example, uses EnumObjects to populate the list on the Objects tabbed page for the selected device.

Like IDirectInput7::EnumDevices, the EnumObjects method has a callback function that allows you to do other processing on each object—for example, adding it to a list or creating a corresponding element on a user interface.

The following code example 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 DIEnumDeviceObjectsCallback, but you can give it any name that you like. Remember, this function is called once for each object enumerated.

char  szName[MAX_PATH]; 
 
BOOL CALLBACK DIEnumDeviceObjectsCallback( 
                      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 objects to be enumerated.

The following code example calls the EnumObjects method, which puts the callback function to work.

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

The first parameter is the address of the callback function.

The second parameter can be a pointer to any data that you want to use or modify in the callback. The example does not use this parameter and, therefore, 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 IDirectInput7::EnumDevices.

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

You enumerate device objects by calling DirectInputDevice.GetDeviceObjectsEnum, which returns an instance of the DirectInputEnumDeviceObjects class representing the collection of available device objects that match the requested parameters.

The following code example enumerates axes on a device:

' diDev is a DirectInputDevice object.
 
Dim diEnumObjects As DirectInputEnumDeviceObjects
Set diEnumObjects = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

The parameter is a flag to indicate which type or types of objects are to be included in the enumeration.

Note  Some of the CONST_DIDFTFLAGS flags are combinations of others; for example, DIDFT_AXIS is equivalent to DIDFT_ABSAXIS OR DIDFT_RELAXIS.

To obtain information about a particular device object, call the methods of a DirectInputDeviceObjectInstance object obtained by calling DirectInputEnumDeviceObjects.GetItem. Information available for a device object includes its name, its type, and its offset in the data structure for the device.

The following code example lists the names of the axes enumerated in the previous example:

Dim diDevEnumObjects As DirectInputEnumDeviceObjects
Set diDevEnumObjects = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

Dim diDevObjInstance As DirectInputDeviceObjectInstance
Dim i As Integer
For i = 1 To diEnumObjects.GetCount
  Set diDevObjInstance = diEnumObjects.GetItem(i)
  Call List1.AddItem(diDevObjInstance.GetName)
Next i