IDirectInputDevice8::GetProperty

Retrieves information about the input device.

HRESULT GetProperty(
  REFGUID rguidProp,    
  LPDIPROPHEADER pdiph  
);

Parameters

rguidProp

Reference to (C++) or address of (C) the GUID identifying the property to be retrieved. This can be one of the predefined values or a pointer to a GUID that identifies the property. The following properties are predefined for an input device:

DIPROP_APPDATA

Retrieves the application-defined value associated with an in-game action, as a DIPROPPOINTER.

DIPROP_AUTOCENTER

Determines whether device objects are self-centering. The value returned can be DIPROPAUTOCENTER_OFF or DIPROPAUTOCENTER_ON. See IDirectInputDevice8::SetProperty for more information.

DIPROP_AXISMODE

Retrieves the axis mode. The retrieved value can be DIPROPAXISMODE_ABS or DIPROPAXISMODE_REL.

DIPROP_BUFFERSIZE

Retrieves the input buffer size.

The buffer size determines the amount of data that the buffer can hold between calls to the IDirectInputDevice8::GetDeviceData method before data is lost. You can set this value to 0 to indicate that the application does not read buffered data from the device. If the buffer size in the dwData member of the DIPROPDWORD structure is too large for the device to support it, the largest possible buffer size is set. However, this property always return the buffer size set using the SetProperty method, even if the buffer cannot be supported because it is too large.

DIPROP_CALIBRATION

Predefined property that allows the application to access the information that DirectInput uses to manipulate axes that require calibration. This property exists primarily for control-panel-type applications. Normal applications should not need to deal with calibration information.

You can access the calibration mode property for a particular axis by setting the dwHow member of the DIPROPHEADER structure to DIPH_BYID or to DIPH_BYOFFSET and setting the dwObj member to the object ID or offset, respectively.

Control panel applications that set new calibration data must also invoke the IDirectInputJoyConfig::SendNotify method to notify other applications of the change in calibration. For more information about IDirectInputJoyConfig::SendNotify, see the DirectX Driver Development Kit (DDK).

DIPROP_CALIBRATIONMODE

For use by device drivers; not used by applications.

DIPROP_CPOINTS

Retrieves calibration points used for the adjustment of incoming raw data as a DIPROPCPOINTS structure.

DIPROP_DEADZONE

Retrieves a value for the dead zone of a joystick, in the range from 0 through 10,000, where 0 indicates that there is no dead zone, 5,000 indicates that the dead zone extends over 50 percent of the physical range of the axis on both sides of center, and 10,000 indicates that the entire physical range of the axis is dead. When the axis is within the dead zone, it is reported as being at the center of its range.

DIPROP_FFGAIN

Retrieves the gain of the device. See IDirectInputDevice8::SetProperty for more information.

DIPROP_FFLOAD

Retrieves the memory load for the device. This setting applies to the entire device, rather than to any particular object, so the dwHow member of the associated DIPROPDWORD structure must be DIPH_DEVICE. The retrieved value is in the range from 0 through 100, indicating the percentage of device memory in use. The device must be acquired in exclusive mode. If it is not, the method will fail with a return value of DIERR_NOTEXCLUSIVEACQUIRED.

DIPROP_GETPORTDISPLAYNAME

Retrieves the human-readable display name of the port to which this device is connected. Not generally used by applications. If no friendly name is returned, the method returns S_FALSE.

DIPROP_GRANULARITY

Retrieves the input granularity. Granularity represents the smallest distance over which the object reports movement. Most axis objects have a granularity of one; that is, all values are possible. Some axes have a larger granularity. For example, the wheel axis on a mouse can have a granularity of 20; that is, all reported changes in position are multiples of 20. In other words, when the user turns the wheel slowly, the device reports a position of 0, then 20, then 40, and so on. This is a read-only property.

DIPROP_GUIDANDPATH

Retrieves the class GUID and device interface (path) for the device. This property lets advanced applications perform operations on a HID that are not supported by Microsoft® DirectInput®. For more information, see the reference for the DIPROPGUIDANDPATH structure.

DIPROP_INSTANCENAME

Retrieves the friendly instance name of the device. For more information, see IDirectInputDevice8::SetProperty.

