浩顺接口SDK

1.通讯协议共同利用的内容1.1 文档中所使用的术语1.2 基于HTTP协议机器与服务器通讯。

机器向服务器发送的所有的请求用POST方式的HTTP 请求。

利用在POST方式上传二进制数据的方法机器到服务器传达数据。

对这个POST请求的HTTP 应答的body部分也包含二进制数据。

1.3 请求和应答中所使用的二进制数据的格式HTTP请求和应答中所使用的二进制数据的格式是如下。

字符串数据放在最前边后续放置任意个数的二进制数据。

字符串数据是 JSON格式的字符串而且他的编码是 UTF-8。

其实使用JSON格式可以表达所有的数据格式。

可是表达二进制数据时可能产生整个数据的大少问题还有通讯速度问题等较难接收的问题。

在这个通讯协议中尽可能使用json格式却不可避免的情况下使用二进制数据来表达数据。

使用二进制数据时在前面的字符串数据里有标识对应后面的二进制数据是哪一个。

举个例子说如果某个字段的值的数据类型是二进制数据时用“BIN_n”的字符串来表示那个字段的值。

在此 n是后面的二进制数据的序号，从1开始。

实例 :{“log_array”:”BIN_1”}这个JSON字符串说明记录数据是二进制数据而且放在字符串数据后面的第一个位置。

1.4 机器与服务器的通讯流程与WEB服务器的通讯大概分两种。

一个是机器接收而执行操作者指令的流程，另一个是机器通知服务器某种事件（比如新记录的产生）的流程。

2. 操作者指令的大概处理过程操作者指令处理，是用户登陆服务器选择需要管理的考勤机，向考勤机下发指令，接收指令执行结果的过程。

处理过程如下：1)操作者选择考勤机，获得机器号（device_id）。

2)操作者在WEB服务器联动的数据库上保存对该机器所执行的指令的记录。

其记录中包含如下信息。

任务识别号（trans_id）,机器识别号（device_id）,指令识别号（cmd_code）,指令参数数据（cmd_param）,任务状态（trans_status）,任务状态最后更新时间（trans_status_update_time）3)机器每隔一定时间向服务器询问有没有针对自己发送的指令，如果有就拿过来执行，并且将其结果上传到WEB服务器。

4)操作者每隔一定时间询问服务指令的执行状态。

如果有已执行的标识，就处理该结果。

这里trans_id是任务识别号，即返回指令执行结果时用这个识别号来判断这个结果是对应哪一条指令的。

这个流程表示如图 2-1。

图2-1.指令处理过程中的通讯流程机器上传指令结果时如果结果数据是较大（10KB以上）可能划分几次上传该结果。

这时候机器分割数据成几个块而传输，服务器按顺序接收块保存在临时缓冲器。

如果服务器接收最后的块（块序号是0）拼接以前接收的块造成完整的结果数据而保存在数据库。

这样的流程如图2-2。

图2-2. 如果结果数据大分割成几个块而一次传输一个块接收指令而执行的流程和这时提交的 HTTP请求和返回应答的格式大部分类似却按指令有所不同。

2.1 考勤机实现接收操作者指令所需的请求和应答为了接收向自己发送的指令，考勤机每隔一定时间向WEB服务器发送HTTP request，并接收response，具体格式如下：2.1.1 机器接收操作者指令的请求为了接收向自己发送的指令，考勤机每隔一定时间向WEB服务器发送HTTP POST 请求。

这时HTTP头部（header）里放置如下字段。

上面一BOLD字体来标记的是该注意的字段。

HTTP body部分里放置在1.3描述的数据。

body部分放置的字符串的内容是如下。

{“fk_name”:<1>,“fk_time”:<2>,“fk_info”:{"supported_enroll_data":<3.1>,"fk_bin_data_lib":<3.2>,"firmware":<3.3>,"firmware_filename":<3.4>,"fp_data_ver":<3.5>}}fk_name 字段：机器的名字fk_time 字段：机器提交HTTP请求的机器的时间。

时间字符串的格式是 YYMMDDhhmmss。

fk_info 字段：机器的信息。

supported_enroll_data 字段：机器所使用的登记数据的类型。

例如如果用指纹数据就标记 [“FP”]。

fk_bin_data_lib 字段：解释机器上传的二进制数据时使用的动态库的名字。

例如标记“FKDataHS001”就表示如要解释二进制数据得用名字FKDataHS001.dll的动态库。

firmware 字段：机器的固件版本。

