DIDEVICEOBJECTINSTANCE

The DIDEVICEOBJECTINSTANCE structure contains information about a device object instance. This structure is used with the IDirectInputDevice7::EnumObjects method to provide the DIEnumDeviceObjectsCallback callback function with information about a particular object associated with a device, such as an axis or button. It is also used with the IDirectInputDevice7::GetObjectInfo method to retrieve information about a device object.

typedef struct DIDEVICEOBJECTINSTANCE { 
    DWORD dwSize; 
    GUID  guidType; 
    DWORD dwOfs; 
    DWORD dwType; 
    DWORD dwFlags; 
    TCHAR tszName[MAX_PATH]; 
    DWORD dwFFMaxForce; 
    DWORD dwFFForceResolution; 
    WORD  wCollectionNumber;
    WORD  wDesignatorIndex;
    WORD  wUsagePage;
    WORD  wUsage;
    DWORD dwDimension;
    WORD  wExponent;
    WORD  wReportId;
} DIDEVICEOBJECTINSTANCE, *LPDIDEVICEOBJECTINSTANCE; 
 
typedef const DIDEVICEOBJECTINSTANCE *LPCDIDEVICEOBJECTINSTANCE;

Members

dwSize

Size of the structure, in bytes. During enumeration, the application can inspect this value to determine how many members of the structure are valid. When the structure is passed to the IDirectInputDevice7::GetObjectInfo method, this member must be initialized to sizeof(DIDEVICEOBJECTINSTANCE).

guidType

Unique identifier that indicates the object type. This member is optional. If present, it can be one of the following values:

GUID_XAxis

The horizontal axis. For example, it can represent the left-right motion of a mouse.

GUID_YAxis

The vertical axis. For example, it can represent the forward-backward motion of a mouse.

GUID_ZAxis

The z-axis. For example, it can represent rotation of the wheel on a mouse, or movement of a throttle control on a joystick.

GUID_RxAxis

Rotation around the x-axis.

GUID_RyAxis

Rotation around the y-axis.

GUID_RzAxis

Rotation around the z-axis (often a rudder control).

GUID_Slider

A slider axis.

GUID_Button

A button on a mouse.

GUID_Key

A key on a keyboard.

GUID_POV

A point-of-view indicator.

GUID_Unknown

Unknown.

Other object types might be defined in the future.

dwOfs

Offset within the data format at which data is reported for this object. This value can be used to identify the object in method calls and structures that accept the DIPH_BYOFFSET flag.

dwType

Device type that describes the object. It is a combination of DIDFT_* flags that describe the object type (axis, button, and so on) and contains the object instance number in the middle 16 bits. Use the DIDFT_GETINSTANCE macro to extract the object instance number. For the DIDFT_* flags, see IDirectInputDevice7::EnumObjects.

dwFlags

Flags describing other attributes of the data format. This value can be one of the following:

DIDOI_ASPECTACCEL

The object reports acceleration information.

DIDOI_ASPECTFORCE

The object reports force information.

DIDOI_ASPECTMASK

The bits that are used to report aspect information. An object can represent at most one aspect.

DIDOI_ASPECTPOSITION

The object reports position information.

DIDOI_ASPECTVELOCITY

The object reports velocity information.

DIDOI_FFACTUATOR

The object can have force-feedback effects applied to it.

DIDOI_FFEFFECTTRIGGER

The object can trigger playback of force-feedback effects.

DIDOI_GUIDISUSAGE

The pguid member of the DIOBJECTDATAFORMAT structure is really a (suitably cast) DIMAKEUSAGEDWORD of the usage page and usage that is desired.

DIDOI_POLLED

The object does not return data until the IDirectInputDevice7::Poll method is called.

tszName[MAX_PATH]

Name of the object; for example, "X-Axis" or "Right Shift."

dwFFMaxForce

The magnitude of the maximum force that can be created by the actuator associated with this object. Force is expressed in newtons and measured in relation to where the hand would be during normal operation of the device.

dwFFForceResolution

The force resolution of the actuator associated with this object. The returned value represents the number of gradations, or subdivisions, of the maximum force that can be expressed by the force-feedback system from 0 (no force) to maximum force.

wCollectionNumber

The HID link collection to which the object belongs.

wDesignatorIndex

An index that refers to a designator in the HID physical descriptor. This number can be passed to functions in the HID parsing library (Hidpi.h) to obtain additional information about the device object.

wUsagePage

The HID usage page associated with the object, if known. Human Interface Devices always report a usage page. Non-HID devices can optionally report a usage page; if they do not, the value of this member is 0.

wUsage

The HID usage associated with the object, if known. Human Interface Devices always report a usage. Non-HID devices can optionally report a usage; if they do not, the value of this member is 0.

dwDimension

An HID code for the dimensional units in which the object's value is reported, if known, or 0 if not known.

wExponent

The exponent to associate with the dimension, if known. Dimensional units are always integral, so an exponent might be needed to convert them to nonintegral types.

wReportId

Reserved.

Remarks

Applications can use the wUsagePage and wUsage members to obtain additional information about how the object was designed to be used. For example, if wUsagePage has the value 0x02 (vehicle controls) and wUsage has the value 0xB9 (elevator trim), the object was designed to be the elevator trim control on a flightstick. A flight simulator application can use this information to provide more reasonable defaults for objects on the device. HID usage codes are determined by the USB standards committee.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dinput.h.