SLABHIDDevice.h

// SLABHIDDevice.h

#ifndef HOST_LIB_SLABHIDDEVICE_INCLUDE_SLABHIDDEVICE_H_INCLUDED_MJWYLEYUPA
#define HOST_LIB_SLABHIDDEVICE_INCLUDE_SLABHIDDEVICE_H_INCLUDED_MJWYLEYUPA

// Includes


#include    "silabs_defs.h"
#include    "silabs_sal.h"
#ifdef _WIN32
#include <windows.h>
#else // !_WIN32
#endif // !_WIN32
#include "Types.h"

#ifdef _WIN32
// 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 CP210xDLL_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 
// CP210xDLL_API functions as being imported from a DLL, whereas this DLL sees symbols
// defined with this macro as being exported.
#ifdef SLAB_HID_DEVICE_EXPORTS
#define SLAB_HID_DEVICE_API
#elif defined(SLAB_HID_DEVICE_BUILD_SOURCE)
#define SLAB_HID_DEVICE_API
#else
#if defined(SILABS_STATIC_LINK)
#define SLAB_HID_DEVICE_API extern
#pragma comment (lib, "SLABHIDDevice.static.lib")
#else // defined(SILABS_STATIC_LINK)
#define SLAB_HID_DEVICE_API __declspec(dllimport)
#pragma comment (lib, "SLABHIDDevice.lib")
#endif // defined(SILABS_STATIC_LINK)
#endif
#else // !_WIN32
#define SLAB_HID_DEVICE_API 
#define WINAPI 
#endif // !_WIN32


// Definitions

#define USE_LEGACY_SLAB_HID_DEVICE_STATUS
#if !defined(USE_LEGACY_SLAB_HID_DEVICE_STATUS) // TODO: Enstone: These defines are a exact duplicate values of HID_DEVICE_STATUS enums in HIDDevice.h.
typedef enum _SLAB_HID_DEVICE_STATUS {
    HID_DEVICE_SUCCESS = 0x00       
    , HID_DEVICE_NOT_FOUND = 0x01                   
    , HID_DEVICE_NOT_OPENED = 0x02
    , HID_DEVICE_ALREADY_OPENED = 0x03
    , HID_DEVICE_TRANSFER_TIMEOUT = 0x04
    , HID_DEVICE_TRANSFER_FAILED = 0x05
    , HID_DEVICE_CANNOT_GET_HID_INFO = 0x06
    , HID_DEVICE_HANDLE_ERROR = 0x07
    , HID_DEVICE_INVALID_BUFFER_SIZE = 0x08
    , HID_DEVICE_SYSTEM_CODE = 0x09
    , HID_DEVICE_UNSUPPORTED_FUNCTION = 0x0A
    , HID_DEVICE_UNKNOWN_ERROR = SILABS_STATUS_UNKNOWN_ERROR
} SLAB_HID_DEVICE_STATUS, *PSLAB_HID_DEVICE_STATUS;
#else // defined(NOT_YET)
typedef BYTE SLAB_HID_DEVICE_STATUS;    
#if !defined(HID_DEVICE_H)
#define HID_DEVICE_SUCCESS                  0x00    
#define HID_DEVICE_NOT_FOUND                0x01                    
#define HID_DEVICE_NOT_OPENED               0x02                    
#define HID_DEVICE_ALREADY_OPENED           0x03                    
#define HID_DEVICE_TRANSFER_TIMEOUT         0x04                    
#define HID_DEVICE_TRANSFER_FAILED          0x05                    
#define HID_DEVICE_CANNOT_GET_HID_INFO      0x06                    
#define HID_DEVICE_HANDLE_ERROR             0x07                    
#define HID_DEVICE_INVALID_BUFFER_SIZE      0x08                    
#define HID_DEVICE_SYSTEM_CODE              0x09                    
#define HID_DEVICE_INVALID_PARAMETER        0x0B                    
#define HID_DEVICE_UNKNOWN_ERROR            SILABS_STATUS_UNKNOWN_ERROR 
#endif
#define HID_DEVICE_UNSUPPORTED_FUNCTION     0x0A                    
#endif // defined(NOT_YET)


#define MAX_USB_DEVICES                 64

#define MAX_REPORT_REQUEST_XP           512 
#define MAX_REPORT_REQUEST_2K           200 

#define DEFAULT_REPORT_INPUT_BUFFERS    0   

