Modules
	HID Device Status Codes

	Max number of reports that can be requested at time

	String Lengths in ASCII character lengths not including NULL-terminator

Macros
#define	SLAB_HID_DEVICE_API
	SLAB_HID_DEVICE_API definition. More...

#define	WINAPI
	WINAPI definition. More...

#define	USE_LEGACY_SLAB_HID_DEVICE_STATUS
	API Status return codes. More...

#define	MAX_USB_DEVICES 64
	Max number of USB Devices allowed. More...

#define	HID_VID_STRING 0x01
	String Types // TODO: Enstone: These defines are a exact duplicate values of HID_DEVICE_STRING_ID enums in HIDDevice.h. More...

#define	HID_PID_STRING 0x02
	PID string, derived from HID_PATH_STRING. More...

#define	HID_PATH_STRING 0x03
	Full Path string. More...

#define	HID_SERIAL_STRING 0x04
	iSerial Number string retrieved from device More...

#define	HID_MANUFACTURER_STRING 0x05
	Manufacturer Description string retrieved from device. More...

#define	HID_PRODUCT_STRING 0x06
	Product Description string retrieved from device. More...

Typedefs
typedef void *	HID_DEVICE
	an opaque handle object More...

Functions
DWORD	HidDevice_GetNumHidDevices (const WORD Vid, const WORD Pid)
	Determines the number of devices connected to the system with matching VID/PID. More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetHidString (const DWORD dwDeviceIndex, const WORD Vid, const WORD Pid, const BYTE WhichHidStringToReturn, char *deviceString, const DWORD deviceStringLengthInBytes)
	Gets a "Product string". More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetHidIndexedString (const DWORD dwDeviceIndex, const WORD Vid, const WORD Pid, const DWORD stringIndex, char *deviceString, const DWORD deviceStringLengthInBytes)
	Gets an indexed string from the device. More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetHidAttributes (const DWORD dwDeviceIndex, const WORD Vid, const WORD Pid, WORD pDeviceVid, WORD pDevicePid, WORD *pDeviceReleaseNumber)
	Reads and returns the Vendor ID, Product ID and device Release Number. More...

void	HidDevice_GetHidGuid (void *pHIDGuid)
	Return the GUID for HIDClass devices ("return the HID GUID") More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetHidLibraryVersion (BYTE pMajor, BYTE pMinor, BOOL *pbIsReleaseBuild)
	tbd More...

SLAB_HID_DEVICE_STATUS	HidDevice_Open (HID_DEVICE *device, const DWORD dwDeviceIndex, const WORD Vid, const WORD Pid, const DWORD numInputBuffers)
	tbd More...

BOOL	HidDevice_IsOpened (const HID_DEVICE device)
	This function returns the device opened state. More...

HANDLE	HidDevice_GetHandle (const HID_DEVICE device)
	This function returns the HID handle for the currently-opened device. More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetString (const HID_DEVICE device, const BYTE WhichHidStringToReturn, char *deviceString, const DWORD deviceStringLengthInBytes)
	Gets a "Product string". More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetIndexedString (const HID_DEVICE device, const DWORD stringIndex, char *deviceString, const DWORD deviceStringLengthInBytes)
	Gets an indexed string from the device. More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetAttributes (const HID_DEVICE device, WORD pDeviceVid, WORD pDevicePid, WORD *pDeviceReleaseNumber)
	Reads and returns the Vendor ID, Product ID and device Release Number. More...

SLAB_HID_DEVICE_STATUS	HidDevice_SetFeatureReport_Control (const HID_DEVICE device, BYTE *ReportBuffer, const DWORD ReportBufferLengthInBytes)
	This function sends an HID feature report from the host to the device over the control endpoint. More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetFeatureReport_Control (const HID_DEVICE device, BYTE *ReportBuffer, const DWORD ReportBufferLengthInBytes)
	This function receives an HID feature report from the host to the device over the control endpoint. More...

SLAB_HID_DEVICE_STATUS	HidDevice_SetOutputReport_Interrupt (const HID_DEVICE device, BYTE *ReportBuffer, const DWORD ReportBufferLengthInBytes)
	This function sends an HID output report from the host to the device over the interrupt endpoint. More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetInputReport_Interrupt (const HID_DEVICE device, BYTE ReportBuffer, const DWORD ReportBufferLengthInBytes, const DWORD numReports, DWORD bytesReturned)
	This function receives an HID input report from the host to the device over the interrupt endpoint. More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetInputReport_Interrupt_WithTimeout (const HID_DEVICE device, BYTE ReportBuffer, const DWORD ReportBufferLengthInBytes, const DWORD numReports, DWORD bytesReturned, const DWORD TimeoutMSec)
	This function receives an HID input report from the host to the device over the interrupt endpoint. More...

SLAB_HID_DEVICE_STATUS	HidDevice_SetOutputReport_Control (const HID_DEVICE device, BYTE *ReportBuffer, const DWORD ReportBufferLengthInBytes)
	Sends an HID output report from the host to the device over the control endpoint. More...

SLAB_HID_DEVICE_STATUS	HidDevice_GetInputReport_Control (const HID_DEVICE device, BYTE *ReportBuffer, const DWORD ReportBufferLengthInBytes)
	Receives an HID input report from the device to the host over the control endpoint. More...

WORD	HidDevice_GetInputReportBufferLength (const HID_DEVICE device)
	Returns the maximum input report size including the report ID. More...

WORD	HidDevice_GetOutputReportBufferLength (const HID_DEVICE device)
	Returns the maximum output report size including the report ID. More...

