HwDevCommdll开发使用手册

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

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

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

4、的定义为：typedef int (CALLBACK FuncTotalDoneTp)( unsigned long nTotal, unsigned long nDone )。返回值意义0成功-1失败其他保留3 通信协议概述3.1 与考勤机的连接两种方式：串口、Socket。准备：用串口线连接PC机与考勤机或用网线连接PC机与考勤机。建立串口连接：打开PC机串口（考勤机串口默认处于打开状态）。拆除串口连接：关闭PC机串口。建立Socket连接：建立PC机Socket，Connect考勤机（考勤机默认处于Accept状态，在9922端口监听）。拆除Socket连接：关闭PC机Socket。3.

5、2 语法和保留字图3.1本协议的语法结构如图3.1所示，由4类保留字组成，这4类保留字的说明如表3.1所示。保留字名称意义与用途命令字用于指明本次操作究竟要干什么（如：GetEmployeeID 表示获取考勤机上所有员工的员工号）。控制字作为命令字的参数出现，用于指明该参数是什么（如：name 表示该参数是员工姓名）。常量保留字作为命令字的参数出现，一般跟在控制字的后面，用于指示该参数的值是多少。（如：language=chs 表示该考勤机的语言设置为简体中文）。分隔符用于分隔各个保留字。表3.1除分隔符外，其余保留字为 数字字母下划线 的组合，最长32字符，大小写敏感。各保留字间可以插入Sp

6、ace(空格)、Tab(跳格)、CR(回车)，处理忽略不计。3.3 保留字的命名原则保留字名称命名原则命令字Pascal命名法，指用一个或多个连在一起的词来组成名字，每个词都用大写字母开头，其他字母都小写。控制字采用“小写加下划线”的方式，都用小写字母，词之间用“_”分隔。如finger_count。常量保留字采用“小写加下划线”的方式。4 保留字列表及其意义4.1 命令字名称意义员工管理类命令GetEmployeeID从考勤机接收所有员工的员工号。GetEmployee从考勤机接收指定工号员工的员工信息，一次只能接收一个。SetEmployee发送员工到考勤机，一次只能发一个。DeleteE

7、mployee在考勤机上删除指定工号的员工。可一次删除多个员工。DeleteAllEmployee在考勤机上删除所有员工。SetNameTable该命令更新考勤机上的id-姓名对照表，然后更新表中存在的员工姓名。记录管理类命令GetRecord从考勤机接收所指定时间范围的考勤记录。DeleteAllRecord在考勤机上删除所有考勤记录。考勤机管理类命令InitDevice初始化考勤机到出厂状态。InitDeviceAdmin初始化考勤机的管理员设置到出厂状态。GetDeviceInfo读取考勤机配置、状态信息。SetDeviceInfo设置考勤机配置、状态信息。图片管理类命令GetPictu

8、reName根据图像文件的时间和图片是否成功识别得到图像文件名称列表。GetPicture根据图像文件名称获取图像文件。图像文件是以base-64编码的Jpeg格式的照片。结果类命令Return返回值标识。是某个命令执行结果。结构如：Return( result=success / failed Ctrl_Word = Parameter / Value . )Wait等待标识。表示考勤机正在执行命令，需要等待一定的时间（时间由控制字wait_time指定，单位为秒）后才能返回结果，结构如：Wait(wait_time = 10) /该命令表示需要等待10秒钟该命令被用于如下场合：某操作需要时

9、间较长（例如：初始化考勤机），这时等待该操作的一方可通过wait_time了解到需要等待多长时间才能接收到正确的结果。一般来说，如果命令的执行可以在5秒钟内开始返回结果，则不需要使用Wait命令。需要注意的是：本协议的接收数据默认等待时间是5秒。如果一个命令在5秒内没有返回，并且没有用Wait命令指明需要等待的时间，则超时退出。4.2 控制字名称意义对命令执行结果的描述result标示某命令的执行结果，可能的常量值有：名称意义success成功failed失败reason对执行结果的解释信息，可能的常量值有：名称意义unknown command不能识别的命令bad parameter错误的参

10、数device busy设备忙employee overflow对于SetEmployee命令，员工超过最大数unknown id对于DeleteEmployee命令，指定id的员工不存在notify对执行结果的提醒信息，通常是由于命令中有不能识别的参数所致，可能的常量值有：名称意义unknown parameter不能识别的参数注意执行结果必须以result/reason/notify开头，并且必须按result/reason/notify这样的顺序排列。wait_time指明完成某设备操作需要等待的时间，单位为秒公用常量检查方式常量用于定义考勤或开门等控制字的值，可能的常量值为：名称意义f

