Obtaining Preparsed Data
This section describes how user-mode applications and kernel-mode drivers obtain a HID collection's preparsed data, which is an opaque structure that describes a collection's HID reports.
A user-mode application must obtain a collection's preparsed data before calling any of the HIDClass support routines that require the preparsed data. An application should retain access to a collection's preparsed data as long as it has an open file on the device.
After opening a file on a HID collection, an application calls HidD_GetPreparsedData to return a collection's preparsed data in a routine-allocated buffer.
Applications should call HidD_FreePreparsedData when the application no longer requires access to a collection.
After a kernel-mode driver opens a HID collection, the driver obtains a collection's preparsed data in the following way:
Obtains the length of the collection's preparsed data
Obtains the collection's preparsed data
To determine the length of the preparsed data, the driver uses an IOCTL_HID_GET_COLLECTION_INFORMATION request. This request returns a HID_COLLECTION_INFORMATION structure. The DescriptorSize member of this structure specifies the size, in bytes, of a collection's preparsed data. The driver must allocate a buffer from nonpaged pool of at least this size to hold the preparsed data.
After allocating the buffer for the preparsed data, the driver uses an IOCTL_HID_GET_COLLECTION_DESCRIPTOR request to obtain the preparsed data.
After obtaining the preparsed data, the driver can use it with the HidP_Xxx HID support routines to obtain information about the capabilities of the HID collection and to extract control data from HID reports.