WORD	HidDevice_GetFeatureReportBufferLength (const HID_DEVICE device)
	Returns the maximum feature report size, including the report ID. More...

DWORD	HidDevice_GetMaxReportRequest (const HID_DEVICE device)
	Returns the maximum number of input reports that can be queued in the HID driver. More...

BOOL	HidDevice_FlushBuffers (const HID_DEVICE device)
	Deletes all pending input reports in the HID driver queue and the HID library. More...

BOOL	HidDevice_CancelIo (const HID_DEVICE device)
	Cancels all pending input and output operations issued by the calling thread. More...

void	HidDevice_GetTimeouts (const HID_DEVICE device, DWORD pGetReportTimeoutInMilliSeconds, DWORD pSetReportTimeoutInMilliSeconds)
	Returns the input and output report timeouts over the interrupt endpoint. More...

void	HidDevice_SetTimeouts (const HID_DEVICE device, const DWORD getReportTimeoutInMilliSeconds, const DWORD setReportTimeoutInMilliSeconds)
	Sets the input and output report timeouts over the interrupt endpoint. More...

SLAB_HID_DEVICE_STATUS	HidDevice_Close (const HID_DEVICE device)
	Closes an open handle to the device. More...

Detailed Description

The Silicon Labs CP211x USB-to-HID bridges are devices that communicate over the Universal Serial Bus (USB) to perform Universal Asynchronous Receiver / Transmitter (UART) data transfers. These devices have many programmable options that can be configured via USB. These devices also often include flexible GPIO functions that can be configured and accessed via USB during runtime. Silicon Labs provides libraries that can be used to configure these devices and access their GPIOs.

Two interface library files can be used to interface with CP211x devices, CP210xManufacturing.DLL and .LIB, which is responsible for reading and writing the device settings, and CP210xRuntime.DLL and .LIB, which is responsible for interfacing with the device's GPIOs. The APIs for CP210xManufacturing are described below.

This document supercedes, obsoletes and takes precedences over AN532.

The CP211x SLABHIDDevice Host API is provided as a means to facilitate production of customized CP211x devices. This API allows access to the CP211x device for retrieving and setting the VID, PID, product string, serial number, self - power attribute, maximum power consumption, and device version.

The CP211x SLABHIDDevice Host API is provided in the form of a Windows Dynamic Link Library (DLL), SLABHIDDevice.DLL and as a Windows static link library (SLABHIDDevice.static.LIB). The host interface library communicates with the bridge controller device via the provided device driver and the operating system's USB stack.

Custom applications can use the CP211x SLABHIDDevice API implemented in SLABHIDDevice.DLL. To use functions implemented in SLABHIDDevice.DLL link SLABHIDDevice.LIB include SLABHIDDevice.h into any source code files that call any functions implemented in SLABHIDDevice.DLL and include the PATH to the location of SLABHIDDevice.DLL in your custom application Visual Studio .VCXPROJ Profile File's Properties->Linker->General->Additional Library Directories property.

Typically, the user initiates communication with the target CP211x device by making a call to HidDevice_GetNumHidDevices(). This call returns the number of CP211x target devices. This number is used as a range when calling HidDevice_GetHidString() to build a list of devices connected to the host machine. A handle to the device must first be opened by a call to HidDevice_Open() using an index determined from the call to HidDevice_GetNumHidDevices(). The handle will be used for all subsequent accesses. When I/O operations are complete, the device handle is closed by a call to HidDevice_Close().

Macro Definition Documentation

◆ HID_MANUFACTURER_STRING

#define HID_MANUFACTURER_STRING 0x05

Manufacturer Description string retrieved from device.

◆ HID_PATH_STRING

#define HID_PATH_STRING 0x03

Full Path string.

◆ HID_PID_STRING

#define HID_PID_STRING 0x02

PID string, derived from HID_PATH_STRING.

◆ HID_PRODUCT_STRING

#define HID_PRODUCT_STRING 0x06

Product Description string retrieved from device.

◆ HID_SERIAL_STRING

#define HID_SERIAL_STRING 0x04

iSerial Number string retrieved from device

◆ HID_VID_STRING

#define HID_VID_STRING 0x01

String Types // TODO: Enstone: These defines are a exact duplicate values of HID_DEVICE_STRING_ID enums in HIDDevice.h.

VID string, derived from HID_PATH_STRING

◆ MAX_USB_DEVICES

#define MAX_USB_DEVICES 64

Max number of USB Devices allowed.

◆ SLAB_HID_DEVICE_API

#define SLAB_HID_DEVICE_API

SLAB_HID_DEVICE_API definition.

◆ USE_LEGACY_SLAB_HID_DEVICE_STATUS

#define USE_LEGACY_SLAB_HID_DEVICE_STATUS

API Status return codes.

◆ WINAPI

#define WINAPI

WINAPI definition.

Typedef Documentation

◆ HID_DEVICE

typedef void* HID_DEVICE

an opaque handle object

Function Documentation

◆ HidDevice_CancelIo()

BOOL HidDevice_CancelIo ( const HID_DEVICE device )

Cancels all pending input and output operations issued by the calling thread.

Parameters

[in] device is an open handle to the device as returned by HidDevice_Open()

Returns: Returns TRUE if the function completed successfully. Returns FALSE if the function failed or if the device does not exist.

Return values

TRUE	– success
FALSE	– the function failed or the device does not exist.

◆ HidDevice_Close()

SLAB_HID_DEVICE_STATUS HidDevice_Close ( const HID_DEVICE device )

Closes an open handle to the device.

