HidD_GetPhysicalDescriptor function (hidsdi.h)

Article
02/22/2024

The HidD_GetPhysicalDescriptor routine returns the Physical Descriptor of a top-level collection that identifies the collection's physical device.

Physical Descriptor is used to indicate what physical part of the human body is used to activate the controls on a device. For example, a Physical Descriptor might indicate that the right hand thumb is used to activate button 5.

Note that Physical Descriptors are entirely optional. They add complexity and offer very little in return for most devices. However, some devices, particularly those with a large number of identical controls (for example, buttons) will find that Physical Descriptors help different applications assign functionality to these controls in a more consistent manner. See HID specification for more info.

Syntax

BOOLEAN HidD_GetPhysicalDescriptor(
  [in]  HANDLE HidDeviceObject,
  [out] PVOID  Buffer,
  [in]  ULONG  BufferLength
);

Parameters

[in] HidDeviceObject

Specifies an open handle to a top-level collection.

[out] Buffer

Pointer to a caller-allocated buffer that the routine uses to return the requested physical descriptor.

[in] BufferLength

Specifies the length, in bytes, of the buffer at Buffer.

Return value

HidD_GetPhysicalDescriptor returns TRUE if it succeeds; otherwise, it returns FALSE. Use GetLastError to get extended error information.

Remarks

Only user-mode applications can call HidD_GetPhysicalDescriptor. Kernel-mode drivers can use an IOCTL_GET_PHYSICAL_DESCRIPTOR request.

For more information, see HID Collections.

Requirements

Requirement	Value
Minimum supported client	Available in Windows 2000 and later versions of Windows.
Target Platform	Universal
Header	hidsdi.h (include Hidsdi.h)
Library	Hid.lib
DLL	Hid.dll