AN532

DATASHEET SEARCH SITE | WWW.ALLDATASHEET.COM

Document overview

• Manufacturer or author: Provided By ALLDATASHEET.COM(FREE DATASHEET DOWNLOAD SITE)
• PDF pages: 22

Technical content

Visual Basic .NET. Refer to Table 1 for complete details. Figure 1. System Architecture Diagram Table 1. HID Library Include Files

2 Rev. 0.1 2. Library Usage The HID Library contains the following files:  SLABHIDDevice.dll—Dynamic link libra ry that exports a C HID library  SLABHIDDevice.lib—Provides build-time linking for C/C++ projects  SLABHIDDevice.h—Defines HID library function prototypes and constants  SLABHIDDevice.vb—Provides DLL imports and constants for Visual Basic .NET  SLABHIDDevice.bas—Provides DLL import s and constants for Visual Basic 6  SLABHIDDevice.cs—Provides DLL imports, constants, and an HID class for Visual C# 2.1. C/C++ Projects The HID Library is designed to be universally compatible with most programming languages and is exported in C. Perform the following steps to use the library in a C/C++ project: 1. Add “SLABHIDDevice.lib” as a linker input dependency or add the following code: #pragma comment (lib, “SLABHIDDevice.lib”) 2. Include “SLABHIDDevice.h” as needed. 3. Provide “SLABHIDDevice.dll” with the executable (.exe file). 2.2. Visual Basic .NET Projects Perform the following steps to use the library in a Visual Basic .NET project: 1. Include “SLABHIDDevice.vb” in the project to define library constants and library declarations. 2. Provide “SLABHIDDevice.dll” with the executable (.exe file). 2.3. Visual Basic 6 Projects Perform the following steps to use the library in a Visual Basic 6 project: 1. Include “SLABHIDDevice.bas” in the project to define library constants and library declarations. 2. Provide “SLABHIDDevice.dll” with the executable (.exe file). 2.4. Visual C# Projects Perform the following steps to use the library in a Visual C# project: 1. Include "SLABHIDDevice.cs" in the project to define library constants and library declarations. This file also defines an HID class that uses the DLL functions and manages the “HID_DEVICE device” parameter automatically. 2. Provide “SLABHIDDevice.dll” with the executable (.exe file).

1. SLABHIDDevice Library Functions
2. pid— Filter device results by product ID. If both vid and pid are set to 0x0000, devices will not

(HidDevice_GetNumHidDevices() – 1). only functions that take a device index parameter. Table 2. API Functions Table

4 Rev. 0.1 3.2. HidDevice_GetHidString Description: This function returns a null-terminated vendor ID, product ID, device path, serial, manufacturer, or product string for the device specified by an index passed in deviceIndex. Prototype: BYTE HidDevice_GetHidString (DWORD deviceIndex, WORD vid, WORD pid, BYTE hidStringType, char* deviceString, DWORD deviceStringLength) Parameters:1 . deviceIndex— Index specifying which device to retrieve the string from. This value ranges from 0 to (HidDevice_GetNumHidDevices() – 1). 2. vid— Filter device results by vendor ID. If both vid and pid are set to 0x00 00, devices will not be filtered by VID/PID. 3. pid— Filter device results by product ID. If both vid and pid are set to 0x0000, devices will not be filtered by VID/PID. 4. hidStringType —Determines if deviceString contains a vendor ID, product ID, device path, serial, manufacturer, or product string. 5. deviceString— Pointer to a user-d efined, ASCII string that will contain a NULL-terminated device string on return. The string must be allocated with enough space to return the desired string. 6. deviceStringLength— The length of deviceString in bytes. Definition Value Length Description HID_VID_STRING 0x01 5 Vendor ID HID_PID_STRING 0x02 5 Product ID HID_PATH_STRING 0x03 260 Device path HID_SERIAL_STRING 0x04 256 Serial string HID_MANUFACTURER_STRING 0x05 256 Manufacturer String HID_PRODUCT_STRING 0x06 256 Product String

