HwDevComm.dll開發(fā)使用手冊

1、HwDevComm.dll開發(fā)使用手冊1 概述HwDevComm.dll 是與所有漢王考勤機(jī)（及其他符合漢王考勤機(jī)通信協(xié)議-HDCP_V0.1.20060120協(xié)議（以下簡稱：通信協(xié)議）的考勤設(shè)備）進(jìn)行通信的動(dòng)態(tài)鏈接庫（DYNAMIC LINK LIBRARY，簡稱DLL），其可以在Win32平臺上被調(diào)用。2 接口HwDevComm.dll 對外提供了1個(gè)接口，描述如下：接口意義HwDev_Execute執(zhí)行各種命令，如管理類、記錄類等。其接口聲明如下：Int HwDev_Execute( char * pDevInfoBuf, unsigned long nDevInfoLen, char

2、* pSendBuf, unsigned long nSendLen,char * pRecvBuf, unsigned long * pRecvLen,FuncTotalDoneTp pFuncTotalDone)其接口具體參數(shù)、返回值及意義如下：參數(shù)意義pDevInfoBuf考勤機(jī)信息首指針；存放符合漢王考勤機(jī)通信協(xié)議-HDCP_V0.1.20060120語法的考勤機(jī)信息描述。考勤機(jī)信息描述形如：DeviceInfo( dev_id = "1" comm_type = "ip" ip_adress = "172.16.1.15"

3、)nDevInfoLen考勤機(jī)信息緩沖區(qū)的長度。pSendBuf發(fā)送緩沖區(qū)首指針；存放符合漢王考勤機(jī)通信協(xié)議-HDCP_V0.1.20060120語法的命令、參數(shù)和數(shù)據(jù)。建議在緩沖區(qū)中一次放入一條命令。如果在該緩沖區(qū)中放入了多個(gè)命令，將會(huì)被順序執(zhí)行。如果其中的一個(gè)命令執(zhí)行失敗了，將不會(huì)影響到之后的命令的執(zhí)行。nSendLen發(fā)送緩沖區(qū)的長度。如果 nSendLen=0 則HwDevComm.dll只接收不發(fā)送。pRecvBuf接收緩沖區(qū)首指針；存放各種命令的執(zhí)行結(jié)果；執(zhí)行結(jié)果的語法符合漢王考勤機(jī)通信協(xié)議-HDCP_V0.1.20060120；該內(nèi)存由HwDevComm.dll來申請和釋放。pR

4、ecvLen接收緩沖區(qū)的長度pFuncTotalDone回調(diào)函數(shù)指針；用于向調(diào)用者反饋執(zhí)行進(jìn)度。其中PFuncTotalDoneTp類型的定義為：typedef int (CALLBACK FuncTotalDoneTp)( unsigned long nTotal, unsigned long nDone )。返回值意義0成功-1失敗其他保留3 通信協(xié)議概述3.1 與考勤機(jī)的連接兩種方式：串口、Socket。準(zhǔn)備：用串口線連接PC機(jī)與考勤機(jī)或用網(wǎng)線連接PC機(jī)與考勤機(jī)。建立串口連接：打開PC機(jī)串口（考勤機(jī)串口默認(rèn)處于打開狀態(tài)）。拆除串口連接：關(guān)閉PC機(jī)串口。建立Socket連接：建立PC機(jī)So

5、cket，Connect考勤機(jī)（考勤機(jī)默認(rèn)處于Accept狀態(tài)，在9922端口監(jiān)聽）。拆除Socket連接：關(guān)閉PC機(jī)Socket。3.2 語法和保留字圖3.1本協(xié)議的語法結(jié)構(gòu)如圖3.1所示，由4類保留字組成，這4類保留字的說明如表3.1所示。保留字名稱意義與用途命令字用于指明本次操作究竟要干什么（如：GetEmployeeID 表示獲取考勤機(jī)上所有員工的員工號）?？刂谱肿鳛槊钭值膮?shù)出現(xiàn)，用于指明該參數(shù)是什么（如：name 表示該參數(shù)是員工姓名）。常量保留字作為命令字的參數(shù)出現(xiàn)，一般跟在控制字的后面，用于指示該參數(shù)的值是多少。（如：language="chs" 表示該考

6、勤機(jī)的語言設(shè)置為簡體中文）。分隔符用于分隔各個(gè)保留字。表3.1除分隔符外，其余保留字為 數(shù)字字母下劃線 的組合，最長32字符，大小寫敏感。各保留字間可以插入Space(空格)、Tab(跳格)、CR(回車)，處理忽略不計(jì)。3.3 保留字的命名原則保留字名稱命名原則命令字Pascal命名法，指用一個(gè)或多個(gè)連在一起的詞來組成名字，每個(gè)詞都用大寫字母開頭，其他字母都小寫。控制字采用“小寫加下劃線”的方式，都用小寫字母，詞之間用“_”分隔。如finger_count。常量保留字采用“小寫加下劃線”的方式。4 保留字列表及其意義4.1 命令字名稱意義員工管理類命令GetEmployeeID從考勤機(jī)接收所有