This function deletes the internal library input report buffer and cancels any pending input report reads via::CancelIo(). This function is responsible for deallocating the HID class object allocated in HidDevice_Open().

Parameters

[in] device is an open handle to the device as returned by HidDevice_Open()

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_HANDLE_ERROR	– failed, the device specified by device does not have a valid handle
HID_DEVICE_NOT_FOUND	– failed, the device specified by device was not found
HID_DEVICE_NOT_OPENED	– failed, the device specified by device is not open

◆ HidDevice_FlushBuffers()

BOOL HidDevice_FlushBuffers ( const HID_DEVICE device )

Deletes all pending input reports in the HID driver queue and the HID library.

This function first cancels pending overlapped input report reads (CancelIo()). Next, it flushes the HID driver input report queue. Finally, it flushes the library's internal input report queue.

Parameters

[in] device is an open handle to the device as returned by HidDevice_Open()

Returns: Returns TRUE if the function completed successfully. Returns FALSE if the function failed or if the device does not exist.

Return values

TRUE	– success
FALSE	– the function failed or the device does not exist.

◆ HidDevice_GetAttributes()

SLAB_HID_DEVICE_STATUS HidDevice_GetAttributes	(	const HID_DEVICE	device,
		WORD *	pDeviceVid,
		WORD *	pDevicePid,
		WORD *	pDeviceReleaseNumber
	)

Reads and returns the Vendor ID, Product ID and device Release Number.

This function returns the USB vendor ID, product ID, and device release number for the device specified by device.

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[out]	pDeviceVid	points at a 2-byte buffer into which the USB device vendor ID value will be written
[out]	pDevicePid	points at a 2-byte buffer into which the USB device product ID value will be written
[out]	pDeviceReleaseNumber	points at a 2-byte buffer into which the USB device bcdVersion, or device release number, value will be written

Note: A successfully returned pDeviceReleaseNumber is in binary-coded decimal (BCD).; Once a device is opened dwDeviceIndex is no longer valid, and HidDevice_GetAttributes() must be used rather than HidDevice_GetHidAttributes()

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_PARAMETER	– pDeviceVid, pDevicePid and/or pDeviceReleaseNumber is an unexpected value
HID_DEVICE_SYSTEM_CODE	– failed, system error see Windows' GetLastError()

◆ HidDevice_GetFeatureReport_Control()

SLAB_HID_DEVICE_STATUS HidDevice_GetFeatureReport_Control	(	const HID_DEVICE	device,
		BYTE *	ReportBuffer,
		const DWORD	ReportBufferLengthInBytes
	)

This function receives an HID feature report from the host to the device over the control endpoint.

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	ReportBuffer	- The buffer into which the feature report should be placed. The first byte of the buffer should be set to the report ID of the desired report.
[in]	ReportBufferLengthInBytes	- The size of ReportBuffer in bytes

The user must call this function with the first byte in ReportBuffer set to the report ID of the report to receive. ReportBuffer must be large enough to hold the feature report including report ID and, in most cases, should be allocated with a size equal to HidDevice_GetFeatureReportBufferLength().

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_BUFFER_SIZE	– ReportBuffer and/or ReportBufferLengthInBytes is an unexpected value
HID_DEVICE_NOT_OPENED	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_TRANSFER_FAILED	– failed, interaction with the device failed

◆ HidDevice_GetFeatureReportBufferLength()

WORD HidDevice_GetFeatureReportBufferLength ( const HID_DEVICE device )

Returns the maximum feature report size, including the report ID.

This function should be called to determine the appropriate buffer size for HidDevice_GetFeatureReport_Control().

Parameters

[in] device is an open handle to the device as returned by HidDevice_Open()

Returns: A return value of zero indicates that the specified device cannot be found. A non-zero value specifies the maximum feature report size, including the report ID.

◆ HidDevice_GetHandle()

HANDLE HidDevice_GetHandle ( const HID_DEVICE device )

This function returns the HID handle for the currently-opened device.

Parameters

[in] device is an open handle to the device as returned by HidDevice_Open()

Returns: Returns a Windows HANDLE created by Windows CreateFile() in HidDevice_Open(). Returns INVALID_HANDLE_VALUE if a device is not open or if there was an error opening a device.

◆ HidDevice_GetHidAttributes()

SLAB_HID_DEVICE_STATUS HidDevice_GetHidAttributes	(	const DWORD	dwDeviceIndex,
		const WORD	Vid,
		const WORD	Pid,
		WORD *	pDeviceVid,
		WORD *	pDevicePid,
		WORD *	pDeviceReleaseNumber
	)

Reads and returns the Vendor ID, Product ID and device Release Number.

This function returns the USB vendor ID, product ID, and device release number for the device specified by dwDeviceIndex.

Parameters

[in]	dwDeviceIndex	is the desired device's index into the device list used to determine HidDevice_GetNumHidDevices()
[in]	Vid	- Filter device results by the 2-byte Vendor ID value.
[in]	Pid	- Filter device results by the 2-byte Product ID value.
[out]	pDeviceVid	points at a 2-byte buffer into which the USB device vendor ID value will be written
[out]	pDevicePid	points at a 2-byte buffer into which the USB device product ID value will be written
[out]	pDeviceReleaseNumber	points at a 2-byte buffer into which the USB device bcdVersion, or device release number, value will be written

Note: If both Vid and Pid are zero (0x0000), devices will NOT be filtered by Vid/Pid.; A successfully returned pDeviceReleaseNumber is in binary-coded decimal (BCD).

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_PARAMETER	– pDeviceVid, pDevicePid and/or pDeviceReleaseNumber is an unexpected value
HID_DEVICE_NOT_FOUND	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_ALREADY_OPENED	– failed to open the device, it is already exclusively open elsewhere
HID_DEVICE_SYSTEM_CODE	– failed, see Windows GetLastError()