#if !defined(HID_DEVICE_H)
#define HID_VID_STRING                  0x01    
#define HID_PID_STRING                  0x02    
#define HID_PATH_STRING                 0x03    
#define HID_SERIAL_STRING               0x04    
#define HID_MANUFACTURER_STRING         0x05    
#define HID_PRODUCT_STRING              0x06    
#endif
#if !defined(MAX_STRING_LENGTH)
#define MAX_VID_LENGTH                  5   
#define MAX_PID_LENGTH                  5   
#define MAX_PATH_LENGTH                 260 
#define MAX_SERIAL_STRING_LENGTH        256 
#define MAX_MANUFACTURER_STRING_LENGTH  256 
#define MAX_PRODUCT_STRING_LENGTH       256 
#define MAX_INDEXED_STRING_LENGTH       256 
#define MAX_STRING_LENGTH               260 
#endif

// Typedefs

typedef void* HID_DEVICE;       

// Exported Functions


#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

_Check_return_
_Ret_range_(0, MAX_USB_DEVICES-1)
SLAB_HID_DEVICE_API DWORD WINAPI
HidDevice_GetNumHidDevices(_In_ _Pre_defensive_ const WORD Vid, _In_ _Pre_defensive_ const WORD Pid);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetHidString(_In_ _Pre_defensive_ const DWORD dwDeviceIndex, _In_ _Pre_defensive_ const WORD Vid, _In_ _Pre_defensive_ const WORD Pid, _In_ _Pre_defensive_ const BYTE WhichHidStringToReturn, char* deviceString, _In_ _Pre_defensive_ const DWORD deviceStringLengthInBytes);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetHidIndexedString(_In_ _Pre_defensive_ const DWORD dwDeviceIndex, _In_ _Pre_defensive_ const WORD Vid, _In_ _Pre_defensive_ const WORD Pid, _In_ _Pre_defensive_ const DWORD stringIndex, char* deviceString, _In_ _Pre_defensive_ const DWORD deviceStringLengthInBytes);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetHidAttributes(_In_ _Pre_defensive_ const DWORD dwDeviceIndex, _In_ _Pre_defensive_ const WORD Vid, _In_ _Pre_defensive_ const WORD Pid, _Out_writes_bytes_(2) _Pre_defensive_ WORD* pDeviceVid, _Out_writes_bytes_(2) _Pre_defensive_ WORD* pDevicePid, _Out_writes_bytes_(2) _Pre_defensive_ WORD* pDeviceReleaseNumber);

SLAB_HID_DEVICE_API void WINAPI
HidDevice_GetHidGuid(_Out_ void *pHIDGuid);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetHidLibraryVersion(_Out_writes_bytes_(1) _Pre_defensive_ BYTE* pMajor, _Out_writes_bytes_(1) _Pre_defensive_ BYTE* pMinor, _Out_writes_bytes_(4) BOOL* pbIsReleaseBuild);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_Open(_Out_ HID_DEVICE* device, _In_ _Pre_defensive_ const DWORD dwDeviceIndex, _In_ _Pre_defensive_ const WORD Vid, _In_ _Pre_defensive_ const WORD Pid, _In_ _Pre_defensive_ const DWORD numInputBuffers);

_Ret_range_(FALSE, TRUE)
_Success_(return)
SLAB_HID_DEVICE_API BOOL WINAPI
HidDevice_IsOpened(_In_ _Pre_defensive_ const HID_DEVICE device);

_Check_return_
SLAB_HID_DEVICE_API HANDLE WINAPI
HidDevice_GetHandle(_In_ _Pre_defensive_ const HID_DEVICE device);

