Tipro API
Communicate with Tipro devices
TiproHidApi_Info.h
1 /****************************************************************************/
2 /* */
3 /* Tipro Hid API */
4 /* */
5 /* V 2.0.2.0. */
6 /* */
7 /****************************************************************************/
8 /* */
9 /* The HID API provides for communication with a Tipro USB controller via */
10 /* standard HID interface. It is a single DLL (Dynamic Link Library) file */
11 /* which doesn't require any additional drivers (besides Microsoft standard */
12 /* HID drivers) or interfaces for the operation. This approach simplifies */
13 /* the software development and results in a faster communication with */
14 /* lower requirements on engaged computer resources. */
15 /* */
16 /* Notes: */
17 /* */
18 /* Precondition to use the HID API is the respective support in the */
19 /* firmware of the controller. Currently only Atom-based BeFREE with */
20 /* firmware version 05.0E.31 or later/higher implements this feature. */
21 /* A special software utility is provided for the upgrade of the previous */
22 /* firmware version 05.0E.2F. This upgrade only supports FW Level 1 */
23 /* communication. */
24 /* */
25 /* Notes (02.04.2012): */
26 /* */
27 /* A special software utility is provided for the upgrade of the previous */
28 /* firmware version 05.0E.2F. This upgrade now also supports limited */
29 /* FW Level 2 communication. Later/higer firmware versions will also */
30 /* support FW Level 3 communication, intended for fast firmware update. */
31 /* */
32 /****************************************************************************/
33 /* HISTORY: */
34 /* */
35 /* V 2.0.2.0 - Release on 07.06.2019 */
36 /* */
37 /* V 2.0.1.17 - BF07 implementation */
38 /* - Finished on 04.06.2019 */
39 /* - preparing for release 2.0.2.0 */
40 /* */
41 /* V 2.0.1.16 - Start of BF07 implementation */
42 /* - WIN10_GUID_FIX added to solve problem with latest */
43 /* windows 10 update. Bug#149 */
44 /* - new ID support added Task#150 */
45 /* */
46 /* V 2.0.1.15. - SpeakerBox104 (ONUR) implementation */
47 /* */
48 /* V 2.0.1.14. - changes made by Tomaž / search "tomaz201711" */
49 /* - BF22 implementation */
50 /* */
51 /* V 2.0.1.13. - changes made by Tomaž / search "tomaz20170512" */
52 /* - added new IDs for BeFREE 10 version 2 */
53 /* */
54 /* V 2.0.1.12. - changes made by Tomaž / search "tomaz20170511" */
55 /* - added HIDBF20GetPTTKeyState */
56 /* */
57 /* V 2.0.1.11. - changes made by Tomaž / search "tomaz20170411" */
58 /* - added logging to tiprohidapi.log for all functions that */
59 /* are exported */
60 /* */
61 /* V 2.0.1.10. - changes made by Tomaž / search "tomaz20170404" */
62 /* - switching between more controllers improved: */
63 /* - array of detected devices */
64 /* - changed functions: DetectTiproDevice, HIDSelectDeviceEx */
65 /* - new function SelectTiproDevice */
66 /* */
67 /* V 2.0.1.9. - tasks checked, documented and done (112,114,115,116,120) */
68 /* - no major changes from previous version */
69 /* - starting point for further development */
70 /* */
71 /* V 2.0.1.8. - BF20 impementation by Tomaž / search "tomaz2016" */
72 /* - TODO: make documentation */
73 /* - TODO: check tasks and finish them with the next release */
74 /* */
75 /* V 2.0.1.5. - Task#118 and Task#119: */
76 /* - function HIDBF10EnableManualMicrophoneControl added */
77 /* */
78 /* V 2.0.1.4. - Task#109 in progress... */
79 /* */
80 /* V 2.0.1.3. - Task#107: */
81 /* - All projects prepared for x64 build (TFS_Release/x64) */
82 /* - PostBuild script prepared for MultiPlatform deployment */
83 /* - Multiplatform build definition created and tested */
84 /* - Task#108: */
85 /* - Configurations cleaned/deleted */
86 /* */
87 /* V 2.0.1.2. - All projects converted to Unicode (WCHAR), task#106 */
88 /* */
89 /* V 2.0.1.1. - Solution moved to Win10/VS2015 */
90 /* - >Branching/Merging from V2.0.0.22 */
91 /* */
92 /* V 2.0.0.21. - New handset support added Taks#92 (16.09.2015) */
93 /* - Future development moving to Win10/VS2015 */
94 /* - >Branching/Merging to V 2.0.1.xx */
95 /* */
96 /* V 2.0.0.19. - Bug#104 Solved - Refere to Bug104 comments (23.03.2015) */
97 /* */
98 /* V 2.0.0.17. - HIDGetModuleVersionEx added (09.01.2015) */
99 /* */
100 /* V 2.0.0.15. - Relese for ChangeMe 5.19.0 CD (16.10.2014) */
101 /* - Lots of changes regarding the telephony devices */
102 /* - constructors/destructors issues solved */
103 /* - non-existant handles closing issue solved */
104 /* - other optimizations regarding the detection of the */
105 /* telephony devices */
106 /* (one function redundant, no more unnecesary temp objects) */
107 /* - 2 changesets made as first one didn't have bug#101 properly added */
108 /* */
109 /* V 2.0.0.9. - Demo relese for Trans-Data */
110 /* */
111 /* - New (updated) functions: */
112 /* HIDSetSbxLEDBlinkSpeed */
113 /* HIDSetSbxLEDState (SBX_LED_BLINK, SBX_LED_BLINK_INV) */
114 /* HIDGetModuleVersion */
115 /* */
116 /* V 2.0.0.4. - Prepared for Trans-Data Release */
117 /* */
118 /* - New (updated) functions: */
119 /* HIDRegisterTelephonyKeysCallback */
120 /* HIDRegisterTelephonyKeysCallbackEx */
121 /* HIDGetNumOfDetectedTelephonyDevices */
122 /* HIDGetTelephonyDeviceProductDescriptor */
123 /* */
124 /* */
125 /* V 2.0.0.2. - Merged with version 1.9.9.25 */
126 /* */
127 /* - Under development */
128 /* */
129 /* V 1.9.9.25. - Preparing for merge latest development to version 2.0 */
130 /* */
131 /* V 1.9.9.24. - Test of BF10 module commands */
132 /* */
133 /* - Prepared for release */
134 /* */
135 /* */
136 /* V 1.9.9.23. - Sent to transdata for testing */
137 /* */
138 /* - Solving Bug#11 (part 2) */
139 /* */
140 /* */
141 /* V 1.9.9.22. - Test of Chameleon module commands */
142 /* */
143 /* - Task#17 done */
144 /* */
145 /* V 1.9.9.21. - Sent to transdata for testing */
146 /* */
147 /* - Solving Bug#9 (reported by transdata) */
148 /* - Solving Bug#38 (found during debugging) */
149 /* */
150 /* V 1.9.9.20. - branching from version 2.0.0.0. */
151 /* */
152 /* V 1.9.9.18. - beta 9 version (*) */
153 /* */
154 /* - Beta Implementation of BF104 commands */
155 /* - Beta Implementation of Chameleon module */
156 /* */
157 /* V 1.9.9.17. - beta 8 version (*) */
158 /* */
159 /* - Added GetHandsetSatusEx without SendHandsetStatusToSystem */
160 /* function; solves the problem with excpetions */
161 /* - HIDEnumerateModules() returns error if modules are not enumerated */
162 /* properly. Should be improved in the next version */
163 /* */
164 /* V 1.9.9.15. - beta 7 version (*) */
165 /* */
166 /* - Test only / removed SendHandsetStatusToSystem function */
167 /* solves the problem with excpetions... to be solved in v.16 */
168 /* */
169 /* V 1.9.9.14. - beta 6 version (*) */
170 /* */
171 /* - BugFix (Exception error @ SendCommandEx */
172 /* delete[] pTempResponseData called without init of array */
173 /* */
174 /* V 1.9.9.13. - beta 5 version (*) */
175 /* */
176 /* - OnLine functions added for the SpeakerBox */
177 /* HIDSpeakerboxGoOnline */
178 /* HIDIsSpeakerboxOnline */
179 /* HIDGetAlertLine */
180 /* HIDSetAlertLine */
181 /* HIDSetActiveDevice */
182 /* */
183 /* V 1.9.9.12. - beta 4 version (*) */
184 /* */
185 /* - MuteMicrophone function added for the SpeakerBox */
186 /* */
187 /* V 1.9.9.11. - beta 3 version (*) */
188 /* */
189 /* - memory leaks located and removed */
190 /* - asignment and copy constructors written for CHid to solve */
191 /* the problem with malloc and free functions */
192 /* */
193 /* V 1.9.9.10. - beta 2 version (*) */
194 /* */
195 /* - support for different handset types (IDs) added */
196 /* */
197 /* */
198 /* V 1.9.9.9. - beta version (*) */
199 /* */
200 /* - support for FW-Level 2 bi-directional communication added */
201 /* - implementation of the TiproBus class for enumerating the modules */
202 /* present on the TiproBus. Currently only "dispatching" modules */
203 /* and matrix modules are recognized */
204 /* - start of implementation of limited number of API commands for */
205 /* "dispatching" modules. */
206 /* - beta implementaion of FW-Level 3 communication (not finished yet) */
207 /* will not be available in v 2.0.0.0. release */
208 /* - beta implementaion of string descriptors (not finished yet) */
209 /* refer to _VER_STR_DESCRIPTORS */
210 /* - beta implementaion of multiple controllers support */
211 /* (not finished yet) refer to _VER_MULTIPLE_CONTROLLERS */
212 /* - beta implementaion of possibility to detect additional interfaces */
213 /* (not finished yet) refer to _VER_ADDITIONAL_INTERFACES */
214 /* - bug found and eliminated at (FindHIDByVID), coping between */
215 /* different classes not reported as error in compiler */
216 /* */
217 /* */
218 /* V 1.0.0.0. (released 06.02.2012) */
219 /* */
220 /* - second release version made as a new project (due to renaming */
221 /* the DLL to TiproHidApi) */
222 /* - error codes properly defined in ErrCodes.h, and used in all */
223 /* exported functions. */
224 /* - version control added to the project */
225 /* - history/to-do/scenarious/fixes file added */
226 /* - DetectTiproDevice function called at DLL_PROCESS_ATTACH */
227 /* - global variables g_hidTiproDevice and g_nNumOfDetectedDevices */
228 /* added to reduce the time needed for execution of commands */
229 /* - SendCommandToConnectedDevice function written to simplify */
230 /* cheking and connecting to a HID device. All exported functions */
231 /* now call the same function. */
232 /* - Internal functions now in sepparate .cpp file */
233 /* - Global variables now in sepparate .h file */
234 /* - HIDDetectDevices function added */
235 /* */
236 /* */
237 /****************************************************************************/
238 /* TODO: */
239 /* */
240 /* * (DONE 06.02.2012 @ V 1.0.0.0.) */
241 /* -> add version control and history/to-do/scenarious/fixes file */
242 /* * (DONE 06.02.2012 @ V 1.0.0.0.) */
243 /* -> add sepparate .cpp file for Internal/Support/not-exported */
244 /* functions */
245 /* * (DONE 06.02.2012 @ V 1.0.0.0.) */
246 /* -> define error codes and use it properly */
247 /* - multiple controllers with HID API support connected to the same PC */
248 /* - at attach store array of possible devices */
249 /* - at each function, paramter should somehow define to which */
250 /* controller the command should be directed to */
251 /* - think about how to destinguish different controllers */
252 /* * (DONE 12.03.2012 @ V 1.9.9.9.) */
253 /* -> support for FW-level 2 bi-directional communication */
254 /* -> commands that can work in both levels should run in the highest */
255 /* possible level */
256 /* - support for FW-level 3 communication (fast FW-Update) */
257 /* * (DONE 02.04.2012 @ V 1.9.9.9.) */
258 /* -> check all files in project and add comments/headers... */
259 /* - check that all returned error codes have corrct meaning */
260 /* mark possible contradictions with API_ERR_??? */
261 /* mark solved ones with toAPI_ERR */
262 /* 28.03.2012 -> checked for IntFn */
263 /* - Implement Get versions of commands for BeFree module commands */
264 /* - GetLuminance */
265 /* - GetTouchscreenState */
266 /* - GetBeFreeUserLEDs */
267 /* */
268 /****************************************************************************/
269 /* Different scenarios / fixes */
270 /****************************************************************************/
271 // template, how to define different fixes, scenarios, builds
272 // #define _FIX_TEMPLATE_
273 //
274 
275 // Multiple controllers connected to the same PC (beta, test)
276 #define _VER_MULTIPLE_CONTROLLERS
277 
278 // Support for additional interfaces (Telephony/Joystick...)
279 #define _VER_ADDITIONAL_INTERFACES
280 
281 // Bug#104
282 // DataKrat issue with resets when sending LED commands over TBS and pressing keys at the same time
283 // Issue was solved with this temporary fix that prevents checking of the FWLevel before each command
284 // and putting extra delay on strategic places. Delay was checked with the USB analyzer to
285 // mimimize the chance that you will get previous signature and repeat GetReport command.
286 // Version .18 was sent DataKrat customer for evaluation and confirmed. After testing version .19 will
287 // be released specialy for DataKrat and stored in source controll with this comment.
288 // Add 23.02.2015: PreDealy and PostDelay defined at this spot for testing. Version sent to Datakrat
289 // customer had delays set to 80ms/20ms this produces aproximately 14% slower communication.
290 // Further testing showed that the alternative settings could be 60ms/20ms
291 // which produces approximately 5% slower communication.
292 #define _DATAKRAT_TEMP_FIX_
293 #ifdef _DATAKRAT_TEMP_FIX_
294  /* original values sent to Datakrat */
295  #define _DATAKRAT_TEMP_FIX_PRE_DELAY_MS 80
296  #define _DATAKRAT_TEMP_FIX_POST_DELAY_MS 20
297  /* alternative settings (tested 23.02.2015)
298  #define _DATAKRAT_TEMP_FIX_PRE_DELAY_MS 60
299  #define _DATAKRAT_TEMP_FIX_POST_DELAY_MS 20
300  */
301 #endif
302 
303 // Bug#104
304 // SetFeature report is automaticaly repetead if failed (this happens rarely, but can fix strange errors)
305 // NOTE: This fix was not defined in version sent to datakrat, but can only have positive effect
306 // NOTE: Additional 20ms delay was added in the release version to prevent any surprises (tested on 23.02.2015).
307 #define _SET_FEATURE_REPORT_RAW_REPEAT_FAILED
Generated by   doxygen 1.8.13