7、員工的員工號。GetEmployee從考勤機(jī)接收指定工號員工的員工信息，一次只能接收一個(gè)。SetEmployee發(fā)送員工到考勤機(jī)，一次只能發(fā)一個(gè)。DeleteEmployee在考勤機(jī)上刪除指定工號的員工?？梢淮蝿h除多個(gè)員工。DeleteAllEmployee在考勤機(jī)上刪除所有員工。SetNameTable該命令更新考勤機(jī)上的"id-姓名"對照表，然后更新表中存在的員工姓名。記錄管理類命令GetRecord從考勤機(jī)接收所指定時(shí)間范圍的考勤記錄。DeleteAllRecord在考勤機(jī)上刪除所有考勤記錄?？记跈C(jī)管理類命令I(lǐng)nitDevice初始化考勤機(jī)到出廠狀態(tài)。InitDevi

8、ceAdmin初始化考勤機(jī)的管理員設(shè)置到出廠狀態(tài)。GetDeviceInfo讀取考勤機(jī)配置、狀態(tài)信息。SetDeviceInfo設(shè)置考勤機(jī)配置、狀態(tài)信息。圖片管理類命令GetPictureName根據(jù)圖像文件的時(shí)間和圖片是否成功識別得到圖像文件名稱列表。GetPicture根據(jù)圖像文件名稱獲取圖像文件。圖像文件是以base-64編碼的Jpeg格式的照片。結(jié)果類命令Return返回值標(biāo)識。是某個(gè)命令執(zhí)行結(jié)果。結(jié)構(gòu)如：Return( result="success / failed" Ctrl_Word = "Parameter / Value" . )Wa

9、it等待標(biāo)識。表示考勤機(jī)正在執(zhí)行命令，需要等待一定的時(shí)間（時(shí)間由控制字wait_time指定，單位為秒）后才能返回結(jié)果，結(jié)構(gòu)如：Wait(wait_time = "10") /該命令表示需要等待10秒鐘該命令被用于如下場合：某操作需要時(shí)間較長（例如：初始化考勤機(jī)），這時(shí)等待該操作的一方可通過wait_time了解到需要等待多長時(shí)間才能接收到正確的結(jié)果。一般來說，如果命令的執(zhí)行可以在5秒鐘內(nèi)開始返回結(jié)果，則不需要使用Wait命令。需要注意的是：本協(xié)議的接收數(shù)據(jù)默認(rèn)等待時(shí)間是5秒。如果一個(gè)命令在5秒內(nèi)沒有返回，并且沒有用Wait命令指明需要等待的時(shí)間，則超時(shí)退出。4.2 控制字

10、名稱意義對命令執(zhí)行結(jié)果的描述result標(biāo)示某命令的執(zhí)行結(jié)果，可能的常量值有：名稱意義success成功failed失敗reason對執(zhí)行結(jié)果的解釋信息，可能的常量值有：名稱意義unknown command不能識別的命令bad parameter錯(cuò)誤的參數(shù)device busy設(shè)備忙employee overflow對于SetEmployee命令，員工超過最大數(shù)unknown id對于DeleteEmployee命令，指定id的員工不存在notify對執(zhí)行結(jié)果的提醒信息，通常是由于命令中有不能識別的參數(shù)所致，可能的常量值有：名稱意義unknown parameter不能識別的參數(shù)注意執(zhí)行結(jié)果

11、必須以result/reason/notify開頭，并且必須按result/reason/notify這樣的順序排列。wait_time指明完成某設(shè)備操作需要等待的時(shí)間，單位為秒公用常量檢查方式常量用于定義考勤或開門等控制字的值，可能的常量值為：名稱意義fp指紋方式考勤card卡式考勤face人臉識別考勤photo攝像考勤password密碼方式考勤邏輯運(yùn)算常量用于組合多個(gè)檢查方式常量，可能的常量值為：名稱意義&與|或?qū)T工信息的描述id員工號cacu_id根據(jù)某些法則計(jì)算得到的IDname員工姓名cardcode該員工的員工卡卡號finger_count該員工在考勤機(jī)上存儲(chǔ)的指紋的數(shù)

12、目finger_data指紋數(shù)據(jù)，值為base-64編碼的二進(jìn)制數(shù)據(jù)。face_data人臉特征數(shù)據(jù)，值為base-64編碼的二進(jìn)制數(shù)據(jù)。privilege該員工的權(quán)限，可能的常量值有：名稱意義prvg_none無權(quán)限prvg_user普通用戶prvg_admin普通管理員prvg_adv_admin高級管理員check_type考勤方式，可能的常量值為檢查方式常量?？捎糜眠壿嫵Ａ坎⒘卸鄠€(gè)常量表示該員工擁有多個(gè)權(quán)限。如：check_type="fp & card & face"。opendoor_type開門方式，可能的常量值為檢查方式常量?？捎糜眠壿嫵Ａ坎?/p>