firmware_filename字段：机器的固件文件的头部。

这个信息将来更新机器固件的时候参考。

如果要更新的新固件文件名的头部不一致这个字段的价就表示这个新的固件文件不是匹配机器。

fp_data_ver字段：机器采用的指纹数据版本。

这个信息用于各种型号的机器的指纹数据之间的转换。

机器提交接收指令的HTTP请求时在 HTTP body部分不放置任何二进制数据。

2.1.2 服务器的应答对于接收指令的请求如果服务器接收上述的请求就查询有没有对该机器发送的指令而如有的话下传应答。

应答的头（header）和体（body）里所包含的内容是如下。

应答的头(header) 里包含如下字段。

应答体（ body）部分里放置的数据按指令不同。

2.2 机器上传指令执行结果所需的请求和答应机器执行指令后，发送HTTP request，接收response，将其结果告诉WEB服务器，具体格式如下：2.2.1 机器上传操作者指令执行结果所需的请求机器上传到服务器如下的 HTTP POST请求。

此时请求的头部放置如下字段。

此请求的体（body）里放置的数据按指令不同。

2.2.2 服务器的应答对于机器上传结果的请求服务器保存到数据库机器上传的指令执行结果而下传如下应答。

应答头部放置如下字段。

3. 按操作者指令具体设计请求和应答操作者发布的指令是如下。

3.1. 获得机器的登记数据(GET_ENROLL_DATA) 获得该机器里保存的各种登记数据。

3.2. 把数据库的登记数据写入到机器(SET_ENROLL_DATA) 把业务数据库的登记数据写入到机器。

3.3. 同步机器时间(SET_TIME) 调整机器的时间以服务器的时间。

3.4. 机器重新启动 (RESET_FK)在由于某些原因要重启考勤机的时候发送这个指令。

例如某个指令的状态一直在{RUN}状态的情况下。

若果不能确定这个现象的原因就重启机器是最合适的方法。

重启以后机器将忽视以前执行的所有的指令而进入接收新指令的状态。

3.5. 删除人员 (DELETE_USER)3.6. 修改姓名(SET_USER_NAME)3.7. 修改用户权限 (SET_USER_PRIVILEGE)-- HTTP header --response_code: <1>trans_id: <2>cmd_code: SET_USER_PRIVILEGE-- HTTP body --{<4>}<4>的格式{"user_id":"<1>","user_privilege":"<2>"}user_privilege : 表示用户的机器操作权限。

设置成如MANAGER : 管理员REGISTER : 登记员OPERATOR : 操作员USER : 普通用户-- HTTP header --request_code: send_cmd_resultdev_id: <2>trans_id:<3>cmd_return_code:<4>blk_no:<5>-- HTTP body --执行这个命令后不产生结果数据，所以body部分没有任何数据。

-- HTTP header --response_code: <1>trans_id: <2>3.8. 打开/关闭用户注册功能 (ENABLE_ENROLL_FUNC)机器发送的请求WEB服务器返-- HTTP header --request_code: receive_cmddev_id: <2>-- HTTP body --表示机器信息的字符串-- HTTP header --response_code: <1>trans_id: <2>cmd_code: ENABLE_ENROLL_FUNC-- HTTP body --{<4>}<4>的格式{"enable_flag":<5>}enable_flag : 激活注册用户功能的标志ON : 激活注册用户功能 (必须是大字母)OFF : 禁止注册用户功能-- HTTP header --request_code: send_cmd_resultdev_id: <2>trans_id:<3>cmd_return_code:<4>blk_no:<5>-- HTTP body --执行这个命令后不产生结果数据，所以body部分没有任何数据。

-- HTTP header --response_code: <1>trans_id: <2>3.9. 获得注册人员列表 (GET_USER_ID_LIST) 获取注册在机器里面的用户ID表3.10. 获取记录数据 (GET_LOG_DATA) 从机器获取某一个时间段之内的机器记录数据{<4>}<4>的格式{"begin_time":"<1>","end_time":"<2>"}时间字符串的格式为YYYYMMDDhhmmss。

begin_time字段为空的或者不存在字段本身的时候，会获取 eend_time字段为空的或者不存在字段本身的时候，会获取beg若两个字段为无效值，会获取机器里面的所有考勤记录数据。

-- HTTP header –request_code: send_cmd_resultdev_id:<2>trans_id:<3>cmd_return_code:<4>blk_no:<5>获取记录数据的时候，获取任何个数的记录数据，会成为很大的结果数据。