原创 串口控件HotComm使用说明(草稿未完)

             串口控件HotComm使用说明(草稿未完)
                                               雁塔菜农 HotPower 2007.6.29 于菜地
    HotComm采用Windows API多线程编程，它综合了各种串口控件的优点，且与VB的MSCOMM控件十分接近。
这主要考虑了众多MSCOMM控件的使用者和他们的习惯。尽量做到属性的一致性和兼容性。

HotComm有自己非常明显的特点：
   基于安装用户事件的回调函数和配置运行参数的编程方法。这也是使用HotComm的重点和关键。

它的优点在于用户可随时安装或卸载自己某个或全部的事件回调函数，而主事件回调函数不受任何影响和变动。从而做到
了对用户有无回调函数的自适应。这也符合当今控件的潮流和趋势。

由于HotComm当前已提供了144个函数之多，随着版本的完善将会更加丰富。编写串口不需写代码的愿望基本实现。
HotComm目前处于测试和试用阶段。本说明也将会逐步完善。
虽然函数众多，但CVI完美的函数面板可以使用户最快捷地找到并在需要的地方添加需要的函数。而函数不需要人工输入。
在这个方面，CVI作得非常完美。

一.主事件回调函数的安装
    主事件回调函数类似MSCOMM的OnComm()事件函数，它本身也必须由自己的安装函数HotComm_InstallOnCommCallback()
来安装。若不安装主事件回调函数，则子事件回调函数必须各自安装，即如SPCOMM等控件的"分立"回调格式。

    虽然安装好主事件回调函数不需再安装子事件回调函数，只需输入事件代码即可，但推荐安装子事件回调函数，因为
在子事件回调函数安装时，可能需要一些特殊的参数设置。而且可以随意安装或卸载子事件回调函数。这样可把精力集中
在子事件回调函数的具体事件过程的处理，不同的处理可链接不同的子事件回调函数，主模块框架可保证不变。
   
HotComm专门提供了主事件回调函数模板HotComm_OnCommCallback()。模板代码如下:
void CVICALLBACK HotComm_OnCommCallback (unsigned int CommPort)
{
 unsigned int comEvent;
 comEvent = HotComm_GetCommEvent (CommPort);
 switch (comEvent)
 {
  case comEvReceive://同扩展VB的comEvReceive事件
   HotComm_ReceiveCallback (CommPort);//已被安装的回调函数
   break;
  case comEvReceiveError://扩展VB事件
   HotComm_ReceiveErrorCallback (CommPort);//例如可以捕捉GPS格式错误时的具体字符串
   break;
  case comEvSendEmpty://类似VB的comEvSend,当SThreshold 属性为1时.HotComm不支持SThreshold 属性
   HotComm_SendEmptyCallback (CommPort);
   break;
  case comEvSendError://扩展VB事件
   HotComm_SendErrorCallback (CommPort);
   break;
  case comEvPortOpenError://打开串口时的错误事件
   HotComm_PortOpenErrorCallback (CommPort);
   break;
  case comEvModemStateChange://是VB事件comEvCTS,DSR,comEvRing和comEvCD的集合
                                           //因为comEvModenStateChange可能是并发的事件
   //在HotComm_ModemStateChangeCallback()可以用
   //modemEvent = HotComm_GetModemEvent (CommPort);//找出comEvCTS等具体事件
   HotComm_ModemStateChangeCallback (CommPort);
   break;
 }
}

用户若采用HotComm提供的主事件回调函数模板HotComm_OnCommCallback(), 只需如下安装代码:
    HotComm_InstallOnCommCallback (CommPort, NULL);//主回调函数由HotComm自动提供。

若要安装自己的主回调函数(最好复制模板后再改写)，可以这样安装:
    HotComm_InstallOnCommCallback (CommPort, OnComm);//自己提供回调函数OnComm()。
   
二.子事件回调函数的安装
   由于在主事件回调函数中采用了switch分枝结构，子事件回调函数都在各自的case语句后执行。
每个事件命名为HotComm_+子事件+Callback, 参数CommPort为某个将要或正在工作的串口号，从1开始. 0为系统专用。
这里请不要写具体的串口号, 因为HotComm支持多串口，它会根据不同的串口正确地执行某个具体的串口任务。
当CommPort设置为0时，表示所有的串口都执行一种动作。它的实际号将和打开串口的号相符。

