HwDevComm.dll开发使用手册

1、HwDevComm.dll开发使用手册1 概述HwDevComm.dll 是与所有汉王考勤机（及其他符合汉王考勤机通信协议-HDCP_V0.1.20060120协议（以下简称：通信协议）的考勤设备）进行通信的动态链接库（DYNAMIC LINK LIBRARY，简称DLL），其可以在Win32平台上被调用。2 接口HwDevComm.dll 对外提供了1个接口，描述如下：接口意义HwDev_Execute执行各种命令，如管理类、记录类等。其接口声明如下：Int HwDev_Execute( char * pDevInfoBuf, unsigned long nDevInfoLen, char

2、* pSendBuf, unsigned long nSendLen,char * pRecvBuf, unsigned long * pRecvLen,FuncTotalDoneTp pFuncTotalDone)其接口具体参数、返回值及意义如下：参数意义pDevInfoBuf考勤机信息首指针；存放符合汉王考勤机通信协议-HDCP_V0.1.20060120语法的考勤机信息描述。考勤机信息描述形如：DeviceInfo( dev_id = "1" comm_type = "ip" ip_adress = "172.16.1.15"

3、)nDevInfoLen考勤机信息缓冲区的长度。pSendBuf发送缓冲区首指针；存放符合汉王考勤机通信协议-HDCP_V0.1.20060120语法的命令、参数和数据。建议在缓冲区中一次放入一条命令。如果在该缓冲区中放入了多个命令，将会被顺序执行。如果其中的一个命令执行失败了，将不会影响到之后的命令的执行。nSendLen发送缓冲区的长度。如果 nSendLen=0 则HwDevComm.dll只接收不发送。pRecvBuf接收缓冲区首指针；存放各种命令的执行结果；执行结果的语法符合汉王考勤机通信协议-HDCP_V0.1.20060120；该内存由HwDevComm.dll来申请和释放。pR

4、ecvLen接收缓冲区的长度pFuncTotalDone回调函数指针；用于向调用者反馈执行进度。其中PFuncTotalDoneTp类型的定义为：typedef int (CALLBACK FuncTotalDoneTp)( unsigned long nTotal, unsigned long nDone )。返回值意义0成功-1失败其他保留3 通信协议概述3.1 与考勤机的连接两种方式：串口、Socket。准备：用串口线连接PC机与考勤机或用网线连接PC机与考勤机。建立串口连接：打开PC机串口（考勤机串口默认处于打开状态）。拆除串口连接：关闭PC机串口。建立Socket连接：建立PC机So

5、cket，Connect考勤机（考勤机默认处于Accept状态，在9922端口监听）。拆除Socket连接：关闭PC机Socket。3.2 语法和保留字图3.1本协议的语法结构如图3.1所示，由4类保留字组成，这4类保留字的说明如表3.1所示。保留字名称意义与用途命令字用于指明本次操作究竟要干什么（如：GetEmployeeID 表示获取考勤机上所有员工的员工号）。控制字作为命令字的参数出现，用于指明该参数是什么（如：name 表示该参数是员工姓名）。常量保留字作为命令字的参数出现，一般跟在控制字的后面，用于指示该参数的值是多少。（如：language="chs" 表示该考

6、勤机的语言设置为简体中文）。分隔符用于分隔各个保留字。表3.1除分隔符外，其余保留字为 数字字母下划线 的组合，最长32字符，大小写敏感。各保留字间可以插入Space(空格)、Tab(跳格)、CR(回车)，处理忽略不计。3.3 保留字的命名原则保留字名称命名原则命令字Pascal命名法，指用一个或多个连在一起的词来组成名字，每个词都用大写字母开头，其他字母都小写。控制字采用“小写加下划线”的方式，都用小写字母，词之间用“_”分隔。如finger_count。常量保留字采用“小写加下划线”的方式。4 保留字列表及其意义4.1 命令字名称意义员工管理类命令GetEmployeeID从考勤机接收所有

