HidD_GetSerialNumberString function (hidsdi.h)

Article
02/22/2024

The HidD_GetSerialNumberString routine returns the embedded string of a top-level collection that identifies the serial number of the collection's physical device.

Syntax

BOOLEAN HidD_GetSerialNumberString(
  [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 serial number string. The routine returns a NULL-terminated wide character string.

[in] BufferLength

Specifies the length, in bytes, of a caller-allocated buffer provided at Buffer. If the buffer is not large enough to return the entire NULL-terminated embedded string, the routine returns nothing in the buffer. The supplied buffer must be <= 4093 bytes (2^12 – 3).

Return value

HidD_GetSerialNumberString returns TRUE if it successfully returns the entire NULL-terminated embedded string. Otherwise, the routine returns FALSE. Use GetLastError to get extended error information.

Remarks

Only user-mode applications can call HidD_GetSerialNumberString. Kernel-mode drivers can use IOCTL_HID_GET_SERIALNUMBER_STRING.

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

If the supplied buffer is not <= 4093 bytes (2^12 – 3), the call may fail (depending on the underlying protocol, HID/Bluetooth/SPI) with error code ERROR_GEN_FAILURE (0x0000001f)

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