1. 接收事件回调函数的安装
   接收事件回调函数HotComm_ReceiveCallback()由comEvReceive事件触发，但比MSCOMM等串口控件的功能都更为强大。
它本身与一般的回调函数没任何区别，主要是用HotComm_Input()或HotComm_InputBuffer()函数取出接收缓冲区中的数据。
其中HotComm_Input()取出的是接收缓冲区中数据的备份，取出后自动清除接收缓冲区中的数据，以便HotComm继续送数据。
而HotComm_InputBuffer()是直读方式，不需要用户自己申请字符缓冲区，但必须在接收事件回调函数退出前发送清除接收
缓冲区命令HotComm_ClearInBufferCount()后, HotComm方可继续送数据，否则用户将永远再收不到任何数据，直到再次
接收到HotComm_ClearInBufferCount()命令后才能继续送数据。
   安装接收事件回调函数：
HRESULT CVIFUNC HotComm_InstallReceiveCallback (unsigned int CommPort, int StartCharacter,
                                         int StopCharacter, unsigned int InputLen,
                                         HotCommCallbackPtr ReceiveCallbackPtr);
入口参数：
CommPort:              串口号(1~ HotComm_MaxCount).HotComm_MaxCount可以自己设置.HotComm默认为10。

StartCharacter:        同步起始字符。-1.无效。0x00~0xff合法起始字符。它必须与事件终止字符配对。
                       它主要功能是在数据流中找同步字符，在同步字符前的其他字符都认为是非法字符，都将被放弃。

StopCharacter:         事件终止字符。-1.无效。0x00~0xff合法终止字符。它可以不与同步起始字符配对。
                       当找到终止字符时。将立即触发用户接收事件而不管其固定长度InputLen的大小(<=InputLen).
                       若有同步起始字符配对时，可再安装HotComm支持的数据格式检查回调函数(如常用的GPS数据格式等)
                       或安装自己的格式检查回调函数(可不与同步起始字符配对)。若错误时也可再安装格式错误回调函数。

InputLen:              该参数与MSCOMM的InputLen不同。它不能默认为0!!!
                       它表示实际需要接收字符的最小长度.（即非格式化数据时的固定长度）。
                       InputLen="0时",HotComm将默认系统给出的64个字节的长度。

ReceiveCallbackPtr:    被安装的串口接收事件回调函数。以用以接收事件的及时处理，可想象为中断处理。
                       格式void CVICALLBACK HotCommReceiveCallback (unsigned int CommPort);

注意: StartCharacter等参数也可单独设置。这里主要考虑主回调不安装子回调的情况。

2. Modem状态变化事件回调函数的安装
HRESULT CVIFUNC HotComm_InstallModemStateChangeCallback (unsigned int CommPort,
                                                      HotCommCallbackPtr ModemStateChangeCallbackPtr,
                                                      DWORD ModemEventMask);
入口参数：
CommPort:              串口号(1~ HotComm_MaxCount).HotComm_MaxCount可以自己设置.HotComm默认为10。
ModemEventMask:        需要捕捉具体某些引脚上的电平变化。
                       例如: EV_RLSD. EV_RLSD | EV_CTS.等
ModemStateChangeCallbackPtr:
                       被安装的Modem状态变化事件回调函数。

   Modem状态变化事件回调函数HotComm_ModemStateChangeCallback()由comEvModemStateChange事件触发.
它与MSCOMM最大的不同在于它是comEvCTS,DSR,comEvRing和comEvCD等事件的集合。因为在实际应用中它们可能是并发的事件。
如果再事件细分，可在HotComm_ModemStateChangeCallback()内用HotComm_GetModemEvent (CommPort)得到具体的事件。
注意不要用switch()语句，否则case后的其他事件会丢失，应该用if()逐一找出具体的事件并做相应的处理。

注意：如果感觉本回调函数速度达不到要求时，可安装挂钩回调函数HotComm_ModemStateChangeHookCallback().
特别注意：挂钩回调函数是钩挂在HotComm的线程里面，所以代码必须十分简洁！！！

未完待续