Rev. 0.1 5 Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_SYSTEM _CODE HID_DEVICE_ALREADY_OPENED HID_DEVICE_CANNOT_GET_HID_INFO 3.3. HidDevice_GetHidIndexedString Description: This function returns an ASCII, null-terminated USB string descriptor using the specified string descriptor index for the device specified by deviceIndex. Prototype: BYTE HidDevice_GetHidIndexedString (DWORD deviceIndex, WORD vid, WORD, pin, DWORD stringIndex, char* deviceString, DWORD deviceStringLength) Parameters:1 . deviceIndex— Index specifying from which device to retrieve the string. This value ranges from 0 to (HidDevice_GetHidNumDevices() – 1). 2. vid— Filter device results by ven dor ID. If both vid and pid ar e set to 0x0000, devices will not be filtered by VID/PID. 3. pid— Filter device results by prod uct ID. If both vid and pid are set to 0x0000, devices will not be filtered by VID/PID. 4. stringIndex— Index specifying which USB string descriptor to retrieve. 5. deviceString— Pointer to a user-d efined, ASCII string that will contain a NULL-terminated device string on return. The string must be allocated with enough space to return the desired string and must be at least 256 bytes. 6. deviceStringLength— The length of deviceString in bytes. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_SYSTEM _CODE HID_DEVICE_ALREADY_OPENED

6 Rev. 0.1 3.4. HidDevice_GetHidAttributes Description: This function returns the USB vendor ID, produc t ID, and device release number for the device specified by deviceIndex. Prototype: BYTE HidDevice_GetHidAttributes (DWORD deviceIndex, WORD vid, WORD pid, WORD* deviceVid, WORD* devicePid, WORD* deviceReleaseNumber) Parameters:1 . deviceIndex— Index specifying from which device to retrieve attributes. This value ranges from 0 to (HidDevice_GetNumHidDevices() – 1). 2. vid— Filter device results by ven dor ID. If both vid and pid ar e set to 0x0000, devices will not be filtered by VID/PID. 3. pid— Filter device results by prod uct ID. If both vid and pid are set to 0x0000, devices will not be filtered by VID/PID. 4. deviceVid— Returns the USB device vendor ID. 5. devicePid— Returns the USB device product ID. 6. deviceReleaseNumber— Returns the USB device bcdVersion, or device release number, in binary-coded decimal. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_SYSTEM_CODE HID_DEVICE_ALREADY_OPENED 3.5. HidDevice_GetHidGuid Description: This function returns the HID GUID. Prototype: void HidDevice_GetHidGuid (void* hidGuid) Parameters:1 . hidGuid— Returns the HID GUID. Remarks: See "8. Surprise Removal" on page 21 for more information on surprise removal. 3.6. HidDevice_GetLibraryVersion Description: This function returns the library version and w hether the build is a debug or release version. Prototype: BYTE HidDevice_GetLibraryVersion (BYTE* major, BYTE* minor, BOOL* release) Parameters:1 . major— Returns the library major version number. This value ranges from 0 to 255. 2. minor— Returns the library minor version number. This value ranges from 0 to 255. 3. release— Returns TRUE if the library was built in release mode. Returns FALSE if the library was built in debug mode. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_INVALID_BUFFER_SIZE

1. SLABHIDDevice Library Functions for Opened Devices

Table 3. API Functions for Opened Devices Note: These functions require an additional "HID_DEVICE device" parameter at the beginning of the argument list. This parameter is an HID class object pointer as returned by HidDevice_Open().

8 Rev. 0.1 4.1. HidDevice_Open Description: Opens a device using a device index and returns a device object pointer which will be used for subsequent access. Prototype: BYTE HidDevice_Open (HID_DEVICE* device, DWORD deviceIndex, WORD vid, WORD pid, DWORD numInputBuffers) Parameters:1 . device— Returns a pointer to an HID class object used for subsequent device access. 2. deviceIndex— Zero-based device index ranging from 0 to (HidDevice_GetNumDevices() – 1). 3. vid— Filter device results by vendor ID. If both vi d and pid are set to 0x0000, then devices will not be filtered by VID/PID. 4. pid— Filter device results by product ID. If both vid and pid are set to 0x0000, then devices will not be filtered by VID/PID. 5. numInputBuffers— Specifies the number of input report buffers to queue in the HID driver. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_ALREADY_OPENED HID_DEVICE_CANNOT_GET_HID_INFO HID_DEVICE_NOT_FOUND Remarks: For Windows 2000, the maximum numb er of queued input reports is 200. For Windows XP and later, the maximum number of queued input reports is 512. For Windows XP and later, the OS default number of queued input reports is 32. In most cases, call this function with numI nputBuffers set to M AX_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 connect ed 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 inde x may have changed since the last time the device list was updated. In this case, the user should sele ct 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. Definition Value Description MAX_REPORT_REQUEST_XP 512 Maximum number of input report buffers for Windows XP and later. MAX_REPORT_REQUEST_2K 200 Maximum number of input report buffers for Windows 2000. DEFAULT_REPORT_INPUT_BUFFER 0 Use OS-dependent HID driver default.

