dataapi接口使用指南.docx

1、dataapi接口使用指南目 录1 dataapi接口概述 12 dataapi接口技术说明 13 dataapi接口安装 24 dataapi接口函数详述 24.1 Connect 24.2 Disconnect 44.3 DataQuery 44.4 DataCount 84.5 DataAppend 94.6 DataUpdate 124.7 DataDelete 134.8 InfoQuery 144.9 InfoUpdate 164.10 GetRTLog 175 附录 215.1 附录1：接口文件的详细说明 215.2 附录2：demo演示程序的安装、使用指南 215.3 附录3：

2、dataapi接口函数出错说明一览 235.4 附录4：dataapi接口使用的数据表示、表、字段等一览 246 FAQ 326.1 编译VC下的Demo及RTime程序时，出现 ：“fatal error C1083: Cannot open include file: vld.h: No such file or directory”连接错误： 326.2 编译Jave Demo下的commprojava(VC DLL)工程时出现：“fatal error C1083: Cannot open include file: jni.h: No such file or directory”连

3、接错误： 326.3 使用彩屏机对一个用户表查询时：DataQuery(h, (char *)bufOut, 2 * 1024 *1024, “UserInfo”, “*”, “PIN6666”, “”)，过滤条件为: “PIN6666”,即准备查询考勤号大于6666的人员，为何下列记录会返回？ 326.4 当使用GPRS、串口连接时，Append很多指纹数据时非常慢，如何解决？ 336.5 使用RS232、RS485、UDP连接失败？ 336.6 使用RS232、RS485、UDP连接查询、追加操作时，经常返回-902错误？ 34Dataapi接口使用指南1 dataapi接口概述 Data

4、api接口是一组功能函数，是在原有脱机通信开发包SDK接口之上，扩展出的另一组函数接口，可以取代原有通信开发包SDK中对考勤机设备控制、数据访问的功能，但使最终应用程序开发用户在访问考勤机时，更直观、更方便、更简洁。Dataapi接口完成的功能有： 查询、计数、追加、更新、删除考勤机内与考勤用户有关的信息； 查询、计数、追加、更新、删除机内指纹相关的数据； 查询、计数、删除机内用户考勤记录数据； 查询、计数、追加、更新、删除考勤机内短信表的数据； 查询、计数、追加、更新、删除考勤机内工作表的数据； 查询、计数、删除机内管理记录数据； 查询、修改考勤机设备有关的信息。2 dataapi接口技术说

5、明 Dataapi接口使最终应用程序开发用户看起来是一组对考勤机内数据Set/Get的抽象接口，在具体访问考勤用户数据时，类似于在使用最通用的SQL语句。Dataapi接口在应用程序开发用户眼中看起来更像一个数据库服务器； Dataapi接口独立于HTTP、UDP、RS232/485通信协议，实现了与通信协议无关。因此该接口适用于目前任何物理连接形式的考勤机； Dataapi接口仅在访问时，和终端访问PC建立连接一次连接，使用完毕后，连接自动断开。因此，该接口在连接上更安全，更适合业务模型； Dataapi接口程序实现在考勤机内为C语言，在应用程序程序开发端（PC机）采用C语言封装的动态链接库

6、，做到了最高效的访问接口； Dataapi接口在设计伊始参考了SQL，但更考虑到业务中最常用的模型，是精心提炼出来的一组接口，做到了设计、实现、使用三方的平衡。3 dataapi接口安装 Dataapi接口函数存在于文件commpro.dll中，该库依赖于其他几个文件，需要将下列DLL文件一同拷贝到windows下的系统目录（windows XP下为windows/system32）：（含Demo的目录是演示程序如何编写，不要拷贝到系统目录）（注： 每个文件功能描述见附录1， 当收到中控科技更新版本的动态库时，注意先将系统目录下的原文件删除，确认删掉后，再拷贝更新版本的DLL）。 含demo的

7、目录是三种流行语言的开发演示程序，均附有源码及丰富的注释，如何正确成功编译它们，参见附录2。4 dataapi接口函数详述4.1 Connect函数DLLIMPORT void * _stdcall Connect(const char *Parameters);功能 连接到设备，连接成功后返回连接的句柄。参数说明 Parameters: in 通过Parameter参数指定连接选项，如下列例子： protocol=RS232,port=COM1,baudrate=115200bps,timeout=50000,passwd=0； protocol=RS485,port=COM2,baudra

