PullSDK接口使用指南中文.doc

《PullSDK接口使用指南中文.doc》由会员分享，可在线阅读，更多相关《PullSDK接口使用指南中文.doc（27页珍藏版）》请在三一办公上搜索。

1、目 录1 PULLSDK接口概述12 PULLSDK接口技术说明13 PULLSDK接口安装14 PULLSDK接口函数详述24.1 Connect24.2 Disconnect34.3 SetDeviceParam44.4 GetDeviceParam44.5 ControlDevice54.6 SetDeviceData64.7 GetDeviceData74.8 GetDeviceDataCount94.9 DeleteDeviceData104.10 GetRTLog114.11 SearchDevice114.12 ModifyIPAddress124.13 PullLastErro

2、r134.14 SetDeviceFileData134.15 GetDeviceFileData145 附录155.1 附表一：接口文件的详细说明155.2 附表二：控制器参数的说明165.3 附表三：ControlDevice参数说明185.4 附表四：功能函数的表结构说明185.5 附表五：返回值错误码说明20PullSDK接口使用指南1 PullSDK接口概述PullSDK接口是一组功能函数，对C3、C4系列门禁控制器进行数据访问的通讯接口。PullSDK使最终应用程序开发用户在访问门禁控制器时，更直观、更方便、更简洁，其接口完成的功能有：读取、设置控制器参数；读取、设置、删除控制器的

3、时间段、用户信息、假日信息等数据；搜索、修改设备信息。2 PullSDK接口技术说明PullSDK接口使最终应用程序开发用户看起来是一组对门禁控制器内数据Set/Get的抽象接口，在具体访问设备用户数据时，类似于在使用最通用的SQL语句。PullSDK接口在应用程序开发用户眼中看起来更像一个数据库服务器。PullSDK接口支持TCP/IP和RS485通信协议。PullSDK接口使用C语言开发，对数据通讯做了高度优化，使其成为一个简洁高效的访问接口。PullSDK接口在设计开始参考了SQL，但更考虑到业务中最常用的模型，是精心提炼出来的一组接口，做到了设计、实现、使用三方的平衡。3 PullSD

4、K接口安装PullSDK接口函数存在于文件plcommpro.dll中，该库依赖于其他几个文件，需要将下列五个DLL文件一同拷贝到windows下的系统目录（windows XP下为windows/system32）（注：每个文件功能描述见附表一）。4 PullSDK接口函数详述4.1 Connect函数int Connect(const char *Parameters)功能连接设备，连接成功后返回连接句柄。参数说明Parameters:in 通过Parameter参数指定连接选项，如下列例子：protocol=RS485,port=COM2,baudrate=38400bps,device

5、id=1,timeout=50000, passwd=”;“protocol=TCP,ipaddress=192.168.12.154,port=4370,timeout=4000,passwd=”;需要向该函数传递与设备相关的连接参数方可实现连接功能。protocol是通讯使用的协议，目前有RS485和TCP两种方式；port：设备通讯端口。例如，以RS485方式连接，可设置port为COM1；以TCP通讯的端口，如果不特别强调，port默认为4370；deviceid：串口使用的设备ID号；baudrate：串口通讯使用的波特率；ipaddress：TCP/IP通讯相关设备的IP地址；ti

6、meout：连接超时时间，单位为毫秒。遇到网络连接质量不好时，应加大timeout的值。一般的，“timeout=5000”（5秒）可以满足基本网络使用；当查询数据经常出现-2错误码时，应加大timeout的值，可以设置：“timeout=20000”（20秒）。passwd：设置通讯的连接密码，可以为空表示不使用密码。（注：Parameters连接字符串大小写敏感）返回值与设备连接成功后返回该连接句柄，否则连接失败返回0。示例Python：params = “protocol=TCP,ipaddress=192.168.12.154,port=4370,timeout=4000,passwd

7、=”mpro = windll.LoadLibrary(plcommpro.dll)con_str = create_string_buffer(params)self.hcommpro = mpro.Connect(con_str)c#：params = “protocol=TCP,ipaddress=192.168.12.154,port=4370,timeout=2000,passwd=” ;IntPtr h = Connect(params);4.2 Disconnect函数Void Disconnect(HANDLE handle)功能断开与设备的连接参数说明handlein 由Co

