The IOCTL_HID_GET_STRING request obtains a manufacturer ID, product ID, or serial number for a top-level collection. The retrieved string is a NULL-terminated wide character string in a human-readable format.
For general information about HIDClass devices, see HID Collections.
IOCTL_HID_GET_STRING makes use of two input buffers.
Parameters.DeviceIoControl.OutputBufferLength in the I/O stack location of the IRP indicates the size, in bytes, of the locked-down output buffer at Irp->UserBuffer. If the output buffer is not large enough to hold the entire NULL-terminated embedded string, the request returns nothing in the output buffer. The maximum possible number of characters in an embedded string is device specific. For USB devices, the maximum string length is 126 wide characters (not including the terminating NULL character).
Parameters.DeviceIoControl.Type3InputBuffer in the I/O stack location of the IRP contains a composite value. The two most significant bytes contain the language ID of the string to be retrieved. The two least significant bytes contain one of the following three constant values:
It is important not to confuse these three constants with the actual string indices of the IDs. These constants represent the offsets in the device descriptor where the corresponding string indices can be found.
For example, HID_STRING_ID_IMANUFACTURER indicates the location in the device descriptor where the index for the manufacturer ID is found. This index, in turn, serves as an offset into the string descriptor where the human-readable form of the manufacturer ID is located.
Input Buffer Length
The size of the OutputBufferLength and the size of the Type3InputBuffer.
The HID minidriver fills the buffer at Irp->UserBuffer with the requested string (a NULL-terminated wide character string).
Output Buffer Length
The size of the UserBuffer.
HID minidrivers that carry out the I/O to the device set the following fields of Irp->IoStatus:
- Information is set to the number of bytes transferred from the device.
- Status is set to STATUS_SUCCESS if the transfer completed without error. Otherwise, it is set to an appropriate NTSTATUS error code.
|Header||hidport.h (include Hidport.h)|