DIPROP_JOYSTICKID

Retrieves the instance number of a joystick. This property is not implemented for the mouse or keyboard.

DIPROP_KEYNAME

Retrieves the localized key name for a keyboard key, as a DIPROPSTRING.

DIPROP_LOGICALRANGE

Retrieves the range of the raw data returned for axes on a HID. Devices can return negative values.

DIPROP_PHYSICALRANGE

Retrieves the range of data for axes as suggested by the manufacturer of a HID. Values can be negative. Normally DirectInput® returns values from 0 through 0xFFFF, but the range can be made to conform to the manufacturer's suggested range by using DIPROP_RANGE.

DIPROP_PRODUCTNAME

Retrieves the friendly product name of the device. For more information, see IDirectInputDevice8::SetProperty.

DIPROP_RANGE

Retrieves the range of values an object can possibly report. For some devices, this is a read-only property.

DIPROP_SATURATION

Retrieves a value for the saturation zones of a joystick, in the range from 0 through 10,000. The saturation level is the point at which the axis is considered to be at its most extreme position. For example, if the saturation level is set to 9,500, the axis reaches the extreme of its range when it has moved 95 percent of the physical distance from its center position (or from the dead zone).

DIPROP_SCANCODE

Retrieves the scan code for a keyboard key, as a DIPROPDWORD.If successful, S_OK is returned. E_FAIL is returned if the property cannot resolve specialized keys on USB keyboards because they do not exist in scan code form. For all other failures, E_INVALIDARG is returned.

DIPROP_TYPENAME

Predefined property that retrieves the type name of a device. For most game controllers, this is the registry key name under REGSTR_PATH_JOYOEM from which static device settings can be retrieved, but predefined joystick types have special names consisting of a number sign (#) followed by a character dependent on the type. This value might not be available for all devices.

DIPROP_USERNAME

Retrieves the user name for a user currently assigned to a device, as a DIPROPSTRING. User names are set by calling IDirectInputDevice8::SetActionMap. If no user name is set, the method returns S_FALSE.

DIPROP_VIDPID

Read-only device property that retrieves the vendor identity (ID) and product ID of a HID device. This property is of type DIPROPDWORD and contains both values. These two WORD values are combined in the dwData member of the DIPROPDWORD structure so the values should be extracted as follows:

        wVendorID  = LOWORD(DIPROPDWORD.dwData);
        wProductID = HIWORD(DIPROPDWORD.dwData);

This property applies to the entire device, rather than to any particular object, so the dwHow member of the DIPROPHEADER structure must be set to DIPH_DEVICE.

pdiph

Address of the DIPROPHEADER portion of a larger property-dependent structure that contains the DIPROPHEADER structure as a member. The following structures are used for properties:

DIPROPDWORD

Used for properties represented by a single numerical value.

DIPROPGUIDANDPATH

Used for DIPROP_GUIDANDPATH.

DIPROPRANGE

Used for properties represented by a pair of numerical values. Currently, the only such property is DIPROP_RANGE.

DIPROPSTRING

Used for string properties.

Return Values

If the method succeeds, the return value is DI_OK or S_FALSE.

If the method fails, the return value can be one of the following error values:

Remarks

The following C example shows how to obtain the value of the DIPROP_BUFFERSIZE property:

DIPROPDWORD dipdw;  // DIPROPDWORD contains a DIPROPHEADER structure. 
HRESULT hr; 
dipdw.diph.dwSize       = sizeof(DIPROPDWORD); 
dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER); 
dipdw.diph.dwObj        = 0; // device property 
dipdw.diph.dwHow        = DIPH_DEVICE; 
 
hr = IDirectInputDevice8_GetProperty(pdid, DIPROP_BUFFERSIZE, &dipdw.diph); 
if (SUCCEEDED(hr)) { 
    // The dipdw.dwData member contains the buffer size. 
} 

Requirements

  Windows NT/2000/XP: Requires Windows® 2000.
  Windows 98/Me: Requires Windows 98 or later. Available as a redistributable for Windows 98.
  Header: Declared in Dinput.h.

See Also

IDirectInputDevice8::SetProperty