8、nnect()成功返回的句柄。返回值无示例Python：mpro.Disconnect(self.hcommpro)self.hcommpro = 0c#：Disconnect(h);h = IntPtr.Zero;4.3 SetDeviceParam函数int SetDeviceParam(HANDLE handle, const char *ItemValues)功能设置控制器参数，例如设备号、门磁类型、锁驱动时间、读卡间隔等。参数说明handlein 由Connect()成功返回的句柄。ItemValuesin 将要设置的设备参数值，多个参数值之间可以用逗号分开，一次至多可同时设置20个

9、参数（可设置的参数值属性请参见表二）。返回值返回为0或者正数时，表示成功；返回负数时为错误，错误代码的信息请参见附表五。 示例Python：items = (DeviceID=1,Door1SensorType=2,Door1Drivertime=6,Door1Intertime=3)p_items = create_string_buffer(items)ret = mpro.SetDeviceParam(self.hcommpro, p_items)c#：int ret = 0;items = (DeviceID=1,Door1SensorType=2,Door1Drivertime=6,

10、Door1Intertime=3)ret = SetDeviceParam(h, items);4.4 GetDeviceParam函数int GetDeviceParam(HANDLE handle, char *Buffer, int BufferSize, const char *Items)功能读取控制器参数，例如设备号、门磁类型、锁驱动时间、读卡间隔等。参数说明handlein 由Connect()成功返回的句柄。Bufferin 用于接收返回数据的缓冲区，返回的数据是文本格式的，可能是多个参数值，各参数之间用逗号分隔。BufferSizein用于接收返回数据的缓冲区大小。Items

11、in 将要读取的设备参数名称表，多个名称之间可以用逗号分开，一次至多可同时读取20个参数（可设置的参数值属性请参见表一）。返回值返回为0或者正数时，表示操作成功；返回负数时为失败，错误代码的信息请参见附表五。 示例Python：buffer = create_string_buffer(2048)items = (DeviceID,Door1SensorType,Door1Drivertime,Door1Intertime)p_items = create_string_buffer(items)ret = mpro.GetDeviceParam(self.hcommpro, buffer,

12、256, p_items)c#：int ret = 0;int BUFFERSIZE = 10 * 1024 * 1024;byte buffer = new byteBUFFERSIZE;items = (DeviceID,Door1SensorType,Door1Drivertime,Door1Intertime);ret = GetDeviceParam(h, ref buffer 0, BUFFERSIZE, items);4.5 ControlDevice函数int ControlDevice(HANDLE handle, LONG OperationID, LONG Param1,

13、 LONG Param2, LONG Param3, LONG Param4, const char *Options)功能控制控制器动作。参数说明handlein 由Connect()成功返回的句柄；OperationIDin 操作内容，1表示输出操作，2表示取消报警，3表示重启设备；Param1in 当OperationID为输出操作时，此参数表示设备中门的ID号，详细请参见附表三；当OperationID为取消报警时，默认值为0；当OperationID为重启设备时，默认值为0；Param2in 当OperationID为输出操作时，此参数表示设备输出点地址，详细请参见附表三；当Oper

14、ationID为取消报警时，默认值为0；当OperationID为重启设备时，默认值为0；Param3in当OperationID为输出操作时，此参数表示开门时间（0表示关，255表示常开，取值范围为160（秒），默认值为0；当OperationID为重启设备时，默认值为0；Param4in 预留之用，默认为0；Optionin 默认为空，扩展之用；返回值返回为0或者正数时，表示成功；返回负数时表示失败，错误代码的信息请参见附表五。 示例Python：operation_id = 1door_id = 1index = 2state = 6ret = mpro.ControlDevice(se

15、lf.hcommpro, operation_id, door_id, index, state, 0, )c#：int ret = 0;int operid = 1;int doorid = 0;int outputadr = 0;int doorstate = 8;ret = ControlDevice(h, operid, doorid, outputadr, doorstate, 0, );4.6 SetDeviceData函数int SetDeviceData(HANDLE handle,const char *TableName,const char *Data，const cha

16、r *Options) 功能设置数据到设备,用于设置时间段、用户信息、假日设置、等数据，数据可以是一条记录，也可以是多条记录。参数说明handlein 由Connect()成功返回的句柄；TableNamein 数据表名，目前可使用表请参见附表四Datain 数据记录表示，数据是文本格式的，多条记录之间用rn分隔，各个“字段=值”对之间用t分隔；Optionsin 默认为空，扩展之用； 返回值返回为0或者正数时，表示操作成功；返回负数时表示失败，错误代码的信息请参见附表五。 示例Python：table = user# 用户信息表data = Pin=19999tCardNo=13375401