8、te=115200bps,deviceid=1,timeout=50000, passwd=0； protocol=UDP,ipaddress=192.168.1.201,port=4370,timeout=50000, passwd=0； protocol=HTTP,ipaddress=192.168.1.201,port=80,name=12345,passwd=12345； protocol=HTTPS,ipaddress=192.168.1.201,port=80,name=12345,passwd=12345； 其中protocol 为使用协议，目前有RS232，RS485，UDP及

9、HTTP(S)；port为指定使 用的串口；baudrate为波特率；timeout为超时设置，单位为毫秒，例中“timeout=50000”为50秒；deviceid为使用RS485协议时终端设备号；ipaddress为考勤机IP地址；port为使用端口号（端口可以理解为收音机收听广播时使用的不同频率），如果不特别强调，默认为80；name为使用HTTP连接时认证用户名，passwd为连接时使用的密码。以上参数使用时按照例子中的样式填写。 遇到网络连接质量不好时，应加大timeout的值。一般的，“timeout=50000”（50秒）可以满足基本网络使用；当查询、追加大量数据经常出现-90

10、2错误时，应加大timeout的值，可以设置：“timeout=1200000”（20分钟）。 RS232、RS485、UDP连接时，其passwd=0指的是没有密码（不设置密码），可以不用填写“passwd=0”，但是HTTP、HTTPS连接时一定要填写“passwd=xxx”的设置。返回值 连接成功后返回连接句柄，否则返回NULL。示例 VC：CString szPara =protocol=HTTP,ipaddress=192.168.1.201,port=80,name=12345,passwd=12345 ;HANDLE h = Connect(szPara); VB：Private

11、 Declare Function Connect Lib commpro.dll (ByVal Parameters As String) As LongDim h As Long 连接设备句柄Dim ret As Long 函数返回h = Connect(protocol=HTTP,ipaddress=192.168.1.213,port=80,name=12345,passwd=12345)MsgBox Connect return =0x + Hex(h) Java：commpro2java co = new commpro2java();long h = co.Connect(pro

12、tocol=HTTP,ipaddress=192.168.1.213,port=80,name=12345,passwd=12345 );System.out.printf(Return Handle = 0x%xn, h);注意事项 如果返回为NULL，程序注意及时终止。 当使用串口（RS232、RS285）及UDP连接时，当考勤机重新启动过，那么客户端应当关闭此次连接，重新建立一次连接；HTTP(S)可以继续使用上次的连接。4.2 Disconnect函数DLLIMPORT void _stdcall Disconnect(void* Handle);功能 断开与设备的连接。参数说明 Ha

13、ndle: in 由Connect()成功返回的句柄。返回值 无。示例 VC： Disconnect(h); VB： Disconnect (h) Java：co.Disconnect(h);注意事项 一旦成功调用了Connect()，都应该调用Disconnect()函数，释放资源。4.3 DataQuery函数DLLIMPORT int _stdcall DataQuery(void *Handle, char *Buffer, int BufferSize, const char *TableName, const char *FieldNames, const char *Filter

14、, const char *Options);功能 查询设备中的数据，返回符合条件的记录数。参数说明 Handle in 由Connect()成功返回的句柄。 Buffer in 用于接收返回数据的缓冲区，返回的数据是文本格式的，可能是多条记录，各条记录之间用rn（等价于ASCII的值13，10）分隔，各个字段之间用t（等价于ASCII的值9）分隔。 BufferSizein 用于接收返回数据的缓冲区大小。 TableName in 数据表名，目前可用的有：用户表：UserInfo；指纹表：FPTemplate；考勤表：Transaction 或者 ExtLog；操作表：OpLog；短信表：S

15、ms；工作表：Workcode；组表：Group。（注：考勤表 Transaction / ExtLog 的区分在于考勤机内部使用的.ExtendFmt配置情况，当.ExtendFmt=1时，应该使用ExtLog；当ExtendFmt=0时，应该使用Transaction） FieldNamesin 字段名列表，多个字段之间用分号分开，“*”表示全部字段，此时返回数据字段的第一行是字段名 Filterin 返回数据的条件，当单独一个“字段名 操作符 值”构成的字符串时，可以是如下几种方式： = （“=”符号两边可以有空格或无空格） IN ()（“IN”两边须有空格） BETWEN (,) 或 BETWEN TO （“BETWEEN”、“TO” 的两边须有空格隔开） （“”符号两边可以有或无空格） = 最小