_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetString(_In_ _Pre_defensive_ const HID_DEVICE device, _In_ _Pre_defensive_ const BYTE WhichHidStringToReturn, char* deviceString, _In_ _Pre_defensive_ const DWORD deviceStringLengthInBytes);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetIndexedString(_In_ _Pre_defensive_ const HID_DEVICE device, _In_ _Pre_defensive_ const DWORD stringIndex, char* deviceString, _In_ _Pre_defensive_ const DWORD deviceStringLengthInBytes);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetAttributes(_In_ _Pre_defensive_ const HID_DEVICE device, _Out_writes_bytes_(2) _Pre_defensive_ WORD* pDeviceVid, _Out_writes_bytes_(2) _Pre_defensive_ WORD* pDevicePid, _Out_writes_bytes_(2) _Pre_defensive_ WORD* pDeviceReleaseNumber);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_SetFeatureReport_Control(_In_ _Pre_defensive_ const HID_DEVICE device, _In_reads_bytes_(ReportBufferLengthInBytes) _Pre_defensive_ BYTE* ReportBuffer, _In_ _Pre_defensive_ const DWORD ReportBufferLengthInBytes);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetFeatureReport_Control(_In_ _Pre_defensive_ const HID_DEVICE device, _Out_writes_bytes_(ReportBufferLengthInBytes) _Pre_defensive_ BYTE* ReportBuffer, _In_ _Pre_defensive_ const DWORD ReportBufferLengthInBytes);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_SetOutputReport_Interrupt(_In_ _Pre_defensive_ const HID_DEVICE device, _In_reads_bytes_(ReportBufferLengthInBytes) _Pre_defensive_ BYTE* ReportBuffer, _In_ _Pre_defensive_ const DWORD ReportBufferLengthInBytes);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetInputReport_Interrupt(_In_ _Pre_defensive_ const HID_DEVICE device, _Out_writes_bytes_(ReportBufferLengthInBytes) _Pre_defensive_ BYTE* ReportBuffer, _In_ _Pre_defensive_ const DWORD ReportBufferLengthInBytes, _In_ _Pre_defensive_ const DWORD numReports, _Out_writes_bytes_(sizeof(DWORD)) _Pre_defensive_ DWORD* bytesReturned);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetInputReport_Interrupt_WithTimeout(_In_ _Pre_defensive_ const HID_DEVICE device, _Out_writes_bytes_(ReportBufferLengthInBytes) _Pre_defensive_ BYTE* ReportBuffer, _In_ _Pre_defensive_ const DWORD ReportBufferLengthInBytes, _In_ _Pre_defensive_ const DWORD numReports, _Out_writes_bytes_(sizeof(BYTE)) _Pre_defensive_ DWORD* bytesReturned, _In_ _Pre_defensive_ const DWORD TimeoutMSec);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_SetOutputReport_Control(_In_ _Pre_defensive_ const HID_DEVICE device, _In_reads_bytes_(ReportBufferLengthInBytes) _Pre_defensive_ BYTE* ReportBuffer, _In_ _Pre_defensive_ const DWORD ReportBufferLengthInBytes);

_Check_return_
_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_GetInputReport_Control(_In_ _Pre_defensive_ const HID_DEVICE device, _Out_writes_bytes_(ReportBufferLengthInBytes) _Pre_defensive_ BYTE* ReportBuffer, _In_ _Pre_defensive_ const DWORD ReportBufferLengthInBytes);


SLAB_HID_DEVICE_API WORD WINAPI
HidDevice_GetInputReportBufferLength(_In_ _Pre_defensive_ const HID_DEVICE device);

SLAB_HID_DEVICE_API WORD WINAPI
HidDevice_GetOutputReportBufferLength(_In_ _Pre_defensive_ const HID_DEVICE device);

SLAB_HID_DEVICE_API WORD WINAPI
HidDevice_GetFeatureReportBufferLength(_In_ _Pre_defensive_ const HID_DEVICE device);

SLAB_HID_DEVICE_API DWORD WINAPI
HidDevice_GetMaxReportRequest(_In_ _Pre_defensive_ const HID_DEVICE device);

_Check_return_
_Ret_range_(FALSE, TRUE)
_Success_(return)
SLAB_HID_DEVICE_API BOOL WINAPI
HidDevice_FlushBuffers(_In_ _Pre_defensive_ const HID_DEVICE device);

_Check_return_
_Ret_range_(FALSE, TRUE)
_Success_(return)
SLAB_HID_DEVICE_API BOOL WINAPI
HidDevice_CancelIo(_In_ _Pre_defensive_ const HID_DEVICE device);

SLAB_HID_DEVICE_API void WINAPI
HidDevice_GetTimeouts(_In_ _Pre_defensive_ const HID_DEVICE device, _Out_writes_bytes_(4) _Pre_defensive_ DWORD* pGetReportTimeoutInMilliSeconds, _Out_writes_bytes_(4) _Pre_defensive_ DWORD* pSetReportTimeoutInMilliSeconds);

SLAB_HID_DEVICE_API void WINAPI
HidDevice_SetTimeouts(_In_ _Pre_defensive_ const HID_DEVICE device, _In_ _Pre_defensive_ const DWORD getReportTimeoutInMilliSeconds, _In_ _Pre_defensive_ const DWORD setReportTimeoutInMilliSeconds);

_Ret_range_(HID_DEVICE_SUCCESS, HID_DEVICE_UNKNOWN_ERROR)
_Success_(HID_DEVICE_SUCCESS == return)
SLAB_HID_DEVICE_API SLAB_HID_DEVICE_STATUS WINAPI
HidDevice_Close(_In_ _Pre_defensive_ const HID_DEVICE device);

#ifdef __cplusplus
}
#endif // __cplusplus


#endif // HOST_LIB_SLABHIDDEVICE_INCLUDE_SLABHIDDEVICE_H_INCLUDED_MJWYLEYUPA