IDirectInputDevice8::EnumObjects Method

Article
09/10/2011

Enumerates the input and output objects available on a device.

Syntax

HRESULT EnumObjects(
         LPDIENUMDEVICEOBJECTSCALLBACK lpCallback,
         LPVOID pvRef,
         DWORD dwFlags
)

Parameters

lpCallback
Address of a callback function that receives DirectInputDevice objects. DirectInput provides a prototype of this function as DIEnumDeviceObjectsCallback.
pvRef
Reference data (context) for callback.
dwFlags
Flags that specify the types of object to be enumerated. Each of the following values restricts the enumeration to objects of the described type:
- DIDFT_ABSAXIS
  An absolute axis.
- DIDFT_ALIAS
  Controls identified by a Human Interface Device (HID) usage alias. This flag applies only to HID-compliant USB devices.
- DIDFT_ALL
  All objects.
- DIDFT_AXIS
  An axis, either absolute or relative.
- DIDFT_BUTTON
  A push button or a toggle button.
- DIDFT_COLLECTION
  A HID link collection. HID link collections do not generate data of their own.
- DIDFT_ENUMCOLLECTION(n)
  An object that belongs to HID link collection number n.
- DIDFT_FFACTUATOR
  An object that contains a force-feedback actuator. In other words, forces can be applied to this object.
- DIDFT_FFEFFECTTRIGGER
  An object that can be used to trigger force-feedback effects.
- DIDFT_NOCOLLECTION
  An object that does not belong to any HID link collection; in other words, an object for which the wCollectionNumber member of the DIDEVICEOBJECTINSTANCE structure is 0.
- DIDFT_NODATA
  An object that does not generate data.
- DIDFT_OUTPUT
  An object that supports output. For details, see Remarks in IDirectInputDevice8::SendDeviceData.
- DIDFT_POV
  A point-of-view controller.
- DIDFT_PSHBUTTON
  A push button. A push button is reported as down when the user presses it, and as up when the user releases it.
- DIDFT_RELAXIS
  A relative axis.
- DIDFT_TGLBUTTON
  A toggle button. A toggle button is reported as down when the user presses it and remains so until the user presses the button a second time.
- DIDFT_VENDORDEFINED
  An object of a type defined by the manufacturer.

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 DIERR_NOTINITIALIZED

Remarks

The DIDFT_FFACTUATOR and DIDFT_FFEFFECTTRIGGER flags in the dwFlags parameter restrict enumeration to objects that meet all the criteria defined by the included flags. For all the other flags, an object is enumerated if it meets the criterion defined by any included flag in this category. For example, (DIDFT_FFACTUATOR | DIDFT_FFEFFECTTRIGGER) restricts enumeration to force-feedback trigger objects, and (DIDFT_FFEFFECTTRIGGER | DIDFT_TGLBUTTON | DIDFT_PSHBUTTON) restricts enumeration to buttons of any kind that can be used as effect triggers.

Applications should not rely on this method to determine whether certain keyboard keys or indicator lights are present, as these objects might be enumerated even though they are not present. Although the basic set of available objects can be determined from the device subtype, there is no reliable way of determining whether extra objects such as the menu key are available.

Requirements

Header: Declared in dinput.h.

Share via