7、员工的员工号。GetEmployee从考勤机接收指定工号员工的员工信息，一次只能接收一个。SetEmployee发送员工到考勤机，一次只能发一个。DeleteEmployee在考勤机上删除指定工号的员工。可一次删除多个员工。DeleteAllEmployee在考勤机上删除所有员工。SetNameTable该命令更新考勤机上的"id-姓名"对照表，然后更新表中存在的员工姓名。记录管理类命令GetRecord从考勤机接收所指定时间范围的考勤记录。DeleteAllRecord在考勤机上删除所有考勤记录。考勤机管理类命令InitDevice初始化考勤机到出厂状态。InitDevi

8、ceAdmin初始化考勤机的管理员设置到出厂状态。GetDeviceInfo读取考勤机配置、状态信息。SetDeviceInfo设置考勤机配置、状态信息。图片管理类命令GetPictureName根据图像文件的时间和图片是否成功识别得到图像文件名称列表。GetPicture根据图像文件名称获取图像文件。图像文件是以base-64编码的Jpeg格式的照片。结果类命令Return返回值标识。是某个命令执行结果。结构如：Return( result="success / failed" Ctrl_Word = "Parameter / Value" . )Wa

9、it等待标识。表示考勤机正在执行命令，需要等待一定的时间（时间由控制字wait_time指定，单位为秒）后才能返回结果，结构如：Wait(wait_time = "10") /该命令表示需要等待10秒钟该命令被用于如下场合：某操作需要时间较长（例如：初始化考勤机），这时等待该操作的一方可通过wait_time了解到需要等待多长时间才能接收到正确的结果。一般来说，如果命令的执行可以在5秒钟内开始返回结果，则不需要使用Wait命令。需要注意的是：本协议的接收数据默认等待时间是5秒。如果一个命令在5秒内没有返回，并且没有用Wait命令指明需要等待的时间，则超时退出。4.2 控制字

10、名称意义对命令执行结果的描述result标示某命令的执行结果，可能的常量值有：名称意义success成功failed失败reason对执行结果的解释信息，可能的常量值有：名称意义unknown command不能识别的命令bad parameter错误的参数device busy设备忙employee overflow对于SetEmployee命令，员工超过最大数unknown id对于DeleteEmployee命令，指定id的员工不存在notify对执行结果的提醒信息，通常是由于命令中有不能识别的参数所致，可能的常量值有：名称意义unknown parameter不能识别的参数注意执行结果

11、必须以result/reason/notify开头，并且必须按result/reason/notify这样的顺序排列。wait_time指明完成某设备操作需要等待的时间，单位为秒公用常量检查方式常量用于定义考勤或开门等控制字的值，可能的常量值为：名称意义fp指纹方式考勤card卡式考勤face人脸识别考勤photo摄像考勤password密码方式考勤逻辑运算常量用于组合多个检查方式常量，可能的常量值为：名称意义&与|或对员工信息的描述id员工号cacu_id根据某些法则计算得到的IDname员工姓名cardcode该员工的员工卡卡号finger_count该员工在考勤机上存储的指纹的数

12、目finger_data指纹数据，值为base-64编码的二进制数据。face_data人脸特征数据，值为base-64编码的二进制数据。privilege该员工的权限，可能的常量值有：名称意义prvg_none无权限prvg_user普通用户prvg_admin普通管理员prvg_adv_admin高级管理员check_type考勤方式，可能的常量值为检查方式常量。可用用逻辑常量并列多个常量表示该员工拥有多个权限。如：check_type="fp & card & face"。opendoor_type开门方式，可能的常量值为检查方式常量。可用用逻辑常量并

13、列多个常量表示该员工拥有多个权限。如：opendoor_type="fp | card"。permit_photo这是为了兼容V0.1协议保留的，特指考勤方式。是否有摄像权限，可能的常量值有：名称意义true允许false不允许permit_password这是为了兼容V0.1协议保留的，特指考勤方式。是否有密码考勤权限，可能的常量值有：名称意义true允许false不允许password如果有密码考勤权限，则本项对应其密码。对考勤记录信息的描述time考勤记录时间，格式为：yyyy-mm-dd hh:mm:ss。type考勤方式，可能的常量值为检查方式常量。card_ty

14、pe卡点的属性，可能的常量值有：名称意义cardtype_normal一般卡cardtype_on上班cardtype_off下班cardtype_addon加班上班cardtype_addoff加班下班cardtype_out外出cardtype_back回来card_src卡点产生的来源，可能的常量值有：名称意义from_check来自考勤机from_door来自门禁photo对于摄像方式考勤，该控制字后跟的是以base-64编码的Jpeg格式的照片。对考勤机配置信息的描述dev_type考勤设备的类型：名称意义enroll考勤机door门禁time考勤机时间。weektime对应的星期，

