Using DirectInput

The first step in any Microsoft® DirectInput® application is obtaining the IDirectInput8 interface. You can do this most easily by calling the DirectInput8Create function.

You should create a single Microsoft® DirectInput object and not release it until the application terminates.

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 global variables when calling the IDirectInput8::CreateDevice method.

For all other input devices, and for systems with multiple keyboards or mouse devices, call IDirectInput8::EnumDevices or IDirectInput8::EnumDevicesBySemantics to enumerate available devices and find one that is suitable. You might also want to enumerate in order to give the user a choice of available devices.

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

/* lpdi is a valid IDirectInput8 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 declared 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 identifier to this variable.

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 sample callback function 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 (the address of which was passed in the pvRef variable by the call to EnumDevices in the previous example), which can then be passed to IDirectInput8::CreateDevice.

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 DIDEVICEINSTANCE structure containing information about the device. This structure is created 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 a device is enumerated. It is not important what instance GUID you use for a single keyboard, but the code does illustrate a technique for retrieving an instance GUID from the callback.

Rather than saving the instance GUID so that you can create the DirectInputDevice later, you can save the device created by DirectInput during enumeration. For more information, see Creating a DirectInput Device.

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

For more information on enumerating devices by using IDirectInput8::EnumDevicesBySemantics, see Action Mapping.