Platform SDK: DirectX

DirectInput Device Enumeration

DirectInput can query the system for all available input devices, determine whether they are connected, and return information about them. This process is called enumeration.

[C++]

If your application is using only the standard keyboard or mouse, or both, you do not need to enumerate the available input devices. As explained under Creating the DirectInput Device, you can use predefined global variables when calling the IDirectInput7::CreateDeviceEx method.

For all other input devices, and for systems with multiple keyboards or mouse devices, call IDirectInput7::EnumDevices to obtain at least the instance globally unique identifiers (GUIDs) so that DirectInputDevice objects can be created. You might also want to enumerate to give the user a choice of available devices.

The following is a sample implementation of the IDirectInput7::EnumDevices method:

/* lpdi is a valid IDirectInput7 interface pointer. */
 
GUID              KeyboardGUID = GUID_SysKeyboard; 
 
lpdi->EnumDevices(DIDEVTYPE_KEYBOARD, 
                  DIEnumDevicesCallback, 
                  &KeyboardGUID, 
                  DIEDFL_ATTACHEDONLY); 

The first parameter determines what types of devices are to be enumerated. It is NULL if you want to enumerate all devices, regardless of type; otherwise, it is one of the DIDEVTYPE_* values described in DIDEVICEINSTANCE.

The second parameter is a pointer to a callback function to be called once for each device enumerated. This function can be called by any name; the documentation uses the placeholder name DIEnumDevicesCallback.

The third parameter to the EnumDevices method is any 32-bit value that you want to pass into the callback function. In this example, it is a pointer to a variable of type GUID, passed in so that the callback can assign a keyboard instance GUID.

The fourth parameter is a flag to request enumeration of either all devices or only those that are attached (DIEDFL_ALLDEVICES or DIEDFL_ATTACHEDONLY).

If your application is using more than one input device, the callback function is a good place to initialize each device as it is enumerated. (For an example, see Tutorial 3: Using the Joystick.) You obtain the instance GUID of the device from the callback function. You can also perform other processing here, such as looking for particular subtypes of devices or adding the device name to a list box.

The following code example checks for the presence of an enhanced keyboard and stops the enumeration as soon as it finds one. It assigns the instance GUID of the last keyboard found to the KeyboardGUID variable (passed in as pvRef by the previous example of a EnumDevices call), which can then be used in a call to IDirectInput7::CreateDeviceEx.

BOOL          hasEnhanced; 
 
BOOL CALLBACK DIEnumKbdCallback(LPCDIDEVICEINSTANCE lpddi, 
                            LPVOID pvRef) 
{ 
  *(GUID*) pvRef = lpddi->guidInstance; 
  if (GET_DIDEVICE_SUBTYPE(lpddi->dwDevType) == 
                       DIDEVTYPEKEYBOARD_PCENH) 
  { 
    hasEnhanced = TRUE; 
    return DIENUM_STOP; 
  } 
  return DIENUM_CONTINUE; 
} // End of callback 

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

The second parameter points to data passed in from EnumDevices. In this case, it is a pointer to the variable KeyboardGUID. This variable was assigned a default value earlier, but it is given a new value each time that a device is enumerated. It is not important what instance GUID you use for a single keyboard, but the code example illustrates a technique for retrieving an instance GUID from the callback.

The return value in this case indicates that enumeration is to stop if the sought-for device has been found, or otherwise that it is to continue. Enumeration automatically stops as soon as all devices have been enumerated.

[Visual Basic]

If your application is using only the standard keyboard or mouse, or both, you do not need to enumerate the available input devices. As explained under Creating a DirectInput Device, you can use predefined GUID aliases when calling the DirectInput.CreateDevice method.

For all other input devices, and for systems with multiple keyboards or mouse devices, call DirectInput.GetDIEnumDevices to build a collection of available devices. This method returns a DirectInputEnumDevices object representing the collection. Each device in the collection can be retrieved as a DirectInputDeviceInstance object by using the DirectInputEnumDevices.GetItem method.

At the very least, you must retrieve the unique identifier for a nonstandard device by calling DirectInputDeviceInstance.GetGuidInstance before you can create a DirectInputDevice object for that device. You might also want to enumerate devices to look for particular types and subtypes (by using DirectInputDeviceInstance.GetDevType) or to populate a list box that allows the user to select a game controller.

You might even want to search for a device with particular capabilities. To do this, you must create a DirectInputDevice object for each candidate to examine it further by using the DirectInputDevice.GetCapabilities method.