15、值为：17 。1：星期日 2：星期一7：星期六。language考勤机语言，可能的常量值有：名称意义chs简体中文cht繁体中文enu美国英语jpn日语kor朝鲜语volume考勤机音量大小，可能的常量值有：名称意义low低mid中high高employee_total现有员工总数。employee_max最大员工数。record_total现有记录总数。record_max最大记录数。finger_algorithm指纹比对所用的算法。finger_captor采集头的标号。soft_version考勤机上软件的版本号。memory_alarm内存警戒百分比，可能的值为 1% 99%。doo

16、r门禁控制器设置，可能的常量值有：名称意义wiegand26韦根26wiegand34韦根34wiegand27韦根信号W27(汉王标配控制器)op开关信号其他控制信息total总数。通常在有多个返回结果的时候用于标示返回结果的数目。该保留字必须要在他描述的多个返回结果之前出现，否则将被忽略。start_time开始时间，格式为：yyyy-mm-dd hh:mm:ss。end_time结束时间，格式为：yyyy-mm-dd hh:mm:ss。overwrite是否覆盖，可能的常量值有：名称意义true允许false不允许5 命令详解5.1 员工管理类命令命令GetEmployeeID()成功回

17、复Return(result="success" total="100" id="11" id="109" .)。失败回复Return(result="failed")。命令GetEmployee(id="120")成功回复Return(result="success" id="120" name="张三" finger_count="2" finger_algorithm="0.0.1

18、" finger_captor="0.0.3" finger_data="ADFASERQERERTYSDFGHSDFGADSF." finger_data="HASRTTYHRTAEFASDFQEQAFf."(base-64 encode) permit_photo="true")。失败回复Return(result="failed" reason="unknown id")。注意一次只能获取一个id。命令SetEmployee(id="1009&quo

19、t; name="李四" finger_count="1" finger_algorithm="0.0.1" finger_captor="1.0.2" finger_data="AGQWERASDFASERQWERAS." permit_photo="false" overwrite="true/false")成功回复Return(result="success")。失败回复Return(result="failed&quo

20、t; reason="employee overflow")。命令DeleteEmployee(id="100")成功回复Return(result="success")。失败回复Return(result="failed" reason="unknown id")。命令SetNameTable(120="张三" 88="李四" 192="王五" 1290="赵六" .)成功回复Return(result="

21、;success")。失败回复Return(result="failed")。注意该命令更新"id-姓名"对照表，然后更新表中存在的员工姓名。对照表以覆盖方式更新，若只想修改个别员工姓名，请用SetEmployee(id="1009" name="李四")命令。5.2 记录管理类命令命令GetRecord(start_time="2005-11-1 0:0:0" end_time="2005-11-30 24:00:00")成功回复Return(result=&qu

22、ot;success" total="100" dev_id="1"time="2006-1-10 17:40:06" type="fp" id="120" name="张三"time="2006-1-10 18:00:10" type="fp" id="160" name="李四"time="2006-1-10 18:03:28" type="photo&

23、quot; id="219" name="王二 "photo="SDFQWERASDFAESRASDF.")。失败回复Return(result="failed")。注意没有start_time表示读取end_time之前所有记录；没有end_time表示读取start_time之后所有记录；都没有表示读取全部记录。start_time <= 有效时间段 <= end_time。接收记录时以控制字time作为分隔每一条记录的标示。命令DeleteAllRecord()成功回复Return(result=

24、"success")。失败回复Return(result="failed")。5.3 考勤机管理类命令命令InitDevice()成功回复Return(result="success")。失败回复Return(result="failed")。命令InitDeviceAdmin()成功回复Return(result="success")。失败回复Return(result="failed")。命令SetDeviceInfo(time="2006-1-16 12:39:40" memory_alarm="90%" language="chs" volume="low/mid/high")成功回复Return(result="success")。失败回复Return(result="failed")。命令GetDeviceInfo()成功回复Return(result="success" dev_id="1"time="2006-1