Rev. 0.1 9 4.2. HidDevice_IsOpened Description: This function returns the device opened state. Prototype: BOOL HidDevice_IsOpened (HID_DEVICE device) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). Return Value: Returns TRUE if a device is opened. Returns FALSE if the device is invalid or if a device is not opened. 4.3. HidDevice_GetHandle Description: This function returns the HID handle for the currently-opened device Prototype: HANDLE HidDevice_GetHandle (HID_DEVICE device) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). Return Value: Returns a Windows HANDLE created by ::CreateFile() in HidDevice_Open() . Returns INVALID_HANDLE_VALUE if a device is not open or if there was an error opening a device. 4.4. HidDevice_GetString Description: This function returns an ASCII, null-terminated vendor ID, product ID, device path, serial, manufacturer, or product string for the device specified by device. Prototype: BYTE HidDevice_GetString (HID_DEVICE device, BYTE hidStringType, char* deviceString, DWORD deviceStringLength) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. hidStringType— Determines if deviceString contains a vendor ID, product ID, device path, serial, manufacturer, or product string. 5. deviceString— Pointer to a user-defined, ASCII string which will contain a NU LL-terminated device string on return. The string must be allocated with enough space to return the desired string. 6. deviceStringLength— The length of deviceString in bytes. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_NOT_OPENED HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_SYSTEM _CODE HID_DEVICE_ALREADY_OPENED HID_DEVICE_CANNOT_GET_HID_INFO Remarks: Once a device is opened, deviceIndex is no longer valid. Similarl y, to retrieve a USB string, HidDevice_GetString() must be used rather than HidDevice_GetHidString(). Definition Value Length Description HID_VID_STRING 0x01 5 Vendor ID HID_PID_STRING 0x02 5 Product ID HID_PATH_STRING 0x03 260 Device path HID_SERIAL_STRING 0x04 256 Serial string HID_MANUFACTURER_STRING 0x05 256 Manufacturer String HID_PRODUCT_STRING 0x06 256 Product String

10 Rev. 0.1 4.5. HidDevice_GetIndexedString Description: This function returns an ASCII, null-terminated USB string descriptor using the specified string descriptor index for the currently-open device. Prototype: BYTE HidDevice_GetIndexedString (HID_DEVICE_ device, DWORD stringIndex, char* deviceString, DWORD deviceStringLength) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. stringIndex— Index specifying which USB string descriptor to retrieve. 3. deviceString — Pointer to a user-defined, ASCII string which will contain a NU LL-terminated device string on return. The string must be allocated with enough space to return the desired string and must be at least 256 bytes. 4. deviceStringLength —The length of deviceString in bytes. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_NOT_OPENED HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_SYSTEM_CODE 4.6. HidDevice_GetAttributes Description: This function returns the USB vendor ID, product ID, and device release number for the currently- open device. Prototype: BYTE HidDevice_GetAttributes (HID_DEVICE device, WORD* deviceVid, WORD* devicePid, WORD* deviceReleaseNumber) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. deviceVid— Returns the USB device vendor ID. 3. devicePid— Returns the USB device product ID. 4. deviceReleaseNumber— Returns the USB device bcdVersion, or device release number, in binary-coded decimal. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_NOT_OPENED HID_DEVICE_SYSTEM_CODE

