IDirectInputDevice8::GetProperty Method

Article
09/10/2011

Retrieves information about the input device.

Syntax

HRESULT GetProperty(
         REFGUID rguidProp,
         LPDIPROPHEADER pdiph
)

Parameters

rguidProp
Reference to (C++) or address of (C) the globally unique identifier (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, then the largest possible buffer size is set. However, this property always returns the buffer size set using the IDirectInputDevice8::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 applications of the control panel type. 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 DirectInput Driver Development Kit (DDK).
- DIPROP_CALIBRATIONMODE
  For use by device drivers; not used by applications.
- DIPROP_CPOINTS
  This property is unsupported. 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. This property always returns DI_OK even if the device does not support force feedback. 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.
- 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 human interface device that are not supported by DirectInput. For more information, see 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. Using this property on devices other than a keyboard will return unexpected names.
- DIPROP_LOGICALRANGE
  Retrieves the range of the raw data returned for axes on a human interface device. Devices can return negative values.
- DIPROP_PHYSICALRANGE
  Retrieves the range of data for axes as suggested by the manufacturer of a human interface device. 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 (&Sharp;) 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. See Examples. 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 is used for properties represented by a single numerical value.
- DIPROPGUIDANDPATH is used for DIPROP_GUIDANDPATH.
- DIPROPRANGE is used for properties represented by a pair of numerical values. Currently, the only such property is DIPROP_RANGE.
- DIPROPSTRING is used for string properties.

Return Value

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: DIERR_INVALIDPARAM, DIERR_NOTEXCLUSIVEACQUIRED, DIERR_NOTINITIALIZED, DIERR_OBJECTNOTFOUND, DIERR_UNSUPPORTED.

Remarks

If rguidProp is set to DIPROP_APPDATA, the dwHow member of the DIPROPHEADER structure should only be set to DIPH_BYUSAGE when getting information about input controls, such as buttons or axes. Setting DIPH_BYUSAGE for other device objects such as a physical interface device (PID) or LED devices can lead to unpredictable results.

S_FALSE is always returned when IDirectInputDevice8::GetProperty is called with rguidProp set to DIPROP_GETPORTDISPLAYNAME, even if the method succeeds.

The scan codes reported in Microsoft DirectX 8.1 are different from the ones reported in DirectX 8.0. In DirectX 8.0, the property actually reported the single byte DIK_* constant associated with the key, not the scan code. In DirectX 8.1 and later releases, the property reports the make scan code as would be reported by a PS/2 keyboard. In some cases, scan codes are multiple bytes, in which case the scan code bytes are ordered with the first byte in the least significant byte of the DWORD retrieved by the property.

Example

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 = idirectinputdevice9_GetProperty(pdid, DIPROP_BUFFERSIZE, &dipdw.diph); 
if (SUCCEEDED(hr)) { 
    // The dipdw.dwData member contains the buffer size. 
}

The following example shows how to extract the two WORD values from the dwData member of the DIPROPDWORD structure using the DIPROP_VIDPID property:

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

Requirements

Header: Declared in dinput.h.

Share via