IDirectInputDevice7::GetProperty

The IDirectInputDevice7::GetProperty method retrieves information about the input device.

HRESULT GetProperty(
  REFGUID rguidProp,    
  LPDIPROPHEADER pdiph  
);

Parameters

rguidProp

Identifier of 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_AUTOCENTER

Specifies whether device objects are self-centering. See IDirectInputDevice7::SetProperty for more information.

DIPROP_AXISMODE

Retrieves the axis mode. The retrieved value (DIPROPAXISMODE_ABS or DIPROPAXISMODE_REL) is set in the dwData member of the associated DIPROPDWORD structure. See the description for the pdiph parameter for more information.

DIPROP_BUFFERSIZE

Retrieves the input-buffer size. The retrieved value is set in the dwData member of the associated DIPROPDWORD structure. See the description for the pdiph parameter for more information.

The buffer size determines the amount of data that the buffer can hold between calls to the IDirectInputDevice7::GetDeviceData method before data is lost. This value can be set to 0 to indicate that the application does not be reading buffered data from the device. If the buffer size in the dwData member of the DIPROPDWORD structure is too large to be supported by the device, the largest possible buffer size is set. To determine whether the requested buffer size was set, retrieve the buffer-size property, and compare the result with the value that you previously attempted to set.

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 IDirectInputDevice7::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 dwData member contains a value in the range from 0 through 100, indicating the percentage of device memory in use.

DIPROP_GRANULARITY

Retrieves the input granularity. The retrieved value is set in the dwData member of the associated DIPROPDWORD structure. See the description of the pdiph parameter for more information.

Granularity represents the smallest distance over which the object reports movement. Most axis objects have a granularity of one, meaning that all values are possible. Some axes have a larger granularity. For example, the wheel axis on a mouse can have a granularity of 20, meaning that 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; you cannot set its value by calling the IDirectInputDevice7::SetProperty method.

DIPROP_GUIDANDPATH

Allows the application to access 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 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 IDirectInputDevice7::SetProperty.

DIPROP_PRODUCTNAME

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

DIPROP_RANGE

Retrieves the range of values an object can possibly report. The retrieved minimum and maximum values are set in the lMin and lMax members of the associated DIPROPRANGE structure. See the description of the pdiph parameter for more information.

For some devices, this is a read-only property; you cannot set its value by calling the IDirectInputDevice7::SetProperty method.

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).

pdiph

Address of the DIPROPHEADER portion of a larger property-dependent structure that contains the DIPROPHEADER structure as a member. When retrieving object range information, this value is the address of the DIPROPHEADER structure contained within the DIPROPRANGE structure. For most other properties, this value is the address of the DIPROPHEADER structure contained within the DIPROPDWORD structure.

Return Values

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:

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

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.
  Import Library: Use dinput.lib.

See Also

IDirectInputDevice7::SetProperty