◆ HidDevice_GetHidGuid()

void HidDevice_GetHidGuid ( void * pHIDGuid )

Return the GUID for HIDClass devices ("return the HID GUID")

Parameters

[out] pHIDGuid points at a caller-allocated GUID buffer into which the HID GUID value will be written

◆ HidDevice_GetHidIndexedString()

SLAB_HID_DEVICE_STATUS HidDevice_GetHidIndexedString	(	const DWORD	dwDeviceIndex,
		const WORD	Vid,
		const WORD	Pid,
		const DWORD	stringIndex,
		char *	deviceString,
		const DWORD	deviceStringLengthInBytes
	)

Gets an indexed string from the device.

Returned strings are UCS-1?/ASCII and NULL-terminated. (verified)

Parameters

[in]	dwDeviceIndex	is the desired device's index into the device list used to determine HidDevice_GetNumHidDevices()
[in]	Vid	- Filter device results by the 2-byte Vendor ID value.
[in]	Pid	- Filter device results by the 2-byte Product ID value.
[in]	stringIndex	is the one-based index of which USB String Descriptor string to return.
[out]	deviceString	points at a buffer into which the string will be copied and returned
[in]	deviceStringLengthInBytes	is the size, in bytes/octets, of the buffer into which the the string will be copied and returned I.e. sizeof deviceString buffer

