HwDevCommdll开发使用手册

-1-HwDevComm.dll开发使用手册1概述HwDevComm.dll是与所有汉王考勤机（及其他符合《汉王考勤机通信协议-HDCP_V0.1.20060120》协议（以下简称：通信协议）的考勤设备）进行通信的动态链接库（DYNAMICLINKLIBRARY，简称DLL），其可以在Win32平台上被调用。2接口HwDevComm.dll对外提供了1个接口，描述如下：接口意义HwDev_Execute执行各种命令，如管理类、记录类等。其接口声明如下：IntHwDev_Execute(char*pDevInfoBuf,unsignedlongnDevInfoLen,char*pSendBuf,unsignedlongnSendLen,char**pRecvBuf,unsignedlong*pRecvLen,FuncTotalDoneTppFuncTotalDone)其接口具体参数、返回值及意义如下：参数意义pDevInfoBuf考勤机信息首指针；存放符合《汉王考勤机通信协议-HDCP_V0.1.20060120》语法的考勤机信息描述。考勤机信息描述形如：DeviceInfo(dev_id=1comm_type=ipip_adress=172.16.1.15)nDevInfoLen考勤机信息缓冲区的长度。pSendBuf发送缓冲区首指针；存放符合《汉王考勤机通信协议-HDCP_V0.1.20060120》语法的命令、参数和数据。建议在缓冲区中一次放入一条命令。如果在该缓冲区中放入了多个命令，将会被顺序执行。如果其中的一个命令执行失败了，将不会影响到之后的命令的执行。nSendLen发送缓冲区的长度。如果nSendLen=0则HwDevComm.dll只接收不发送。-2-pRecvBuf接收缓冲区首指针；存放各种命令的执行结果；执行结果的语法符合《汉王考勤机通信协议-HDCP_V0.1.20060120》；该内存由HwDevComm.dll来申请和释放。pRecvLen接收缓冲区的长度pFuncTotalDone回调函数指针；用于向调用者反馈执行进度。其中PFuncTotalDoneTp类型的定义为：typedefint(CALLBACKFuncTotalDoneTp)(unsignedlongnTotal,unsignedlongnDone)。返回值意义0成功-1失败其他保留3通信协议概述3.1与考勤机的连接两种方式：串口、Socket。准备：用串口线连接PC机与考勤机或用网线连接PC机与考勤机。建立串口连接：打开PC机串口（考勤机串口默认处于打开状态）。拆除串口连接：关闭PC机串口。建立Socket连接：建立PC机Socket，Connect考勤机（考勤机默认处于Accept状态，在9922端口监听）。拆除Socket连接：关闭PC机Socket。3.2语法和保留字Command_Word([Ctrl_Word1=Parameter/Value][Ctrl_Word2=Parameter/Value]...)命令字分隔符控制字控制字参数/常量保留字/其他变量图3.1本协议的语法结构如图3.1所示，由4类保留字组成，这4类保留字的说明如表3.1所示。-3-保留字名称意义与用途命令字用于指明本次操作究竟要干什么（如：GetEmployeeID表示获取考勤机上所有员工的员工号）。控制字作为命令字的参数出现，用于指明该参数是什么（如：name表示该参数是员工姓名）。常量保留字作为命令字的参数出现，一般跟在控制字的后面，用于指示该参数的值是多少。（如：language=chs表示该考勤机的语言设置为简体中文）。分隔符用于分隔各个保留字。表3.1除分隔符外，其余保留字为数字字母下划线的组合，最长32字符，大小写敏感。各保留字间可以插入Space(空格)、Tab(跳格)、CR(回车)，处理忽略不计。3.3保留字的命名原则保留字名称命名原则命令字Pascal命名法，指用一个或多个连在一起的词来组成名字，每个词都用大写字母开头，其他字母都小写。控制字采用“小写加下划线”的方式，都用小写字母，词之间用“_”分隔。如finger_count。常量保留字采用“小写加下划线”的方式。4保留字列表及其意义4.1命令字名称意义员工管理类命令GetEmployeeID从考勤机接收所有员工的员工号。GetEmployee从考勤机接收指定工号员工的员工信息，一次只能接收一个。SetEmployee发送员工到考勤机，一次只能发一个。DeleteEmployee在考勤机上删除指定工号的员工。可一次删除多个员工。DeleteAllEmployee在考勤机上删除所有员工。SetNameTable该命令更新考勤机上的id-姓名对照表，然后更新表中存在的员工姓名。-4-记录管理类命令GetRecord从考勤机接收所指定时间范围的考勤记录。DeleteAllRecord在考勤机上删除所有考勤记录。考勤机管理类命令InitDevice初始化考勤机到出厂状态。InitDeviceAdmin初始化考勤机的管理员设置到出厂状态。GetDeviceInfo读取考勤机配置、状态信息。SetDeviceInfo设置考勤机配置、状态信息。图片管理类命令GetPictureName根据图像文件的时间和图片是否成功识别得到图像文件名称列表。GetPicture根据图像文件名称获取图像文件。图像文件是以base-64编码的Jpeg格式的照片。结果类命令Return返回值标识。是某个命令执行结果。结构如：Return(result=success/failed[Ctrl_Word=Parameter/Value]...)Wait等待标识。表示考勤机正在执行命令，需要等待一定的时间（时间由控制字wait_time指定，单位为秒）后才能返回结果，结构如：Wait(wait_time=10)//该命令表示需要等待10秒钟该命令被用于如下场合：某操作需要时间较长（例如：初始化考勤机），这时等待该操作的一方可通过wait_time了解到需要等待多长时间才能接收到正确的结果。一般来说，如果命令的执行可以在5秒钟内开始返回结果，则不需要使用Wait命令。需要注意的是：本协议的接收数据默认等待时间是5秒。如果一个命令在5秒内没有返回，并且没有用Wait命令指明需要等待的时间，则超时退出。-5-4.2控制字名称意义对命令执行结果的描述result标示某命令的执行结果，可能的常量值有：名称意义success成功failed失败reason对执行结果的解释信息，可能的常量值有：名称意义unknowncommand不能识别的命令badparameter错误的参数devicebusy设备忙employeeoverflow对于SetEmployee命令，员工超过最大数unknownid对于DeleteEmployee命令，指定id的员工不存在notify对执行结果的提醒信息，通常是由于命令中有不能识别的参数所致，可能的常量值有：名称意义unknownparameter不能识别的参数注意执行结果必须以result/reason/notify开头，并且必须按result/reason/notify这样的顺序排列。wait_time指明完成某设备操作需要等待的时间，单位为秒公用常量检查方式常量用于定义考勤或开门等控制字的值，可能的常量值为：名称意义fp指纹方式考勤-6-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普通管理员prvg_adv_admin高级管理员check_type考勤方式，可能的常量值为检查方式常量。可用用逻辑常量并列多个常量表示该员工拥有多个权限。如：check_type=fp&card&face。opendoor_type开门方式，可能的常量值为检查方式常量。可用用逻辑常量并列多个常量表示该员工拥有多个权限。如：opendoor_type=fp|card。-7-permit_photo这是为了兼容V0.1协议保留的，特指考勤方式。是否有摄像权限，可能的常量值有：名称意义true允许false不允许permit_password这是为了兼容V0.1协议保留的，特指考勤方式。是否有密码考勤权限，可能的常量值有：名称意义true允许false不允许password如果有密码考勤权限，则本项对应其密码。对考勤记录信息的描述time考勤记录时间，格式为：yyyy-mm-ddhh:mm:ss。type考勤方式，可能的常量值为检查方式常量。card_type卡点的属性，可能的常量值有：名称意义cardtype_normal一般卡cardtype_on上班cardtype_off下班cardtype_addon加班上班cardtype_addoff加班下班cardtype_out外出cardtype_back回来card_src卡点产生的来源，可能的常量值有：名称意义from_check来自考勤机from_door来自门禁photo对于摄像方式考勤，该控制字后跟的是以base-64编码的Jpeg格式的照片。-8-对考勤机配置信息的描述dev_type考勤设备的类型：名称意义enroll考勤机door门禁time考勤机时间。weektime对应的星期，值为：1～7。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%。door门禁控制器设置，可能的常量值有：-9-名称意义wiegand26韦根26wiegand34韦根34wiegand27韦根信号W27(汉王标配控制器)op开关信号其他控制信息total总数。通常在有多个返回结果的时候用于标示返回结果的数目。该保留字必须要在他描述的多个返回结果之前出现，否则将被忽略。start_time开始时间，格式为：yyyy-mm-ddhh:mm:ss。end_time结束时间，格式为：yyyy-mm-ddhh:mm:ss。overwrite是否覆盖，可能的常量值有：名称意义true允许false不允许5命令详解5.1员工管理类命令命令GetEmployeeID()成功回复Return(result=successtotal=100id=11id=109...)。失败回复Return(result=failed)。命令GetEmployee(id=120)成功回复Return(result=successid=120name=张三finger_count=2finger_algorithm=0.0.1finger_captor=0.0.3finger_data=ADFASERQERERTYSDFGHSDFGADSF...-10-finger_data=HASRTTYHRTAEFASDFQEQAFf...(base-64enc