11、p指纹方式考勤card卡式考勤face人脸识别考勤photo摄像考勤password密码方式考勤逻辑运算常量用于组合多个检查方式常量，可能的常量值为：名称意义&与|或对员工信息的描述id员工号cacu_id根据某些法则计算得到的IDname员工姓名cardcode该员工的员工卡卡号finger_count该员工在考勤机上存储的指纹的数目finger_data指纹数据，值为base-64编码的二进制数据。face_data人脸特征数据，值为base-64编码的二进制数据。privilege该员工的权限，可能的常量值有：名称意义prvg_none无权限prvg_user普通用户prvg_admin

12、普通管理员prvg_adv_admin高级管理员check_type考勤方式，可能的常量值为检查方式常量。可用用逻辑常量并列多个常量表示该员工拥有多个权限。如：check_type=fp & card & face。opendoor_type开门方式，可能的常量值为检查方式常量。可用用逻辑常量并列多个常量表示该员工拥有多个权限。如：opendoor_type=fp | card。permit_photo这是为了兼容V0.1协议保留的，特指考勤方式。是否有摄像权限，可能的常量值有：名称意义true允许false不允许permit_password这是为了兼容V0.1协议保留的，特指考勤方式。是否

13、有密码考勤权限，可能的常量值有：名称意义true允许false不允许password如果有密码考勤权限，则本项对应其密码。对考勤记录信息的描述time考勤记录时间，格式为：yyyy-mm-dd hh:mm:ss。type考勤方式，可能的常量值为检查方式常量。card_type卡点的属性，可能的常量值有：名称意义cardtype_normal一般卡cardtype_on上班cardtype_off下班cardtype_addon加班上班cardtype_addoff加班下班cardtype_out外出cardtype_back回来card_src卡点产生的来源，可能的常量值有：名称意义from_

14、check来自考勤机from_door来自门禁photo对于摄像方式考勤，该控制字后跟的是以base-64编码的Jpeg格式的照片。对考勤机配置信息的描述dev_type考勤设备的类型：名称意义enroll考勤机door门禁time考勤机时间。weektime对应的星期，值为：17 。1：星期日 2：星期一7：星期六。language考勤机语言，可能的常量值有：名称意义chs简体中文cht繁体中文enu美国英语jpn日语kor朝鲜语volume考勤机音量大小，可能的常量值有：名称意义low低mid中high高employee_total现有员工总数。employee_max最大员工数。reco

15、rd_total现有记录总数。record_max最大记录数。finger_algorithm指纹比对所用的算法。finger_captor采集头的标号。soft_version考勤机上软件的版本号。memory_alarm内存警戒百分比，可能的值为 1% 99%。door门禁控制器设置，可能的常量值有：名称意义wiegand26韦根26wiegand34韦根34wiegand27韦根信号W27(汉王标配控制器)op开关信号其他控制信息total总数。通常在有多个返回结果的时候用于标示返回结果的数目。该保留字必须要在他描述的多个返回结果之前出现，否则将被忽略。start_time开始时间，格式

16、为：yyyy-mm-dd hh:mm:ss。end_time结束时间，格式为：yyyy-mm-dd hh:mm:ss。overwrite是否覆盖，可能的常量值有：名称意义true允许false不允许5 命令详解5.1 员工管理类命令命令GetEmployeeID()成功回复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_algor

17、ithm=0.0.1 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 name=李四 finger_count=1 finger_algorithm=0.0.1 finger_captor=1.0.2 finger_data

18、=AGQWERASDFASERQWERAS. permit_photo=false overwrite=true/false)成功回复Return(result=success)。失败回复Return(result=failed reason=employee overflow)。命令DeleteEmployee(id=100)成功回复Return(result=success)。失败回复Return(result=failed reason=unknown id)。命令SetNameTable(120=张三 88=李四 192=王五 1290=赵六 .)成功回复Return(result=s

19、uccess)。失败回复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=success total=100 dev_id=1time=2006-1-10 17:40:06 type=fp id=120 name=张三time=2006-1

20、-10 18:00:10 type=fp id=160 name=李四time=2006-1-10 18:03:28 type=photo id=219 name=王二 photo=SDFQWERASDFAESRASDF.)。失败回复Return(result=failed)。注意没有start_time表示读取end_time之前所有记录；没有end_time表示读取start_time之后所有记录；都没有表示读取全部记录。start_time = 有效时间段 = end_time。接收记录时以控制字time作为分隔每一条记录的标示。命令DeleteAllRecord()成功回复Return(result=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