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

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

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

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

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

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

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

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

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

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

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

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開門方式，可能的常量值為檢查方式常量?？捎糜眠壿嫵Ａ坎?/p>

13、列多個常量表示該員工擁有多個權限。如：opendoor_type="fp | card"。permit_photo這是為了兼容V0.1協(xié)議保留的，特指考勤方式。是否有攝像權限，可能的常量值有：名稱意義true允許false不允許permit_password這是為了兼容V0.1協(xié)議保留的，特指考勤方式。是否有密碼考勤權限，可能的常量值有：名稱意義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