Rev. 0.1 11 4.7. HidDevice_SetFeatureReport_Control Description: This function sends an HID featur e report from the host to the device over the control endpoint. Prototype: BYTE HidDevice_SetFeatureReport_Control (HID_DEVICE device, BYTE* buffer, DWORD bufferSize) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. buffer— A byte array containing a feature report. The first byte specifies the report ID. 3. bufferSize— The size of the feature report including the report ID. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_NOT_OPENED HID_DEVICE_TRANSFER_FAILED 4.8. HidDevice_GetFeatureReport_Control Description: This function receives an HID feature report from the host to the device over the control endpoint. Prototype: BYTE HidDevice_GetFeatureReport_Control (HID_DEVICE device, BYTE* buffer, DWORD bufferSize) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. buffer— Returns a byte array containing a feature report with report ID. The user must call this function with the first byte in buffer set to the report ID of the report to receive. Buffer must be large enough to hold the feature report includ ing report ID and, in most cases, should be allocated with a size equal to HidDevice_GetFeatureReportBufferLength(). 3. bufferSize— The size of buffer in bytes. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_NOT_OPENED HID_DEVICE_TRANSFER_FAILED 4.9. HidDevice_SetOutputReport_Interrupt Description: This function sends an HID output report from th e host to the device over the interrupt endpoint. Prototype: BYTE HidDevice_SetOutputReport_Interrupt (HID_DEVICE device, BYTE* buffer, DWORD bufferSize) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. buffer— A byte array containing an output report. The first byte specifies the report ID. 3. bufferSize— The size of the output report including the report ID. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_NOT_OPENED HID_DEVICE_TRANSFER_FAILED HID_DEVICE_TRANSFER_TIMEOUT

12 Rev. 0.1 4.10. HidDevice_GetInputReport_Interrupt Description: This function receives an HID input report from the host to the device over the interrupt endpoint. Prototype: BYTE HidDevice_GetInputReport_Interrupt (HID_DEVICE device, BYTE* buffer, DWORD bufferSize. DWORD numReports, DWORD* bytesReturned) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. buffer— Returns a byte array of data containing up to numReports number of input reports. Each report occupies HidDevice_GetInputReportBufferLength() number of bytes. The first byte of each report buffer contains the report ID. 3. bufferSize— The size of buffer in bytes. 4. numReports— The maximum number of input reports to return. 5. bytesReturned— The number of bytes returned in buffer. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_NOT_OPENED HID_DEVICE_TRANSFER_FAILED HID_DEVICE_TRANSFER_TIMEOUT Remarks: 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, th en bytesReturned will return with 128 bytes. The firs t 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().

Rev. 0.1 13 4.11. HidDevice_SetInputReport_Control Description: This function sends an HID inpu t report from the host to the device over the control endpoint. Prototype: BYTE HidDevice_SetInputReport_Control (HID_DEVICE device, BYTE* buffer, DWORD bufferSize) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. buffer— A byte array containing an output report. The first byte specifies the report ID. 3. bufferSize— The size of the output report including the report ID. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_UNSPUPPORTED_FUNCTION HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_NOT_OPENED HID_DEVICE_TRANSFER_FAILED Remarks: Attempting to call this function on Windows 2000 or earlier will fail and return HID_DEVICE_UNSUPPORTED_FUNCTION. 4.12. HidDevice_GetInputReport_Control Description: This function receives an HID input report from the host to the device over the control endpoint. Prototype: BYTE HidDevice_GetInputReport_Control (HID_DEVICE device, BYTE* buffer, DWORD bufferSize) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. buffer— Returns a byte array containing an input report with report ID. The user must call this function with the first byte in buffer set to the report ID of the report to receive. Buffer 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(). 3. bufferSize— The size of buffer in bytes. Return Value: HID_DEVICE_SUCCESS HID_DEVICE_NOT_FOUND HID_DEVICE_UNSPUPPORTED_FUNCTION HID_DEVICE_INVALID_BUFFER_SIZE HID_DEVICE_NOT_OPENED HID_DEVICE_TRANSFER_FAILED Remarks: Attempting to call this function on Windows 2000 or earlier will fail and return HID_DEVICE_UNSUPPORTED_FUNCTION.