17、tPassword=1rnPin=2tCardNo=14128058tPassword=1p_table = create_string_buffer(table)str_buf = create_string_buffer(data)ret = mpro.SetDeviceData(self.hcommpro, p_table, str_buf, )# 向用户信息表上传str_buff数据c#：int ret = 0;string devtablename = user;string data = Pin=19999tCardNo=13375401tPassword=1rnPin=2tCar

18、dNo=14128058tPassword=1;string options = ;ret = SetDeviceData(h, devtablename, data, options);4.7 GetDeviceData函数int GetDeviceData(HANDLE handle, char *Buffer, int BufferSize, const char *TableName, const char *FieldNames,const char *Filter, const char *Options)功能从设备读取数据,用于读取刷卡记录、时间段、用户信息、假日设置、等数据，数

19、据可以是一条记录，也可以是多条记录。参数说明handlein 由Connect()成功返回的句柄；Bufferin 用于接收返回数据的缓冲区，返回的数据是文本格式的，可能是多条记录，各条记录之间用rn分隔。BufferSizein用于接收返回数据的缓冲区大小。TableNamein 数据表名，目前可用的表名参见附表四；FieldNamesin 字段名列表，多个字段之间用分号分开，“*”表示全部字段，此时返回数据字段的第一行是字段名Filterin 读取数据的条件，当单独一个“字段名 操作符 值”构成的字符串时，可以支持多个条件，使用逗号分隔，按如下方式：=（“=”符号两边不可以有空格）Opti

20、onsin 仅用于下载门禁事件记录，值为“NewRecord”时下载新记录，当为空时下载全部记录返回值返回为0或者正数时，表示操作成功，其值为记录条数；返回负数时为失败，错误代码的信息请参见附表五。 示例Python:table = ”user”# 从user表下载用户数据fielname = *# 下载表中的所用字段信息pfilter = ”# 没有过滤条件，全部下载options = ”query_buf = create_string_buffer(4*1024*1024)query_table = create_string_buffer(table)query_fieldname =

21、 create_string_buffer(fieldname)query_filter = create_string_buffer(filter)query_options = create_string_buffer(options)ret = mpro.GetDeviceData(self.hcommpro, query_buf, 4*1024*1024, query_table, query_fieldname, query_filter, query_options)c#：int ret = 0;int BUFFERSIZE = 10 * 1024 * 1024;byte buff

22、er = new byteBUFFERSIZE;string devtablename = user;string str = *;string devdatfilter = ;string options = ;ret = GetDeviceData(h, ref buffer0, BUFFERSIZE, devtablename, str, devdatfilter, options);4.8 GetDeviceDataCount函数int GetDeviceDataCount(void *Handle, const char *TableName, const char *Filter,

23、const char *Options)功能读取设备中的记录总数信息，返回指定数据的记录条数。参数说明Handlein 由Connect()成功返回的句柄；TableNamein 数据表名，目前可用的表名参见附表四Filterin 默认为空，扩展之用；Optionsin 默认为空，扩展之用；返回值返回为0或者正数时，表示操作成功，其值为记录条数；返回负数时为失败，错误代码的信息请参见附表五。示例Python：Table = userFilter = p_table = create_string_buffer(table)p_filter = create_string_buffer(filt

24、er)ret = mpro.GetDeviceDataCount(self.hcommpro, p_table, p_filter,)c#：int ret = 0;string devtablename = user;string devdatfilter = ;string options = ;ret = GetDeviceDataCount(h, devtablename, devdatfilter, options);4.9 DeleteDeviceData函数int DeleteDeviceData(HANDLE handle, const char *TableName,const

25、 char *Data,const char *Options)功能删除设备中的数据，例如用户信息、时间段等数据。参数说明handlein 由Connect()成功返回的句柄；TableNamein 数据表名，目前可用的表名参见附表四。Datain 数据记录表示，数据是文本格式的，可以多条记录之间用rn分隔，各个“字段=值”对之间用t分隔；Optionsin 默认为空，扩展之用；返回值返回为0或者正数时，表示成功；返回负数时为失败，错误代码的信息请参见附表五。示例Python：table = “user”data = Pin=2# 删除数据的条件p_table = create_string_

26、buffer(table)p_data = create_string_buffer(data)ret = mpro.DeleteDeviceData(self.hcommpro, p_table, p_data, )c#：int ret = 0;string devtablename = user;string data = Pin=2;string options = ;ret = DeleteDeviceData(h, devtablename, data, options);4.10 GetRTLog函数int GetRTLog(HANDLE handle,char *Buffer,