13、列多個(gè)常量表示該員工擁有多個(gè)權(quán)限。如：opendoor_type="fp | card"。permit_photo這是為了兼容V0.1協(xié)議保留的，特指考勤方式。是否有攝像權(quán)限，可能的常量值有：名稱意義true允許false不允許permit_password這是為了兼容V0.1協(xié)議保留的，特指考勤方式。是否有密碼考勤權(quán)限，可能的常量值有：名稱意義true允許false不允許password如果有密碼考勤權(quán)限，則本項(xiàng)對應(yīng)其密碼。對考勤記錄信息的描述time考勤記錄時(shí)間，格式為：yyyy-mm-dd hh:mm:ss。type考勤方式，可能的常量值為檢查方式常量。card_ty

14、pe卡點(diǎn)的屬性，可能的常量值有：名稱意義cardtype_normal一般卡cardtype_on上班cardtype_off下班cardtype_addon加班上班cardtype_addoff加班下班cardtype_out外出cardtype_back回來card_src卡點(diǎn)產(chǎn)生的來源，可能的常量值有：名稱意義from_check來自考勤機(jī)from_door來自門禁photo對于攝像方式考勤，該控制字后跟的是以base-64編碼的Jpeg格式的照片。對考勤機(jī)配置信息的描述dev_type考勤設(shè)備的類型：名稱意義enroll考勤機(jī)door門禁time考勤機(jī)時(shí)間。weektime對應(yīng)的星期，

15、值為：17 。1：星期日 2：星期一7：星期六。language考勤機(jī)語言，可能的常量值有：名稱意義chs簡體中文cht繁體中文enu美國英語jpn日語kor朝鮮語volume考勤機(jī)音量大小，可能的常量值有：名稱意義low低mid中high高employee_total現(xiàn)有員工總數(shù)。employee_max最大員工數(shù)。record_total現(xiàn)有記錄總數(shù)。record_max最大記錄數(shù)。finger_algorithm指紋比對所用的算法。finger_captor采集頭的標(biāo)號。soft_version考勤機(jī)上軟件的版本號。memory_alarm內(nèi)存警戒百分比，可能的值為 1% 99%。doo

16、r門禁控制器設(shè)置，可能的常量值有：名稱意義wiegand26韋根26wiegand34韋根34wiegand27韋根信號W27(漢王標(biāo)配控制器)op開關(guān)信號其他控制信息total總數(shù)。通常在有多個(gè)返回結(jié)果的時(shí)候用于標(biāo)示返回結(jié)果的數(shù)目。該保留字必須要在他描述的多個(gè)返回結(jié)果之前出現(xiàn)，否則將被忽略。start_time開始時(shí)間，格式為：yyyy-mm-dd hh:mm:ss。end_time結(jié)束時(shí)間，格式為：yyyy-mm-dd hh:mm:ss。overwrite是否覆蓋，可能的常量值有：名稱意義true允許false不允許5 命令詳解5.1 員工管理類命令命令GetEmployeeID()成功回

17、復(fù)Return(result="success" total="100" id="11" id="109" .)。失敗回復(fù)Return(result="failed")。命令GetEmployee(id="120")成功回復(fù)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")。失敗回復(fù)Return(result="failed" reason="unknown id")。注意一次只能獲取一個(gè)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")成功回復(fù)Return(result="success")。失敗回復(fù)Return(result="failed&quo

20、t; reason="employee overflow")。命令DeleteEmployee(id="100")成功回復(fù)Return(result="success")。失敗回復(fù)Return(result="failed" reason="unknown id")。命令SetNameTable(120="張三" 88="李四" 192="王五" 1290="趙六" .)成功回復(fù)Return(result="

21、;success")。失敗回復(fù)Return(result="failed")。注意該命令更新"id-姓名"對照表，然后更新表中存在的員工姓名。對照表以覆蓋方式更新，若只想修改個(gè)別員工姓名，請用SetEmployee(id="1009" name="李四")命令。5.2 記錄管理類命令命令GetRecord(start_time="2005-11-1 0:0:0" end_time="2005-11-30 24:00:00")成功回復(fù)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.")。失敗回復(fù)Return(result="failed")。注意沒有start_time表示讀取end_time之前所有記錄；沒有end_time表示讀取start_time之后所有記錄；都沒有表示讀取全部記錄。start_time <= 有效時(shí)間段 <= end_time。接收記錄時(shí)以控制字time作為分隔每一條記錄的標(biāo)示。命令DeleteAllRecord()成功回復(fù)Return(result=

24、"success")。失敗回復(fù)Return(result="failed")。5.3 考勤機(jī)管理類命令命令I(lǐng)nitDevice()成功回復(fù)Return(result="success")。失敗回復(fù)Return(result="failed")。命令I(lǐng)nitDeviceAdmin()成功回復(fù)Return(result="success")。失敗回復(fù)Return(result="failed")。命令SetDeviceInfo(time="2006-1-16 12:39:40" memory_alarm="90%" language="chs" volume="low/mid/high")成功回復(fù)Return(result="success")。失敗回復(fù)Return(result="failed")。命令GetDeviceInfo()成功回復(fù)Return(result="success" dev_id="1"time="2006-1