14 Rev. 0.1 4.13. HidDevice_GetInputReportBufferLength Description: This function returns the maximum inpu t report size, including the report ID. Prototype: WORD HidDevice_GetInputReportBuffferLength (HID_DEVICE device) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). Return Value: A return value of zero indicates that the spec ified 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(). 4.14. HidDevice_GetOutputReportBufferLength Description: This function returns the maximum output report size including the report ID. Prototype: WORD HidDevice_GetOutputReportBuffferLength (HID_DEVICE device) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). Return Value: A return value of zero indicates that the spec ified device cannot be found. A non-zero value specifies the maximum output report size, including the report ID. 4.15. HidDevice_GetFeatureReportBufferLength Description: This function returns the maximum featur e report size, including the report ID. Prototype: WORD HidDevice_GetFeatureReportBuffferLength (HID_DEVICE device) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). Return Value: A return value of zero indicates that the spec ified device cannot be found. A non-zero value specifies the maximum feature report size, includin g the report ID. This function should be called to determine the appropriate buffer size for HidDevice_GetFeatureReport_Control(). 4.16. HidDevice_GetMaxReportRequest Description: This function returns the maximum number of inpu t reports that can be queued in the HID driver. Prototype: WORD HidDevice_GetMaxReportRequest (HID_DEVICE device) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). Return Value: A return value of zero indicates that the spec ified device cannot be found. A non-zero value specifies the maximum size of the HID driver input report queue in number of reports. This function should be called to determine the appropriate buffer size for HidDevice_GetInputReport_Interrupt(). For Windows XP and later, this function returns up to 512. For Windows 2000, this function returns up to 200. This function cannot be called before a device is opened. See "4.1. HidDevice_Open" on page 8 for more information

Rev. 0.1 15 4.17. HidDevice_FlushBuffers Description: This function deletes all pending input reports in the HID driver queue and the HID library. Prototype: BYTE HidDevice_FlushBuffers (HID_DEVICE device) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). Return Value: Returns TRUE if the function completed successfully. Returns FALSE if the function failed or if the device does not exist. Remarks: 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. 4.18. HidDevice_CancelIo Description: This function cancels all pendi ng input and output operations issued by the calling thread. Prototype: BYTE HidDevice_CancelIo (HID_DEVICE device) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). Return Value: Returns TRUE if the function completed successfully. Returns FALSE if the function failed or if the device does not exist. Remarks: ::CancelIo() called in one thread cannot cancel reads and writes issued in another thread. Therefore, it is necessary to call this function in all threads that call HidDevice_GetInputReport_Interrupt() prior to call HidDevice_Close(). See "7. Thread Read Access Models" on page 19 for more information. 4.19. HidDevice_GetTimeouts Description: This function returns the input and output report timeouts over the interrupt endpoint. Prototype: BYTE HidDevice_GetTimeouts (HID_DEVICE device, DWORD* getReportTimeout, DWORD* setReportTimeout) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. getReportTimeout— Returns the read timeout for HidDevice_GetInput Report_Interrupt() in milliseconds. This timeout specifies the number of milliseco nds that must elapse before HidDevice_GetInputReport_Interrupt() 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. 3. setReportTimeout— Returns 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. Remarks: Read and write timeouts are maintained for each device but are not persistent across HidDevice_Open()/HidDevice_Close(). Allow for sufficient write ti meouts to make sure that an output report can be transmitted successfully. The default get report and set report timeouts are both 1000 ms.

16 Rev. 0.1 4.20. HidDevice_SetTimeouts Description: This function sets the input and ou tput report timeouts over the interrupt endpoint. Timeouts are used for HidDevice_GetInputReport_Interrupt() and HidDevice_SetOutputReport_Interrupt(). Prototype: BYTE HidDevice_SetTimeouts(HID_DEVICE device, DWORD getReportTimeout, DWORD setReportTimeout) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). 2. getReportTimeout— Sets the timeout used in HidDevice_GetInputReport_Interrupt() in milliseconds. This timeout specifies the number of milliseco nds that must elapse before HidDevice_GetInputReport_Interrupt() will return fewer bytes than requeste d with an HID_DEVICE_TRANSFER_TIMEOUT error. A timeout of 0 ms will return immediately with any available data. 3. setReportTimeout— 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. Remarks: If get report timeouts are set to a large value a nd 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. 4.21. HidDevice_Close Description: This function closes the currently-open device. Prototype: BYTE HidDevice_Close (HID_DEVICE device) Parameters:1 . device— A pointer to an HID class object returned by HidDevice_Open(). Return Value: HID_DEVICE_SUCCESS HID_DEVICE_HANDLE_ERROR HID_DEVICE_NOT_FOUND HID_DEVICE_NOT_OPENED Remarks: This function deletes the internal library input report buffer and cancel s any pending input report reads via ::CancelIo(). This function is responsible for dea llocating the HID cla ss object allocated in HidDevice_Open().

