dataapi接口使用指南.docx
《dataapi接口使用指南.docx》由会员分享，可在线阅读，更多相关《dataapi接口使用指南.docx（36页珍藏版）》请在冰豆网上搜索。
dataapi接口使用指南
目录
1dataapi接口概述1
2dataapi接口技术说明1
3dataapi接口安装2
4dataapi接口函数详述2
4.1Connect2
4.2Disconnect4
4.3DataQuery4
4.4DataCount8
4.5DataAppend9
4.6DataUpdate12
4.7DataDelete13
4.8InfoQuery14
4.9InfoUpdate16
4.10GetRTLog17
5附录21
5.1附录1：
接口文件的详细说明21
5.2附录2：
demo演示程序的安装、使用指南21
5.3附录3：
dataapi接口函数出错说明一览23
5.4附录4：
dataapi接口使用的数据表示、表、字段等一览24
6FAQ32
6.1编译VC下的Demo及RTime程序时，出现：
“fatalerrorC1083:
Cannotopenincludefile:
'vld.h':
Nosuchfileordirectory”连接错误：
32
6.2编译JaveDemo下的commprojava（VCDLL）工程时出现：
“fatalerrorC1083:
Cannotopenincludefile:
'jni.h':
Nosuchfileordirectory”连接错误：
32
6.3使用彩屏机对一个用户表查询时：
DataQuery（h,（char*）bufOut,2*1024*1024,“UserInfo”,“*”,“PIN>6666”,“”），过滤条件为:
“PIN>6666”,即准备查询考勤号大于6666的人员，为何下列记录会返回？
32
6.4当使用GPRS、串口连接时，Append很多指纹数据时非常慢，如何解决？
33
6.5使用RS232、RS485、UDP连接失败？
33
6.6使用RS232、RS485、UDP连接查询、追加操作时，经常返回-902错误？
34
Dataapi接口使用指南
1dataapi接口概述
Dataapi接口是一组功能函数，是在原有脱机通信开发包SDK接口之上，扩展出的另一组函数接口，可以取代原有通信开发包SDK中对考勤机设备控制、数据访问的功能，但使最终应用程序开发用户在访问考勤机时，更直观、更方便、更简洁。
Dataapi接口完成的功能有：
查询、计数、追加、更新、删除考勤机内与考勤用户有关的信息；
查询、计数、追加、更新、删除机内指纹相关的数据；
查询、计数、删除机内用户考勤记录数据；
查询、计数、追加、更新、删除考勤机内短信表的数据；
查询、计数、追加、更新、删除考勤机内工作表的数据；
查询、计数、删除机内管理记录数据；
查询、修改考勤机设备有关的信息。
2dataapi接口技术说明
Dataapi接口使最终应用程序开发用户看起来是一组对考勤机内数据Set/Get的抽象接口，在具体访问考勤用户数据时，类似于在使用最通用的SQL语句。
Dataapi接口在应用程序开发用户眼中看起来更像一个数据库服务器；
Dataapi接口独立于HTTP、UDP、RS232/485通信协议，实现了与通信协议无关。
因此该接口适用于目前任何物理连接形式的考勤机；
Dataapi接口仅在访问时，和终端访问PC建立连接一次连接，使用完毕后，连接自动断开。
因此，该接口在连接上更安全，更适合业务模型；
Dataapi接口程序实现在考勤机内为C语言，在应用程序程序开发端（PC机）采用C语言封装的动态链接库，做到了最高效的访问接口；
Dataapi接口在设计伊始参考了SQL，但更考虑到业务中最常用的模型，是精心提炼出来的一组接口，做到了设计、实现、使用三方的平衡。
3dataapi接口安装
Dataapi接口函数存在于文件commpro.dll中，该库依赖于其他几个文件，需要将下列DLL文件一同拷贝到windows下的系统目录（windowsXP下为windows/system32）：
（含Demo的目录是演示程序如何编写，不要拷贝到系统目录）
（注：
①每个文件功能描述见附录1，②当收到中控科技更新版本的动态库时，注意先将系统目录下的原文件删除，确认删掉后，再拷贝更新版本的DLL）。
含demo的目录是三种流行语言的开发演示程序，均附有源码及丰富的注释，如何正确成功编译它们，参见附录2。
4dataapi接口函数详述
4.1Connect
[函数]
DLLIMPORTvoid*__stdcallConnect（constchar*Parameters）;
[功能]
连接到设备，连接成功后返回连接的句柄。
[参数说明]
Parameters:
[in]通过Parameter参数指定连接选项，如下列例子：
"protocol=RS232,port=COM1,baudrate=115200bps,timeout=50000,passwd=0"；
"protocol=RS485,port=COM2,baudrate=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及HTTP（S）；port为指定使用的串口；baudrate为波特率；timeout为超时设置，单位为毫秒，例中“timeout=50000”为50秒；deviceid为使用RS485协议时终端设备号；ipaddress为考勤机IP地址；port为使用端口号（端口可以理解为收音机收听广播时使用的不同频率），如果不特别强调，默认为80；name为使用HTTP连接时认证用户名，passwd为连接时使用的密码。
以上参数使用时按照例子中的样式填写。
遇到网络连接质量不好时，应加大timeout的值。
一般的，“timeout=50000”（50秒）可以满足基本网络使用；当查询、追加大量数据经常出现-902错误时，应加大timeout的值，可以设置：
“timeout=1200000”（20分钟）。
RS232、RS485、UDP连接时，其passwd=0指的是没有密码（不设置密码），可以不用填写“passwd=0”，但是HTTP、HTTPS连接时一定要填写“passwd=xxx”的设置。
[返回值]
连接成功后返回连接句柄，否则返回NULL。
[示例]
VC：
CStringszPara="protocol=HTTP,ipaddress=192.168.1.201,port=80,name=12345,passwd=12345";
HANDLEh=Connect（szPara）;
VB：
PrivateDeclareFunctionConnectLib"commpro.dll"（ByValParametersAsString）AsLong
DimhAsLong'连接设备句柄
DimretAsLong'函数返回
h=
Connect（"protocol=HTTP,ipaddress=192.168.1.213,port=80,name=12345,passwd=12345"）
MsgBox"Connectreturn=0x"+Hex（h）
Java：
commpro2javaco=newcommpro2java（）;
longh=
co.Connect（"protocol=HTTP,ipaddress=192.168.1.213,port=80,name=12345,passwd=12345"）;
System.out.printf（"ReturnHandle=0x%x\n",h）;
[注意事项]
如果返回为NULL，程序注意及时终止。
当使用串口（RS232、RS285）及UDP连接时，当考勤机重新启动过，那么客户端应当关闭此次连接，重新建立一次连接；HTTP（S）可以继续使用上次的连接。
4.2Disconnect
[函数]
DLLIMPORTvoid__stdcallDisconnect（void*Handle）;
[功能]
断开与设备的连接。
[参数说明]
Handle:
[in]由Connect（）成功返回的句柄。
[返回值]
无。
[示例]
VC：
Disconnect（h）;
VB：
Disconnect（h）
Java：
co.Disconnect（h）;
[注意事项]
一旦成功调用了Connect（），都应该调用Disconnect（）函数，释放资源。
4.3DataQuery
[函数]
DLLIMPORTint__stdcallDataQuery（void*Handle,char*Buffer,intBufferSize,constchar*TableName,constchar*FieldNames,constchar*Filter,constchar*Options）;
[功能]
查询设备中的数据，返回符合条件的记录数。
[参数说明]
Handle
[in]由Connect（）成功返回的句柄。
Buffer
[in]用于接收返回数据的缓冲区，返回的数据是文本格式的，可能是多条记录，各条记录之间用\r\n（等价于ASCII的值13，10）分隔，各个字段之间用\t（等价于ASCII的值9）分隔。
BufferSize
[in]用于接收返回数据的缓冲区大小。
TableName
[in]数据表名，目前可用的有：
用户表：
UserInfo；
指纹表：
FPTemplate；
考勤表：
Transaction或者ExtLog；
操作表：
OpLog；
短信表：
Sms；
工作表：
Workcode；
组表：
Group。
（注：
考勤表Transaction/ExtLog的区分在于考勤机内部使用的.~ExtendFmt配置情况，当.~ExtendFmt=1时，应该使用ExtLog；当~ExtendFmt=0时，应该使用Transaction）
FieldNames
[in]字段名列表，多个字段之间用分号分开，“*”表示全部字段，此时返回数据字段的第一行是字段名
Filter
[in]返回数据的条件，当单独一个“字段名操作符值”构成的字符串时，可以是如下几种方式：
<字段名>=<值>（“=”符号两边可以有空格或无空格）
<字段名>IN（<逗号分隔的多个值列表>）（“IN”两边须有空格）
<字段名>BETWEN（<最小值>,<最大值>）或<字段名>BETWEN<最小值>TO<最大值>（“BETWEEN”、“TO”的两边须有空格隔开）
<字段名>><小值>（“>”符号两边可以有或无空格）
<字段名>>=<最小
升级会员 