Note: If both Vid and Pid are zero (0x0000), devices will NOT be filtered by Vid/Pid.; String descriptors are referenced by their one-based index number. Specifically, a stringIndex of 0 successfully does NOT return the list of supported languages.; Once a device is opened dwDeviceIndex is no longer valid, and HidDevice_GetIndexedString() must be used rather than HidDevice_GetHidIndexedString()

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_NOT_FOUND	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_INVALID_BUFFER_SIZE	– failed, `deviceStringLengthInBytes` indicated a buffer that is too small
HID_DEVICE_ALREADY_OPENED	– failed to open the device, it is already exclusively open elsewhere
HID_DEVICE_SYSTEM_CODE	– failed, including when `stringIndex` is "too high" (I.e. there aren't this many strings on the device to index)

◆ HidDevice_GetHidLibraryVersion()

SLAB_HID_DEVICE_STATUS HidDevice_GetHidLibraryVersion	(	BYTE *	pMajor,
		BYTE *	pMinor,
		BOOL *	pbIsReleaseBuild
	)

tbd

Parameters

[out]	pMajor	points at a 1-byte buffer into which the library major version number value will be written
[out]	pMinor	points at a 1-byte buffer into which the library minor version number value will be written
[out]	pbIsReleaseBuild	points at a 4-byte buffer into which a non-zero/TRUE value will be written IFF the library was built as Release mode, else into which a zero/0 value will be written if the library was built as Debug mode.

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_BUFFER_SIZE	– pMajor, pMinor and/or pbIsReleaseBuild is an unexpected value

◆ HidDevice_GetHidString()

SLAB_HID_DEVICE_STATUS HidDevice_GetHidString	(	const DWORD	dwDeviceIndex,
		const WORD	Vid,
		const WORD	Pid,
		const BYTE	WhichHidStringToReturn,
		char *	deviceString,
		const DWORD	deviceStringLengthInBytes
	)

Gets a "Product string".

This function returns an ASCII NULL-terminated Vendor ID string, Product ID string, serial number string, manufacturer string, product description string, or full path string for the device specified by an index passed in the dwDeviceIndex parameter. The index of the first device is 0, and the index of the last device is the value(NumDevices) returned by HidDevice_GetNumHidDevices() - 1.

The Vendor ID string is derived from the "full path" string. deviceString must point to a buffer at least MAX_VID_LENGTH bytes long.

The Product ID string is derived from the "full path" string. deviceString must point to a buffer at least MAX_PID_LENGTH bytes long.

The full path string is the "device interface path" or "Device Path". This path can be passed to Win32 functions such as CreateFile(). deviceString must point to a buffer at least MAX_PATH_LENGTH bytes long.

The Serial Number string is the Serial Number string from the specified Hid device's USB Device Descriptor's iSerialNumber Serial Number String Descriptor. deviceString must point to a buffer at least MAX_SERIAL_STRING_LENGTH bytes long.

The Manufacturer Description string is the Manufacturer string from the specified Hid device's USB Device Descriptor's iManufacturer Manufacturer String Descriptor. deviceString must point to a buffer at least MAX_MANUFACTURER_STRING_LENGTH bytes long.

The Product string is the product string from the specified Hid device's USB Device Descriptor's iProduct Product String Descriptor. deviceString must point to a buffer at least MAX_PRODUCT_STRING_LENGTH bytes long.

Returned strings are UCS-1?/ASCII and NULL-terminated. (verified)

Parameters

[in]	dwDeviceIndex	is the desired device's index into the device list used to determine HidDevice_GetNumHidDevices()
[in]	Vid	- Filter device results by the 2-byte Vendor ID value.
[in]	Pid	- Filter device results by the 2-byte Product ID value.
[in]	WhichHidStringToReturn	is the indication of which string to return, one of HID_DEVICE_STRING_ID
[out]	deviceString	points at a buffer into which the string will be copied and returned
[in]	deviceStringLengthInBytes	is the size, in bytes/octets, of the buffer into which the the string will be copied and returned I.e. sizeof deviceString buffer

Note: If both Vid and Pid are zero (0x0000), devices will NOT be filtered by Vid/Pid.; Once a device is opened dwDeviceIndex is no longer valid, and HidDevice_GetString() must be used rather than HidDevice_GetHidString()

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_NOT_FOUND	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_INVALID_BUFFER_SIZE	– failed, `deviceStringLengthInBytes` indicated a buffer that is too small
HID_DEVICE_ALREADY_OPENED	– failed to open the device, it is already exclusively open elsewhere
HID_DEVICE_SYSTEM_CODE	– failed
HID_DEVICE_CANNOT_GET_HID_INFO	– failed

◆ HidDevice_GetIndexedString()

SLAB_HID_DEVICE_STATUS HidDevice_GetIndexedString	(	const HID_DEVICE	device,
		const DWORD	stringIndex,
		char *	deviceString,
		const DWORD	deviceStringLengthInBytes
	)

Gets an indexed string from the device.

Returned strings are UCS-1?/ASCII and NULL-terminated. (verified)

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	stringIndex	is the one-based index of which USB String Descriptor string to return.
[out]	deviceString	points at a buffer into which the string will be copied and returned
[in]	deviceStringLengthInBytes	is the size, in bytes/octets, of the buffer into which the the string will be copied and returned I.e. sizeof deviceString buffer

Note: String descriptors are referenced by their one-based index number. Specifically, a stringIndex of 0 successfully does NOT return the list of supported languages.; Once a device is opened dwDeviceIndex is no longer valid, and HidDevice_GetIndexedString() must be used rather than HidDevice_GetHidIndexedString()

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_BUFFER_SIZE	– failed, `deviceStringLengthInBytes` indicated a buffer that is too small
HID_DEVICE_SYSTEM_CODE	– failed, including when `stringIndex` is "too high" (I.e. there aren't this many strings on the device to index)

◆ HidDevice_GetInputReport_Control()

SLAB_HID_DEVICE_STATUS HidDevice_GetInputReport_Control	(	const HID_DEVICE	device,
		BYTE *	ReportBuffer,
		const DWORD	ReportBufferLengthInBytes
	)

Receives an HID input report from the device to the host over the control endpoint.

The user must call this function with the first byte in ReportBuffer set to the report ID of the report to receive. ReportBuffer must be large enough to hold the input report including report ID and, in most cases, should be allocated with a size equal to HidDevice_GetInputReportBufferLength().

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	ReportBuffer	- The buffer into which the tbd report should be placed. The first byte of the buffer should be set to the report ID of the desired report
[in]	ReportBufferLengthInBytes	- The size of ReportBuffer in bytes

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_BUFFER_SIZE	– ReportBuffer and/or ReportBufferLengthInBytes is an unexpected value
HID_DEVICE_NOT_OPENED	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_UNSUPPORTED_FUNCTION	– failed, this function is not supported on older Windows versions (Windows 2000)
HID_DEVICE_TRANSFER_FAILED	– failed, interaction with the device failed
HID_DEVICE_TRANSFER_TIMEOUT	– failed, interaction with the device timed out

◆ HidDevice_GetInputReport_Interrupt()

SLAB_HID_DEVICE_STATUS HidDevice_GetInputReport_Interrupt	(	const HID_DEVICE	device,
		BYTE *	ReportBuffer,
		const DWORD	ReportBufferLengthInBytes,
		const DWORD	numReports,
		DWORD *	bytesReturned
	)

This function receives an HID input report from the host to the device over the interrupt endpoint.

Each input report returned in buffer is stored on boundaries set by the maximum input report buffer size. For example, if the maximum input report buffer size as returned by HidDevice_GetInputReportBufferLength() is 64 and HidDevice_GetInputReport_Interrupt() returns 2 input reports, then bytesReturned will return with 128 bytes. The first input report starts at buffer[0], and the second input report starts at buffer[64] regardless of the actual size of the report. To retrieve the maximum number of input reports possible, call HidDevice_GetInputReport_Interrupt() with bufferSize set to(HidDevice_GetInputReportBufferLength() * HidDevice_GetMaxReportRequest()) and numReports set to HidDevice_GetMaxReportRequest().

To get input report interrupt with timeouts see HidDevice_GetInputReport_Interrupt_WithTimeout().

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	ReportBuffer	- The buffer into which the tbd report should be placed.The first byte of the buffer should be set to the report ID of the desired report
[in]	ReportBufferLengthInBytes	- The size of ReportBuffer in bytes
[in]	numReports	- The maximum number of input reports to return
[out]	bytesReturned	points at a 1-byte buffer into which the number of bytes returned in `ReportBuffer` will be written

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_BUFFER_SIZE	– ReportBuffer and/or ReportBufferLengthInBytes is an unexpected value
HID_DEVICE_NOT_OPENED	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_TRANSFER_FAILED	– failed, interaction with the device failed
HID_DEVICE_TRANSFER_TIMEOUT	– failed, interaction with the device timed out

◆ HidDevice_GetInputReport_Interrupt_WithTimeout()

SLAB_HID_DEVICE_STATUS HidDevice_GetInputReport_Interrupt_WithTimeout	(	const HID_DEVICE	device,
		BYTE *	ReportBuffer,
		const DWORD	ReportBufferLengthInBytes,
		const DWORD	numReports,
		DWORD *	bytesReturned,
		const DWORD	TimeoutMSec
	)

This function receives an HID input report from the host to the device over the interrupt endpoint.

Set input report interrupt timeouts by settings getReportTimeout in HidDevice_SetTimeouts().

Each input report returned in buffer is stored on boundaries set by the maximum input report buffer size. For example, if the maximum input report buffer size as returned by HidDevice_GetInputReportBufferLength() is 64 and HidDevice_GetInputReport_Interrupt() returns 2 input reports, then bytesReturned will return with 128 bytes. The first input report starts at buffer[0], and the second input report starts at buffer[64] regardless of the actual size of the report. To retrieve the maximum number of input reports possible, call HidDevice_GetInputReport_Interrupt() with bufferSize set to(HidDevice_GetInputReportBufferLength() * HidDevice_GetMaxReportRequest()) and numReports set to HidDevice_GetMaxReportRequest().

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	ReportBuffer	- The buffer into which the tbd report should be placed.The first byte of the buffer should be set to the report ID of the desired report
[in]	ReportBufferLengthInBytes	- The size of ReportBuffer in bytes
[in]	numReports	- The maximum number of input reports to return
[out]	bytesReturned	points at a 1-byte buffer into which the number of bytes returned in `ReportBuffer` will be written
[in]	TimeoutMSec	is the timeout in Milliseconds

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_BUFFER_SIZE	– ReportBuffer and/or ReportBufferLengthInBytes is an unexpected value
HID_DEVICE_NOT_OPENED	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_TRANSFER_FAILED	– failed, interaction with the device failed
HID_DEVICE_TRANSFER_TIMEOUT	– failed, interaction with the device timed out

◆ HidDevice_GetInputReportBufferLength()

WORD HidDevice_GetInputReportBufferLength ( const HID_DEVICE device )

Returns the maximum input report size including the report ID.

Parameters

[in] device is an open handle to the device as returned by HidDevice_Open()

Returns: A return value of zero indicates that the specified device cannot be found. A non-zero value specifies the maximum input report size including the report ID. This function should be called to determine the appropriate buffer size for HidDevice_GetInputReport_Interrupt() and HidDevice_GetInputReport_Control().

◆ HidDevice_GetMaxReportRequest()

DWORD HidDevice_GetMaxReportRequest ( const HID_DEVICE device )

Returns the maximum number of input reports that can be queued in the HID driver.

This function should be called to determine the appropriate buffer size for HidDevice_GetInputReport_Interrupt().

Parameters

[in] device is an open handle to the device as returned by HidDevice_Open()

Returns: A return value of zero indicates that the specified device cannot be found. A non-zero return value specifies the maximum number of reports in the HID driver input report queue.

◆ HidDevice_GetNumHidDevices()

DWORD HidDevice_GetNumHidDevices	(	const WORD	Vid,
		const WORD	Pid
	)

Determines the number of devices connected to the system with matching VID/PID.

This function returns the number of connected devices. This does not imply that a device is available for use. Users must call HidDevice_GetNumHidDevices() before calling any function that takes a device index as a parameter in order to build an up - to - date device list. If a device is installed or removed after calling HidDevice_GetNumHidDevices(), then the device list will be out of date, and the results may be unpredictable. Currently, HidDevice_GetHidString(), HidDevice_GetHidIndexedString(), HidDevice_GetHidAttributes(), and HidDevice_Open() all take a device index parameter.

Parameters

[in]	Vid	- Filter device results by the 2-byte Vendor ID value.
[in]	Pid	- Filter device results by the 2-byte Product ID value.

Note: If both Vid and Pid are zero (0x0000), devices will NOT be filtered by Vid/Pid.

Returns: Returns the number of devices connected to the system which have VID/PID of Vid/Pid. A return value of 0 indicates that no devices are available. Otherwise returns the number of connected devices. When referring to a device by dwDeviceIndex, the index may range from 0 to (HidDevice_GetNumHidDevices() � 1).

◆ HidDevice_GetOutputReportBufferLength()

WORD HidDevice_GetOutputReportBufferLength ( const HID_DEVICE device )

Returns the maximum output report size including the report ID.

Parameters

[in] device is an open handle to the device as returned by HidDevice_Open()

Returns: A return value of zero indicates that the specified device cannot be found. A non-zero value specifies the maximum output report size, including the report ID.

◆ HidDevice_GetString()

SLAB_HID_DEVICE_STATUS HidDevice_GetString	(	const HID_DEVICE	device,
		const BYTE	WhichHidStringToReturn,
		char *	deviceString,
		const DWORD	deviceStringLengthInBytes
	)

Gets a "Product string".

This function returns an ASCII NULL-terminated Vendor ID string, Product ID string, serial number string, manufacturer string, product description string, or full path string for the device specified by device parameter.

The Vendor ID string is derived from the "full path" string. deviceString must point to a buffer at least MAX_VID_LENGTH bytes long.

The Product ID string is derived from the "full path" string. deviceString must point to a buffer at least MAX_PID_LENGTH bytes long.

The full path string is the "device interface path" or "Device Path". This path can be passed to Win32 functions such as CreateFile(). deviceString must point to a buffer at least MAX_PATH_LENGTH bytes long.

The Serial Number string is the Serial Number string from the specified Hid device's USB Device Descriptor's iSerialNumber Serial Number String Descriptor. deviceString must point to a buffer at least MAX_SERIAL_STRING_LENGTH bytes long.

The Manufacturer Description string is the Manufacturer string from the specified Hid device's USB Device Descriptor's iManufacturer Manufacturer String Descriptor. deviceString must point to a buffer at least MAX_MANUFACTURER_STRING_LENGTH bytes long.

The Product string is the product string from the specified Hid device's USB Device Descriptor's iProduct Product String Descriptor. deviceString must point to a buffer at least MAX_PRODUCT_STRING_LENGTH bytes long.

Returned strings are UCS-1?/ASCII and NULL-terminated. (verified)

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	WhichHidStringToReturn	is the indication of which string to return, one of HID_DEVICE_STRING_ID
[out]	deviceString	points at a buffer into which the string will be copied and returned
[in]	deviceStringLengthInBytes	is the size, in bytes/octets, of the buffer into which the the string will be copied and returned I.e. sizeof deviceString buffer

Note: Once a device is opened dwDeviceIndex is no longer valid, and HidDevice_GetString() must be used rather than HidDevice_GetHidString()

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_NOT_FOUND	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_INVALID_BUFFER_SIZE	– failed, `deviceStringLengthInBytes` indicated a buffer that is too small
HID_DEVICE_SYSTEM_CODE	– failed
HID_DEVICE_CANNOT_GET_HID_INFO	– failed_Check_return_

◆ HidDevice_GetTimeouts()

void HidDevice_GetTimeouts	(	const HID_DEVICE	device,
		DWORD *	pGetReportTimeoutInMilliSeconds,
		DWORD *	pSetReportTimeoutInMilliSeconds
	)

Returns the input and output report timeouts over the interrupt endpoint.

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[out]	pGetReportTimeoutInMilliSeconds	points at a 4-byte buffer into which the GetInputReport timeout value will be written
[out]	pSetReportTimeoutInMilliSeconds	points at a 4-byte buffer into which the SetOutputReport timeout value will be written

pGetReportTimeoutInMilliSeconds is the read timeout for HidDevice_GetInputReport_Interrupt_WithTimeout() in milliseconds. This timeout specifies the number of milliseconds that must elapse before HidDevice_GetInputReport_Interrupt_WithTimeout() will return with fewer bytes than requested with an HID_DEVICE_TRANSFER_TIMEOUT error. A timeout of 0 ms will return immediately with any available data.

pSetReportTimeoutInMilliSeconds is the write timeout for HidDevice_SetOutputReport_Interrupt() in milliseconds.This timeout specifies the number of milliseconds that must elapse for an output report before HidDevice_SetOutputReport_Interrupt() returns with an HID_DEVICE_TRANSFER_TIMEOUT error.

Note: Read and write timeouts are maintained for each device but are not persistent across HidDevice_Open() / HidDevice_Close().Allow for sufficient write timeouts to make sure that an output report can be transmitted successfully.

The default get report and set report timeouts are both 1000 ms.

◆ HidDevice_IsOpened()

BOOL HidDevice_IsOpened ( const HID_DEVICE device )

This function returns the device opened state.

Parameters

[in] device is an open handle to the device as returned by HidDevice_Open(), or not

Returns: Returns TRUE if a device is opened. Returns FALSE if the device is invalid or if a device is not opened.

◆ HidDevice_Open()

SLAB_HID_DEVICE_STATUS HidDevice_Open	(	HID_DEVICE *	device,
		const DWORD	dwDeviceIndex,
		const WORD	Vid,
		const WORD	Pid,
		const DWORD	numInputBuffers
	)

tbd

For Windows 2000, the maximum number of queued input reports is 200/MAX_REPORT_REQUEST_2K. For Windows XP and later, the maximum number of queued input reports is 512/MAX_REPORT_REQUEST_XP. For Windows XP and later, the OS default number of queued input reports is 32. In most cases, call this function with numInputBuffers set to MAX_REPORT_REQUEST_XP to achieve the best input report throughput. If numInputBuffers is set to a value higher than the OS maximum, then the OS maximum value will be used. It is very common to list all connected devices by serial string. After calling HidDevice_GetNumHidDevices(), call HidDevice_GetHidString() to get each device's serial string, making sure to check the return code. Since HidDevice_GetHidString() may fail (indicating that the device is unavailable) it is not appropriate to simply add each device's serial string to a list and use the list index to open. Similarly, a device index may have changed since the last time the device list was updated. In this case, the user should select a device solely by serial string and query all devices for a matching serial string. This function allocates the dynamic report buffers, sets timeouts to their default values, and clears the report queue.

Parameters

[out]	device	is a pointer to an HID_DEVICE opaque object location to hold the returned open handle to the device
[in]	dwDeviceIndex	is the desired device's index into the device list used to determine HidDevice_GetNumHidDevices()
[in]	Vid	is the 2-byte Vendor ID value.
[in]	Pid	is the 2-byte Product ID value.
[in]	numInputBuffers	is the number of input report buffers to queue in the HID class driver.

Note: If both Vid and Pid are zero (0x0000), devices will NOT be filtered by Vid/Pid.

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_PARAMETER	– device is an unexpected value
HID_DEVICE_NOT_FOUND	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_ALREADY_OPENED	– failed to open the device, it is already exclusively open elsewhere
HID_DEVICE_SYSTEM_CODE	– failed
HID_DEVICE_CANNOT_GET_HID_INFO	– failed

◆ HidDevice_SetFeatureReport_Control()

SLAB_HID_DEVICE_STATUS HidDevice_SetFeatureReport_Control	(	const HID_DEVICE	device,
		BYTE *	ReportBuffer,
		const DWORD	ReportBufferLengthInBytes
	)

This function sends an HID feature report from the host to the device over the control endpoint.

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	ReportBuffer	is a byte array containing a feature report. The first byte specifies the report ID.
[in]	ReportBufferLengthInBytes	- The size of ReportBuffer in bytes I.e. the size of the feature report including the report ID.

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_BUFFER_SIZE	– ReportBuffer and/or ReportBufferLengthInBytes is an unexpected value
HID_DEVICE_NOT_OPENED	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_TRANSFER_FAILED	– failed, interaction with the device failed

◆ HidDevice_SetOutputReport_Control()

SLAB_HID_DEVICE_STATUS HidDevice_SetOutputReport_Control	(	const HID_DEVICE	device,
		BYTE *	ReportBuffer,
		const DWORD	ReportBufferLengthInBytes
	)

Sends an HID output report from the host to the device over the control endpoint.

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	ReportBuffer	- A byte array containing an output report. The first byte specifies the report ID.
[in]	ReportBufferLengthInBytes	- The size of ReportBuffer in bytes

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_BUFFER_SIZE	– ReportBuffer and/or ReportBufferLengthInBytes is an unexpected value
HID_DEVICE_NOT_OPENED	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_UNSUPPORTED_FUNCTION	– failed, this function is not supported on older Windows versions (Windows 2000)
HID_DEVICE_TRANSFER_FAILED	– failed, interaction with the device failed
HID_DEVICE_TRANSFER_TIMEOUT	– failed, interaction with the device timed out

◆ HidDevice_SetOutputReport_Interrupt()

SLAB_HID_DEVICE_STATUS HidDevice_SetOutputReport_Interrupt	(	const HID_DEVICE	device,
		BYTE *	ReportBuffer,
		const DWORD	ReportBufferLengthInBytes
	)

This function sends an HID output report from the host to the device over the interrupt endpoint.

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	ReportBuffer	- A byte array containing an output report. The first byte specifies the report ID.
[in]	ReportBufferLengthInBytes	- The size of ReportBuffer in bytes

Returns: Returns HID_DEVICE_SUCCESS on success, or another HID Device Status Codes Return value if there is an error.

Return values

HID_DEVICE_SUCCESS	– success
HID_DEVICE_INVALID_BUFFER_SIZE	– ReportBuffer and/or ReportBufferLengthInBytes is an unexpected value
HID_DEVICE_NOT_OPENED	– failed, the device specified by the dwDeviceIndex and filtered on by Vid and Pid, was not found
HID_DEVICE_TRANSFER_FAILED	– failed, interaction with the device failed
HID_DEVICE_TRANSFER_TIMEOUT	– failed, interaction with the device timed out

◆ HidDevice_SetTimeouts()

void HidDevice_SetTimeouts	(	const HID_DEVICE	device,
		const DWORD	getReportTimeoutInMilliSeconds,
		const DWORD	setReportTimeoutInMilliSeconds
	)

Sets the input and output report timeouts over the interrupt endpoint.

Timeouts are used for HidDevice_GetInputReport_Interrupt() and HidDevice_SetOutputReport_Interrupt().

Parameters

[in]	device	is an open handle to the device as returned by HidDevice_Open()
[in]	getReportTimeoutInMilliSeconds	- Sets the timeout used in HidDevice_GetInputReport_Interrupt() in milliseconds. This timeout specifies the number of milliseconds that must elapse before HidDevice_GetInputReport_Interrupt() will return fewer bytes than requested with an HID_DEVICE_TRANSFER_TIMEOUT error. A timeout of 0 ms will return immediately with any available data.
[in]	setReportTimeoutInMilliSeconds	- Sets the timeout used in HidDevice_SetOutputReport_Interrupt() in milliseconds.This timeout specifies the number of milliseconds that must elapse during an output report before HidDevice_SetOutputReport_Interrupt() will return with an HID_DEVICE_TRANSFER_TIMEOUT error.

Note: If get report timeouts are set to a large value and no data is received, the application may appear unresponsive.Therefore, it is recommended to set timeouts to an appropriate value before reading from the device. The default value for get report and set report timeouts is 1000 ms and can be set to any number of milliseconds from 0 to 0xFFFFFFFF.

Modules

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ HID_MANUFACTURER_STRING

◆ HID_PATH_STRING

◆ HID_PID_STRING

◆ HID_PRODUCT_STRING

◆ HID_SERIAL_STRING

◆ HID_VID_STRING

◆ MAX_USB_DEVICES

◆ SLAB_HID_DEVICE_API

◆ USE_LEGACY_SLAB_HID_DEVICE_STATUS

◆ WINAPI

Typedef Documentation

◆ HID_DEVICE

Function Documentation

◆ HidDevice_CancelIo()

◆ HidDevice_Close()

◆ HidDevice_FlushBuffers()

◆ HidDevice_GetAttributes()

◆ HidDevice_GetFeatureReport_Control()

◆ HidDevice_GetFeatureReportBufferLength()

◆ HidDevice_GetHandle()

◆ HidDevice_GetHidAttributes()

◆ HidDevice_GetHidGuid()

◆ HidDevice_GetHidIndexedString()

◆ HidDevice_GetHidLibraryVersion()

◆ HidDevice_GetHidString()

◆ HidDevice_GetIndexedString()

◆ HidDevice_GetInputReport_Control()

◆ HidDevice_GetInputReport_Interrupt()

◆ HidDevice_GetInputReport_Interrupt_WithTimeout()

◆ HidDevice_GetInputReportBufferLength()

◆ HidDevice_GetMaxReportRequest()

◆ HidDevice_GetNumHidDevices()

◆ HidDevice_GetOutputReportBufferLength()

◆ HidDevice_GetString()

◆ HidDevice_GetTimeouts()

◆ HidDevice_IsOpened()

◆ HidDevice_Open()

◆ HidDevice_SetFeatureReport_Control()

◆ HidDevice_SetOutputReport_Control()

◆ HidDevice_SetOutputReport_Interrupt()

◆ HidDevice_SetTimeouts()