27、int BufferSize)功能实时获取设备事件记录。参数说明handlein 由Connect()成功返回的句柄。Bufferin 用于接收返回数据的缓冲区，返回的数据是文本格式的。BufferSizein 用于接收返回数据的缓冲区大小。返回值返回为0或者正数时，为接收数据的记录数；返回负数时为失败，错误代表的信息请参见附表五。示例Python：rt_log = create_string_buffer(256)ret = mpro.GetRTLog(self.hcommpro, rt_log, 256)c#：int ret = 0;int buffersize = 256;byte bu

28、ffer = new byte256;ret = GetRTLog(h, ref buffer0, buffersize);4.11 SearchDevice函数int SearchDevice(char *CommType,char *Address, char *Buffer)功能搜索局域网内的门禁控制器。参数说明CommTypein 通讯类型为 “Ethernet”，将会搜索指定通讯类型的设备；Addressin 广播地址，将会搜索指定IP地址范围内局域网的设备，默认为255.255.255.255；Bufferin 用于存储搜索到的设备的缓冲区，用户应根据网内设备数量来确定申请内存值。

29、例如50台设备以内建议申请32K的内存，100台设备以内建议申请64K的内存大小。返回值返回为0或者正数时，为搜索到的门禁控制器数量；返回负数时为失败，错误代码的信息请参见附表五。示例Python：dev_buf = create_string_buffer(, 64*1024)ret=mpro.SearchDevice(UDP, 255.255.255.255, dev_buf)c#：int ret = 0;string udp = UDP;string adr = 255.255.255.255;byte buffer = new byte64 * 1024;ret = SearchDev

30、ice(udp,adr, ref buffer0);4.12 ModifyIPAddress函数int ModifyIPAddress(char *CommType,char *Address, char *Buffer)功能UDP广播方式修改控制器IP地址。参数说明CommTypein 搜索设备的通讯类型为“Ethernet”通讯的设备；Addressin 广播地址，默认为255.255.255.255；Bufferin 用于存储目标设备的MAC地址和新IP地址；返回值返回为0或者正数时，为接收数据的记录数；返回负数时为失败，错误代码的信息请参见附表五。示例Python：mac = 00:1

31、7:61:01:88:27# 目标设备的MAC地址new_ip = 192.168.12.156# 设备新的IP地址comm_pwd = str = MAC=%s,IPAddress=%s % (mac,new_ip)p_buf = create_string_buffer(str)modify_ip = mpro.ModifyIPAddress(“UDP”, “255.255.255.255”, p_buf)c#：int ret = 0;string udp = UDP;string address = 255.255.255.255;string buffer = MAC=00:17:61

32、:01:88:27 + , + IPAddress=192.168.12.156;ret = ModifyIPAddress(udp,address,buffer);4.13 PullLastError函数int PullLastError()功能获取错误ID， 返回失败时可通过个函数获取失败ID。参数说明无返回值返回错误ID号。示例Python：ret = mpro.PullLastError()c#：int ret = 0;ret = PullLastError();4.14 SetDeviceFileData函数int SetDeviceFileData(void *Handle, co

33、nst char *FileName, char *Buffer,int BufferSize,const char *Options)功能将文件从PC传送到设备。参数说明Handlein 由Connect()成功返回的句柄；FileNamein 传送到设备的文件名,例如main文件；Bufferin 待传送文件的数据缓冲区；BufferSizein传送数据的长度；Optionsin 默认为空，扩展之用返回值返回为0或者正数时，表示成功；返回负数时为失败，错误代码的信息请参见附表五。示例Python：file_name = ”main”buff_len = len(file_main)pfil

34、e_name = create_string_buffer(file_name)pbuffer = create_string_buffer(buff_len)ret = mpro.SetDeviceFileData(self.hcommpro, pfile_name, pbuffer, buff_len, )c#：int ret = 0;string filename = user.dat;FileStream fsFile = File.OpenRead(this.openFileDialog1.FileName);string buffersize = (int)fsFile.Lengt

35、h;byte buffer = new bytebuffersize;string options = ;ret = SetDeviceFileData(h, filename, ref buffer0, buffersize, options);4.15 GetDeviceFileData函数int GetDeviceFileData(void *Handle,char *Buffer,int *BufferSize,const char *FileName,const char *Options)功能从设备获取文件到PC。参数说明Handlein 由Connect()成功返回的句柄；Fil