an error. Table 4 describes each return code. Table 4. Return Code Descriptions HID_DEVICE_SUCCESS 0x00 Function returned successfully. with less bytes than requested. function parameters are incorrect. HID_DEVICE_HANDLE_ERROR 0x07 HID ::CreateFile() handle is invalid. LastError() to retrieve the system error code.

18 Rev. 0.1 6. Thread Safety The HID library and associated functions are not thre ad safe. This means that calling library functions simultaneously from multiple threads may have undesirable effects. To use the library functions in more than one thread, the user should do the following: 1. Call HID library function s from within a critical section such that only a single function is being called at any given time. If a function is being called in one thread, the user must prevent another thread from calling any function until the first function returns. 2. HidDevice_GetInputReport_Interrupt() issues a pending read request that cannot be canceled from another thread. If the user calls HidDevice_Close() in a thread other than the one in which the read request was created, the device will not be accessible after calling HidDevice_Close(). The thread that issued the pending read request must return/terminate successfully before the device can be accessed again. See "7. Thread Read Access Models" on page 19 for more information.

1. Thread Read Access Models

device until the thread releases access to the device handle. operation times out. ::CancelIo() cancels any pending I/O requests issued by the calling thread.

1. Read*— Read is still pending and was issued in the specified thread
2. Read? — Read is still pending and was issued in one of the threads (indeterminate)
3. Open— Call HidDevice_Open()
4. Read— Call HidDevice_GetInputReport_Interrupt()
5. Close— Call HidDevice_Close()
6. Cancel— Call HidDevice_CancelIo()

Table 5. Single Thread Access Model (Safe) Table 6. Split Thread Access Model (Unsafe) Table 7. Split Thread Access Mode (Safe)

Table 8. Multi-Thread Access Model (Unsafe) Table 9. Multi-Thread Access Model (Safe)

Rev. 0.1 21 8. Surprise Removal HidDevice_GetHidGuid() returns the HID GUID so that Windows app lications or services can register for the WM_DEVICECHANGE Windows message. Once registered, the application will receiv e device arrival and removal notifications for HID devices. The application should retrieve the device path to filter devices. Similarly, if a DBT_DEVICEREMOVECOMPLETE message is received, the application sh ould check to see if the device path matches the device path of any connected devices. If this is the case, the device was removed, and the application should close the device. In addition, if a DBT_DEVICEARRIVAL message is received, then the application might add the new device to a device list so that users can select any HID matching th e required VID/PID. See accompanying example code for information on how to implement surprise removal and device arrival. Search for Knowledge Base Article # 222649, 311158, and 311153 fo r programming examples for C++, Visual Basic .NET, and Visual C#.

22 Rev. 0.1 CONTACT INFORMATION Silicon Laboratories Inc.

400 West Cesar Chavez

Austin, TX 78701 Tel: 1+(512) 416-8500 Fax: 1+(512) 416-9669 Toll Free: 1+(877) 444-3032 Please visit the Silicon Labs Technical Support web page: https://www.silabs.com/support/pages/contacttechnicalsupport.aspx and register to submit a technical support request. Silicon Laboratories and Silicon Labs are trademarks of Silicon Laboratories Inc. Other products or brandnames mentioned herein are trademarks or registered trademarks of their respective holders. The information in this document is believed to be accurate in all respects at the time of publication but is subject to change without notice. Silicon Laboratories assumes no responsibility for errors and omissions, and disclaims responsibility for any consequences resulting from the use of information included herein. Additionally, Silicon Laboratories assumes no responsibility for the functioning of undescribed features or parameters. Silicon Laboratories reserves the right to make changes without further notice. Silicon Laboratories makes no warranty, rep- resentation or guarantee regarding the suitability of its products for any particular purpose, nor does Silicon Laboratories assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation conse- quential or incidental damages. Silicon Laboratories products are not designed, intended, or authorized for use in applications intended to support or sustain life, or for any other application in which the failure of the Silicon Laboratories product could create a situation where per- sonal injury or death may occur. Should Buyer purchase or use Silicon Laboratories products for any such unintended or unauthorized ap- plication, Buyer shall indemnify and hold Silicon Laboratories harmless against all claims and damages.