IDirectInput8::EnumDevicesBySemantics Method

Enumerates devices that most closely match the application-specified action map.

Syntax

HRESULT EnumDevicesBySemantics(      

    LPCTSTR ptszUserName,
    LPDIACTIONFORMAT lpdiActionFormat,
    LPDIENUMDEVICESBYSEMANTICSCB lpCallback,
    LPVOID pvRef,
    DWORD dwFlags
);

Parameters

ptszUserName
String identifying the current user, or NULL to specify the user logged onto the system. The user name is taken into account when enumerating devices. A device with user mappings is preferred to a device without any user mappings. By default, devices in use by other users are not enumerated for this user.
lpdiActionFormat
Address of a DIACTIONFORMAT structure that specifies the action map for which suitable devices are enumerated.
lpCallback
Address of a callback function to be called once for each device enumerated. See DIEnumDevicesBySemanticsCallback.
pvRef
Application-defined 32-bit value to pass to the enumeration callback each time it is called.
dwFlags
Flag value that specifies the scope of the enumeration. This parameter can be one or more of the following values.
DIEDBSFL_ATTACHEDONLY
Only attached and installed devices are enumerated.
DIEDBSFL_AVAILABLEDEVICES
Only unowned, installed devices are enumerated.
DIEDBSFL_FORCEFEEDBACK
Only devices that support force feedback are enumerated.
DIEDBSFL_MULTIMICEKEYBOARDS
Only secondary (non-system) keyboard and mouse devices.
DIEDBSFL_NONGAMINGDEVICES
Only HID-compliant devices whose primary purpose is not as a gaming device. Devices such as USB speakers and multimedia buttons on some keyboards would fall within this value.
DIEDBSFL_THISUSER
All installed devices for the user identified by ptszUserName, and all unowned devices, are enumerated.
DIEDBSFL_VALID
DIEDBSFL_VALID is also defined in Dinput.h, but is not used by applications.

Return Value

If the method succeeds, the return value is DI_OK.
If the method fails, the return value can be one of the following error values.
DIERR_INVALIDPARAM An invalid parameter was passed to the returning function, or the object was not in a state that permitted the function to be called. This value is equal to the E_INVALIDARG standard Component Object Model (COM) return value.
DIERR_NOTINITIALIZED The object has not been initialized.

Remarks

The keyboard and mouse are enumerated last.
Note The order in which devices are enumerated by Microsoft?DirectInput?is not guaranteed.

DIERR_INVALIDPARAM	An invalid parameter was passed to the returning function, or the object was not in a state that permitted the function to be called. This value is equal to the E_INVALIDARG standard Component Object Model (COM) return value.
DIERR_NOTINITIALIZED	The object has not been initialized.