36、eNamein 从设备获取的文件名,例如main文件；Bufferin 接收数据的缓冲区；BufferSizein 接收数据的长度；Optionsin 默认为空，扩展之用返回值返回为0或者正数时，表示成功；返回负数时为失败，错误代码的信息请参见附表五。示例Python：file_name = ”main”pfile_name = create_string_buffer(file_name)pbuffer = create_string_buffer(4*1024*1024)ret = mpro.GetDeviceFileData(self.hcommpro, pbuffer, buff_le

37、n, pfile_name, )c#：int ret = 0;int buffersize = 4 * 1024 * 1024;byte buffer = new bytebuffersize;string filename = user.dat;string options = ;ret = GetDeviceFileData(h, ref buffer0, ref buffersize, filename, options);5 附录5.1 附表一：接口文件的详细说明文件名说明plcommpro.dllPullSDK函数的动态连接库接口plcomms.dllPullSDK接口的依赖库plr

38、scomm.dllPullSDK接口的依赖库pltcpcomm.dllPullSDK接口的依赖库rscagent.dllPullSDK接口的依赖库5.2 附表二：控制器参数的说明属性名称参数读写类型备注门数量LockCount只读读头数量ReaderCount只读自定义输入数量AuxInCount只读自定义输出数量AuxOutCount只读通信密码ComPwd读写默认没有IP地址IPAddress读写默认：192.168.1.201网关GATEIPAddress读写没有设置时为IP地址的值子网掩码NetMask读写默认255.255.255.0反潜回规则（设为反潜的门1和门2，需要有门1开门记

39、录才能在门2上开门，反之没有在门2上开门，不能在门1上连续开两次门）AntiPassback读写单门双向控制器1代表1号门读头间反潜双门单向控制器1代表1,2号门间反潜双门双向控制器1代表1号门读头间反潜2代表2号门读头间反潜3代表1,2号门各自读头间反潜4代表1,2号门间反潜四门单向控制器1代表1-2门反潜2代表3-4门反潜3代表1-2门反潜和3-4门反潜4代表1/2-3/4门反潜5代表1-2/3门反潜6代表1-2/3/4门反潜互锁（设为互锁的门1和门2，门1在开启时，门2只能处于关闭状态；反之门2被打开时，门1不能被打开）InterLock读写两门控制器1 代表1-2两门互锁四门控制器1

40、代表1-2两门互锁2代表3-4两门互锁3代表1-2-3三门互锁4代表1-2两门互锁和3-4两门互锁5代表1-2-3-4四门互锁胁迫密码Door1ForcePassWordDoor2ForcePassWordDoor3ForcePassWordDoor4ForcePassWord读写最大8位紧急密码Door1SupperPassWordDoor2SupperPassWordDoor3SupperPassWordDoor4SupperPassWord读写最大8位闭门回锁Door1CloseAndLockDoor2CloseAndLockDoor3CloseAndLockDoor4CloseAndL

41、ock读写1 启用0不启用门磁类型Door1SensorTypeDoor2SensorTypeDoor3SensorTypeDoor4SensorType读写0 代表无1 代表常开2 代表常闭锁驱动时长Door1DrivertimeDoor2DrivertimeDoor3DrivertimeDoor4Drivertime读写设置范围（0255）0代表常闭255代表常开1254 代表开门时长门磁超时报警时长Door1DetectortimeDoor2DetectortimeDoor3DetectortimeDoor4Detectortime读写设置范围（0255）单位为秒（s）开门方式Door1

42、VerifyTypeDoor2VerifyTypeDoor3VerifyTypeDoor4VerifyType读写0 为“卡”11 为“卡+密码”多卡开门启用（可使用多个人同时验证通过才能开门，在附表四 多卡开门组合表中设置多卡开门的组号，在该组里面的人员就是多人验证的人员，最多只能设置五人同时验证开门。）Door1MultiCardOpenDoorDoor2MultiCardOpenDoorDoor3MultiCardOpenDoorDoor4MultiCardOpenDoor读写0不启用 1启用首卡开门启用Door1FirstCardOpenDoorDoor2FirstCardOpenDo

43、orDoor3FirstCardOpenDoorDoor4FirstCardOpenDoor读写0:不启用 1.首卡常开 门激活时间段(接收有效刷卡时间段)Door1ValidTZDoor2ValidTZDoor3ValidTZDoor4ValidTZ读写默认0表示锁未激活门常开时间段Door1KeepOpenTimeZoneDoor2KeepOpenTimeZoneDoor3KeepOpenTimeZoneDoor4KeepOpenTimeZone读写默认0，没有设置刷卡间隔Door1IntertimeDoor2IntertimeDoor3IntertimeDoor4Intertime读写0为无间隔 以S（秒）为单位MCU看门狗WatchDog读写0不启用 1启用四门转两门Door4ToDoor2读写0不启用