/** \file SebaHID.h \brief \par Project: Reader3 \par Developed using: MS Visual C++ 10 \version 1.0.4.0 \par Version History: - Version 1.0.4.0 - 3 August 2010 moved project to MS Visual Studio 10 improved input check of HID_WriteFile added new error return value - Version 1.0.3.2 - 14 July 2010 corrected the set max report requests in HID_Open due to wrong OS version analysis - Version 1.0.3.1 - 16 June 2010 added more trace capabilities - Version 1.0.3.0 - 21 May 2010 DLL will be statically linked against CRT due to import problems on other PC's added a proper description of transfer details in ReadMe.txt - Version 1.0.2.0 - 7 May 2010 modified HID_ReadFile for reading old data after a buffer overflow added/modified some trace routes - Version 1.0.1.0 - 19 April 2010 moved whole project back to MS Visual Studio 8.0 due to debugging problems in SDV application - Version 1.0.0.3 - 19 March 2010 added proper debug information and trace capabilities via file print - Version 1.0.0.2 - 9 March 2010 changed return values to signed int modified HID_ReadFile function relating to buffer overflows - Version 1.0.0.1 - 15 Janaury 2010 library included first in SDV application minor differences to previous version - Version 0.9.0.0 - 8 December 2009 first library version */ #ifdef __cplusplus extern "C" { #endif #ifndef _SEBAHID_H_ #define _SEBAHID_H_ // The following ifdef block is the standard way of creating macros which make exporting // from a DLL simpler. All files within this DLL are compiled with the SEBAHIDDRIVER_EXPORTS // symbol defined on the command line. This symbol should not be defined on any project // that uses this DLL. This way any other project whose source files include this file see // SEBAHID_API functions as being imported from a DLL, wheras this DLL sees symbols // defined with this macro as being exported. #ifdef SEBAHID_EXPORTS #define SEBAHID_API extern "C" __declspec(dllexport) #else #define SEBAHID_API extern "C" __declspec(dllimport) #endif /// HID Device return codes /// HID read buffer contains old data /// former Read buffer was too small #define HID_DEVICE_RBUFF_OLD_DATA 1 /// HID action/transfer was successful #define HID_DEVICE_SUCCESS 0 /// HID device was not found #define HID_DEVICE_NOT_FOUND -1 /// HID device is not opened #define HID_DEVICE_NOT_OPENED -2 /// HID device is allready opened #define HID_DEVICE_ALREADY_OPENED -3 /// Timeout occurs during transfer #define HID_DEVICE_TRANSFER_TIMEOUT -4 /// HID transfer failed #define HID_DEVICE_TRANSFER_FAILED -5 /// HID transfer report lost #define HID_DEVICE_REPORT_LOST -6 /// HID Read buffer overflow #define HID_DEVICE_RBUFF_OVERFLOW -7 /// HID Write buffer overflow (could not handle so much data with this protocol) #define HID_DEVICE_TBUFF_OVERFLOW -8 /// Invalid handle #define HID_DEVICE_HANDLE_ERROR -9 /// Unknown error #define HID_DEVICE_UNKNOWN_ERROR -100 /** \brief Device information structure. */ struct strHidDevice{ /// Handle for hid device HANDLE hndHidDevice; /// Indicator if device is opened BOOL bDeviceOpen; /// Timeout for GetReport requests UINT uGetReportTimeout; /// Timeout for SetReport requests UINT uSetReportTimeout; OVERLAPPED oRead; OVERLAPPED oWrite; /// Maximum length of InReport's WORD wInReportBufferLength; /// Maximum length of OutReport's WORD wOutReportBufferLength; /// InBuffer contains data, if InReport provides more data then the application actual need BYTE inBuffer[8192]; /// Number of current used bytes in inBuffer WORD inBufferUsed; /// Number of reports still to fetch from queue WORD reportsLeft; }; /** \fn VOID HID_Init(struct strHidDevice* pstrHidDevice); \brief Init structure with default values. - It is important to call HID_Init before calling HID_Open\n to avoid unpredicted behavoir \param pstrHidDevice: Structure which contains important data of an HID device */ SEBAHID_API INT HID_Init(struct strHidDevice* pstrHidDevice); /** \fn INT HID_Open(struct strHidDevice* pstrHidDevice, WORD vid, WORD pid, DWORD deviceIndex) \brief Open a Hid Device. \param pstrHidDevice: Structure which contains important data of an HID device \param vid: Vendor-Id of the device \param pid: Product-Id of the device \param deviceIndex: Index of the device.If only one HID is connected, deviceIndex is 0. - Starts with zero - Maximum value is (HID_GetNumOfDevices()-1) \return HID_DEVICE_SUCCESS:. \n HID_DEVICE_NOT_FOUND:. \n HID_DEVICE_ALREADY_OPENED:. */ SEBAHID_API INT HID_Open(struct strHidDevice* pstrHidDevice, WORD VID, WORD PID, DWORD deviceIndex); /** \fn INT HID_Close(struct strHidDevice* pstrHidDevice) \brief Close a Hid Device. \param pstrHidDevice: Structure which contains important data of an HID device \return HID_DEVICE_SUCCESS:. \n HID_DEVICE_NOT_OPENED:. \n HID_DEVICE_HANDLE_ERROR:. */ SEBAHID_API INT HID_Close(struct strHidDevice* pstrHidDevice); /** \fn DWORD HID_GetNumOfDevices(WORD vid, WORD pid); \brief Returns the number of connected devices with the specific vid and pid. \param VID: Vendor-Id of the device \param PID: Product-Id of the device \return Number of connected devices with the specific vid and pid. */ SEBAHID_API DWORD HID_GetNumOfDevices(WORD vid, WORD pid); /** \fn INT HID_GetSerialNumber(struct strHidDevice* pstrHidDevice, BYTE * Buffer, ULONG BufferLength); \brief Returns the serial number of a device in UNICODE format. \param pstrHidDevice: Structure which contains important data of an HID device \param Buffer: Buffer for serial number (minimum size of 34 bytes) \param BufferLength: Length of given buffer \return HID_DEVICE_SUCCESS:. \n HID_DEVICE_HANDLE_ERROR:. */ SEBAHID_API INT HID_GetSerialNumber(struct strHidDevice* pstrHidDevice, BYTE * Buffer, ULONG bufferLength); /** \fn INT HID_GetVersionNumber(struct strHidDevice* pstrHidDevice, USHORT * lpVersionNumber); \brief Returns the version number of a device. \param pstrHidDevice: Structure which contains important data of an HID device \param VersionNumber: Pointer to USHORT variable. \return HID_DEVICE_SUCCESS:. \n HID_DEVICE_HANDLE_ERROR:. */ SEBAHID_API INT HID_GetVersionNumber(struct strHidDevice* pstrHidDevice, USHORT * VersionNumber); /** \fn INT HID_WriteFile(struct strHidDevice* pstrHidDevice, BYTE* buffer, DWORD bufferSize); \brief Writes a data stream to the given hid device. Needed report headers will be generated automatically. \param pstrHidDevice: Structure which contains important data of an HID device \param buffer: Buffer which will be send \param bufferSize: Number of bytes to be send \param bytesWritten: Number of bytes actually written \return HID_DEVICE_SUCCESS:. \n HID_DEVICE_TBUFF_OVERFLOW:. \n HID_DEVICE_NOT_OPENED:. \n HID_DEVICE_TRANSFER_TIMEOUT:. \n HID_DEVICE_TRANSFER_FAILED:. */ SEBAHID_API INT HID_WriteFile(struct strHidDevice* pstrHidDevice, BYTE* buffer, DWORD bufferSize, DWORD* bytesWritten); /** \fn INT HID_ReadFile(struct strHidDevice* pstrHidDevice, BYTE* buffer, DWORD bufferSize, DWORD* bytesReturned); \brief Reads a data stream from the given hid device. Prefixed report header will be skipped. If internal buffer still contains data the data will be copied into buffer and HID_DEVICE_RBUFF_OLD_DATA will be returned. If internal buffer still contains data and/or the assigned buffer is too small the buffer is filled until end and a HID_DEVICE_RBUFF_OVERFLOW resp. HID_DEVICE_RBUFF_OLD_DATA will be returned. A further call of HID_ReadFile will copy the rest of the data into the assigned buffer. \param pstrHidDevice: Structure which contains important data of an HID device \param buffer: Pointer to buffer in which will be written \param bufferSize: Size of buffer \param bytesReturned: Number of bytes actually read \return HID_DEVICE_RBUFF_OLD_DATA:. \n HID_DEVICE_SUCCESS:. \n HID_DEVICE_NOT_OPENED:. \n HID_DEVICE_TRANSFER_TIMEOUT:. \n HID_DEVICE_TRANSFER_FAILED:. \n HID_DEVICE_REPORT_LOST:. \n HID_DEVICE_RBUFF_OVERFLOW:. */ SEBAHID_API INT HID_ReadFile(struct strHidDevice* pstrHidDevice, BYTE* buffer, DWORD bufferSize, DWORD* bytesReturned); /** \fn INT HID_FlushBuffer(struct strHidDevice* pstrHidDevice); \brief Flush USB buffer for the given device \param pstrHidDevice: Structure which contains important data of an HID device. \return HID_DEVICE_SUCCESS:. \n HID_DEVICE_HANDLE_ERROR:. \n HID_DEVICE_UNKNOWN_ERROR:. */ SEBAHID_API INT HID_FlushBuffer(struct strHidDevice* pstrHidDevice); /** \fn INT HID_RegisterForDeviceNotification(HWND hWnd , HDEVNOTIFY* diNotifyHandle); \brief Registers the window pointed to by handle hWnd to receive notification when devices are added or removed from the system. \param pstrHidDevice: Structure which contains important data of an HID device. \param diNotifyHandle: Device notification handle pointer address. \return HID_DEVICE_SUCCESS:. \n HID_DEVICE_HANDLE_ERROR:. */ SEBAHID_API INT HID_RegisterForDeviceNotification(HWND hWnd , HDEVNOTIFY* diNotifyHandle); /** \fn INT HID_UnRegisterForDeviceNotification(HDEVNOTIFY* diNotifyHandle); \brief UnRegisters the window pointed to by handle hWnd to receive notification when devices are added or removed from the system. \param diNotifyHandle: Device notification handle pointer address. \return HID_DEVICE_SUCCESS:. \n HID_DEVICE_HANDLE_ERROR:. */ SEBAHID_API INT HID_UnRegisterForDeviceNotification(HDEVNOTIFY* diNotifyHandle); /** \fn BOOL HID_IsDeviceAffected(struct strHidDevice* pstrHidDevice); \brief This has to be called inside WM_ON_DEVICECHANGE notification window \param pstrHidDevice: Structure which contains important data of an HID device. \return HID_DEVICE_SUCCESS:. \n HID_DEVICE_HANDLE_ERROR:. */ SEBAHID_API BOOL HID_IsDeviceAffected(struct strHidDevice* pstrHidDevice); #endif #ifdef __cplusplus } #endif