企盾守卫者综合门禁控制器JL-IDD-Z4开发包SDK说明
JL-IDD-Z4综合门禁控制器
开发说明书-使用SDK开发包
目录
1 文档内容简介
1) 通过API使用开发包。
调用接口为c语言接口,默认调用方式为cdecl。同时也提供了stdcall和fastcall的接口,具体参考jlidd.h文件。
最终使用的系统中需要安装了vc2008的支持包,可以运行"综合门禁控制器工具"安装包中的 vcredist_x86/vcredist_x86.exe 安装
接口文件为jlidd.h,库文件为jlidd.lib。
提供vc,c#,Delphi,java的调用实例供参考,其它语言请自行调用
二次开发发布时需要包含如下文件和目录:
Img 解析出来的身份证图片目录
ACE.dll 基础支持动态库
config.ini 配置文件,可用于控制接口库内部行为
jlidd.dll 开发包接口动态库
WltRS.dll 解码身份证头像图片的动态库,软件侧未使用到身份证阅读器可以不用
MasterCom.dll IC读写支持库,未使用IC卡内存储权限(梯控)时可以不用
MasterRD.dll IC读写支持库,未使用IC卡内存储权限(梯控)时可以不用
以及需要在目标计算机上安装vc2008支持包,即vcredist_x86/vcredist_x86.exe
2) 通过OCX使用开发包。
使用控件jliddctrl.ocx,通过jl_call命令调用接口,参数格式与API的call操作相同。
使用控件提供的OnEventCall(1号事件)接收数据并处理,等同与API开发包中的回调函数
使用VC调用控件的代码参考jlidd-vcocx目录,使用网页调用控件代码参考“测试.html”
使用控件前需要注册控件,可以参考“注册控件.bat”
二次开发发布时需要包含如下文件和目录:
Img 解析出来的身份证图片目录
ACE.dll 基础支持动态库
config.ini 配置文件,可用于控制接口库内部行为
jliddctrl.ocx 开发包控件
WltRS.dll 解码身份证头像图片的动态库,软件侧未使用到身份证阅读器可以不用
MasterCom.dll IC读写支持库,未使用IC卡内存储权限(梯控)时可以不用
MasterRD.dll IC读写支持库,未使用IC卡内存储权限(梯控)时可以不用
以及需要在目标计算机上安装vc2008支持包,即vcredist_x86/vcredist_x86.exe
1.1 特别情况说明
控制器使用一些特殊卡号
ü 小于255的卡号用于表示事件,因此系统中不能使用小于255的IC/ID卡
ü 卡号666666表示模拟刷卡,可以配置指定信号被触发后,系统将此信号转换成卡号为666666刷卡
ü 卡号7777777表示过闸超时,用于实时上报表示刷卡后指定时间范围内没有通过闸机(需要在信号配置中指定哪一路信号连接的过闸红外检测信号)
ü 卡号111111111111111110表示所有身份证,使用此号授权后,所有身份证即可有此权限
2 API操作函数接口说明
Jlidd.dll和jlidd.h中同时提供了cdecl及stdcall和fastcall三套API,默认为cdecl。Stdcall及fastcall的接口名称是在命令call/freeBuffer/setCallback后添加_stdcall和_fastcall来区别。没有特殊需要不用使用这些接口。
开发范例可参考如下目录
jlidd-example
jlidd-delphi
jlidd-csharp
jlidd-java
jlidd-vcocx
测试.html
2.1 请求命令
2.1.1 原型
char *call(int cmdcode, char *content);
2.1.2 规范
ü 请求命令要求提供两个调用参数。命令字参数cmdcode和命令内容参数content。
cmdcode是一个32位整数,指定了当前操作的类型及功能,可用的命令字参考后面的说明。
content指定命令的详细数据,要求是一个C语言规范的字符串(即以ASCII的0表示字符串结束),字符串内容是以|分隔的多个参数值,各命令字可选参数值及含义参考后面的说明。参数值根据情况可以为空。如果命令字不需要任何参数,则content使用空字符串””。
ü 请求返回一个字符串。
调用返回的字符串以”-“分隔的多个子字符串连接组成,各子字符串的含义如下:
请求操作结果-控制器返回结果-错误消息-返回数据
其中,如果操作没有返回数据,返回数据字段以及其前面的-可能省略。各字段可能取值参考如下:
请求操作结果 |
说明 |
OK |
请求操作成功,或者消息已经成功发送 |
FAILED |
操作失败,错误原因可以参考数据及错误消息 |
控制器设备返回结果 |
说明 |
ACKOK |
控制器操作成功 |
ACKFAILED |
控制器操作失败 |
ACKTIMEOUT |
等待控制器返回消息超时 |
NONE |
不需要下发控制器或者没有下发,因此没有返回结果 |
错误消息 |
说明 |
Success |
操作成功 |
Failure |
操作失败 |
Bad parameter |
参数错误 |
Socket error |
套接字错误 |
Bind socket error |
套接字绑定失败 |
Bad device address |
错误的设备地址 |
Request timed out |
请求超时 |
No data |
没有数据 |
Device error |
设备错误 |
Unknown cmdcode |
未知命令字 |
Port already in use |
网络端口已被占用 |
Failed to load ic library |
加载IC读写器支持包失败。检查工作目录是否有MasterCom.dll和MasterRD.dll文件。 |
Failed to open device |
打开设备失败,检查IC读卡器端口号是否正确,是否有设备连接到电脑并且使用的1-9号端口,是否有其它可能有影响的串口设备。 |
Failed to find card |
寻卡失败,读卡区内没有卡片 |
Failed to read/write card |
读写卡失败,卡片被其它应用加密或者读写卡过程中卡片移出了读写区 |
2.1.3 功能说明
主动发送请求命令。可用的命令字及参数说明如下:
2.1.3.1 启动
命令字宏定义 |
值 |
说明 |
CMD_START |
0 |
启动服务,启动软件时调用一次即可,中途一般不要多次调用 |
参数 |
说明 |
可选值 |
举例 |
|
|
|
|
调用示例:
char *msg = call(CMD_START,””);
freeBuffer(msg);
2.1.3.2 停止
命令字宏定义 |
值 |
说明 |
CMD_STOP |
1 |
停止服务,软件退出前调用一次即可 |
参数 |
说明 |
可选值 |
举例 |
|
|
|
|
调用示例:
char *msg = call(CMD_STOP,””);
freeBuffer(msg);
2.1.3.3 添加权限
命令字宏定义 |
值 |
说明 |
CMD_ADDRIGHT |
11 |
添加权限到控制器 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
姓名 |
持卡人姓名,特殊控制器权限模式才支持在控制器上存储持卡人姓名,默认不存储,可为空。 |
最大四个汉字或者空 |
张三 |
卡号或证件号码 |
卡号或者身份证号码 |
10位数字 8位区位码格式卡号 18位身份证号码 由转换接口生成的20位数字卡号 |
0016232123 123,22312 510723197609114433 |
生效时间 |
权限生效时间 |
格式为24小时制 YYYY-MM-DD HH:MI:SS |
2013-05-06 10:00:00 |
失效时间 |
权限失效时间 |
格式为24小时制 YYYY-MM-DD HH:MI:SS |
2020-01-01 23:59:59 |
可用读头 |
当前卡可以在此控制器的哪些读头上使用 |
取值为0-255,按位表示1-8号读头。如255表示所有读头。1表示1号读头可用,其它读头不可用。 |
255 |
刷卡数次 |
当前卡可用的次数余额。 |
0-65535 0表示没有权限 65535表示不限次 |
3 65535 |
可用时段 |
当前卡可用时段,时段含义参考“综合门禁控制器工具”中的时段配置。 |
0-255 0表示随时可以开门。1表示禁止开门。 |
0 |
人员类型 |
人员类型,可以用于控制刷卡提示音。 |
0-7人员类型分类,默认为0 |
0 |
加密密码 |
为空或者为0表示不加密。用于软件开发商将其专用控制器和市场上通用的控制器区分开,需要与我司约定加密密码后,开发商使用约定密码调用,配合特供控制板使用。 |
无符号整数
|
0 |
反潜回开关 |
启用反潜回 |
0表示不启用反潜回 1表示启用反潜回 |
0 |
调用示例:
char * msg = call(CMD_ADDRIGHT,
"60102|192.168.0.111||1234567890|2000-01-01 00:00:00|2030-01-01 23:59:59|255|65535|0|0|0|0");
freeBuffer(msg);
2.1.3.4 删除权限
命令字宏定义 |
值 |
说明 |
CMD_REMOVERIGHT |
12 |
从控制器删除权限 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
卡号或证件号码 |
卡号或者身份证号码 |
10位数字 8位区位码格式卡号 18位身份证号码 由转换接口生成的20位数字卡号 |
0016232123 123,22312 510723197609114433 |
调用示例:
char * msg = call(CMD_REMOVERIGHT,"60102|192.168.0.111|1234567890");
freeBuffer(msg);
2.1.3.5 清除权限
命令字宏定义 |
值 |
说明 |
CMD_CLEARRIGHT |
13 |
清除控制器所有权限 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
调用示例:
char * msg = call(CMD_CLEARRIGHT,"60102|192.168.0.111");
freeBuffer(msg);
2.1.3.6 远程开门
命令字宏定义 |
值 |
说明 |
CMD_OPENDOOR |
14 |
远程开门(闭合继电器) |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
继电器序号 |
继电器序号,Z4板有4个继电器可以指定 |
1-4 |
1 |
开门时长 |
开门时长,单位为千分之一秒。继电器闭合指定时长后自动恢复。开门时长指定为650010表示恢复自主控制可刷卡或者远程开门,650020表示保持继电器断开直接恢复自主控制,650030表示保持继电器闭合直到恢复自主控制。650040表示只闭合继电器,650050表示只断开继电器,0表示使用继电器默认时长开门。 |
30-655360 |
3000 |
调用示例:
char * msg = call(CMD_OPENDOOR,"60102|192.168.0.111|1|3000");
freeBuffer(msg);
2.1.3.7 获取设备时间
命令字宏定义 |
值 |
说明 |
CMD_GETTIME |
15 |
取设备时间 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
返回数据 |
说明 |
格式及可选值 |
举例 |
设备时间 |
控制器当前时间 |
YYYY-MM-DD HH:MI:SS 24小时制 |
2015-03-01 18:23:56 |
调用示例:
char * msg = call(CMD_GETTIME,"60102|192.168.0.111");
freeBuffer(msg);
2.1.3.8 设置设备时间
命令字宏定义 |
值 |
说明 |
CMD_SETTIME |
16 |
设置设备时间为电脑时间 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
调用示例:
char * msg = call(CMD_SETTIME,"60102|192.168.0.111");
freeBuffer(msg);
2.1.3.9 播放语音
命令字宏定义 |
值 |
说明 |
CMD_SOUND |
21 |
控制播放语音JL-IDD-Z4S(SB5500)支持 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
放音动作 |
表示声音操作的类型 |
0无效,1-250表示指定次数播放,(-4)无限循环播放,(-3)执行指定的指令,(-2)停止播放并清除待播放列表,(-1)清除待播放列表 |
1 |
指令或者声音索引 |
|
0-219 要播放语音索引。 224-231 音量调节指令,值越大音量越大。 242 循环播放,在语音播放过程中发送此命令可循环当前地址语音。 254 停止播放指令。 |
0 |
直接播放 |
直接播放还是放入播放队列 |
1表示直接发送给 语音设备开始播放,0则放入播放队列 |
0 |
调用示例:
char * msg = call(CMD_ SOUND,"60102|192.168.0.111|1|0|0");
freeBuffer(msg);
2.1.3.10 重新启动设备
命令字宏定义 |
值 |
说明 |
CMD_REBOOT_DEV |
22 |
重新启动设备 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
调用示例:
char * msg = call(CMD_ REBOOT_DEV,"60102|192.168.0.111");
freeBuffer(msg);
2.1.3.11 显示文字到迪文屏
命令字宏定义 |
值 |
说明 |
CMD_SHOW_TEXT |
23 |
在控制板外接显示屏上显示数据 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
显示方向 |
要显示数据的方向,进表示在进入侧的显示屏上显示,出表示在离开侧的显示屏上显示 |
1进 2出 3双向 |
1 |
显示页面 |
要显示的页面号,能够支持哪些页面是由显示屏固件决定的 |
0-N |
1 |
恢复页面 |
显示结束完恢复的页面号,默认为0 |
0-N |
0 |
恢复页面等待时长 |
恢复操作前等待的秒数,也就是内容显示的持续时长。0表示一直显示,即不会自动恢复至某个页面。 |
0-N |
0 |
显示内容 |
以^分隔的多行文本。具体行数由显示屏固件决定。 |
|
测试标题^张三^1234567890^2016-01-01 12:00:00 |
调用示例:
char * msg = call(CMD_SHOW_TEXT,"60102|192.168.0.111|1|1|0|0|测试标题^张三^1234567890^2016-01-01 12:00:00");
freeBuffer(msg);
2.1.3.12 显示文字到LED条屏
命令字宏定义 |
值 |
说明 |
CMD_SHOW_LEDX |
24 |
在控制板外接LED屏上显示数据 |
注意:如果直接从迪文屏厂家购买DGUS串口屏,需要有一张2-16G大小的SD卡,并且在命令行下使用format /q g: /fs:fat32 /a:4096(注意g:是SD卡的盘符,需要替换为实际盘符如f,h等)格式化SD卡,再将我们提供的迪文屏软件放到SD卡中(如果有必要可以替换里面的三张背景图片,注意需要保证大小和格式不变),保证SD卡中有DWIN_SET目录,目录里面就是软件内容,然后将SD卡插到迪文屏进行软件升级。更多详细信息请百度或者咨询迪文屏厂家。
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
串口号 |
LED屏所接控制器的串口号 |
1-4 |
1 |
显示内容 |
以^分隔的多行文本。具体行数由显示屏决定。如果使用我们提供的迪文屏软件,通常各字段含义依次为姓名1/性别2/卡号3/测试4/结果5/时间6/预留7/预留8 |
|
测试标题^张三^1234567890^2016-01-01 12:00:00 |
显示时长 |
显示指定内容的秒数,超时后恢复默认显示, 0表示一直显示指定的内容,直到收到下一个显示指令 |
0-120 |
|
调用示例:
char * msg = call(CMD_SHOW_LEDX,"60102|192.168.0.111|1|测试标题^张三^1234567890^2016-01-01 12:00:00|0");
freeBuffer(msg);
2.1.3.13 文本转语音TTS
命令字宏定义 |
值 |
说明 |
CMD_PLAY_TTS |
25 |
发送文本实现TTS放音 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
串口号 |
TTS设备所接控制器的串口号,0表示自动检测 |
1-4 |
1 |
播放内容 |
要放音的文本内容 |
|
欢迎光临 |
调用示例:
char * msg = call(CMD_PLAY_TTS,"60102|192.168.0.111|4|欢迎光临");
freeBuffer(msg);
2.1.3.14 获取已经连接到软件的设备
命令字宏定义 |
值 |
说明 |
CMD_GET_ONLINE |
81 |
获取已经连接到软件的设备。设备的上报地址配置为运行软件的地址时,会自动连接到软件,通过此接口可以获取这些已经连接到软件的设备的信息。 |
参数 |
说明 |
可选值 |
举例 |
|
|
|
|
调用示例:
char *msg = call(CMD_GET_ONLINE,””);
freeBuffer(msg);
2.1.3.15 设置操作超时时间
命令字宏定义 |
值 |
说明 |
CMD_SET_TIMEOUT |
91 |
设置操作超时时间 |
参数 |
说明 |
可选值 |
举例 |
操作超时时间 |
向控制器发送请求操作后,等待的超时时间值。单位为千分之一秒。设置操作返回后新超时时间开始生效。 |
100-120000 |
5000 |
调用示例:
char *msg = call(CMD_SET_TIMEOUT,”5000”);
freeBuffer(msg);
2.1.3.16 取开发包版本号
命令字宏定义 |
值 |
说明 |
CMD_GET_VER |
99 |
取开发包版本号 |
参数 |
说明 |
可选值 |
举例 |
|
|
|
|
调用示例:
char *msg = call(CMD_GET_VER,””);
freeBuffer(msg);
2.1.3.17 加载IC卡支持模块
加载IC卡支持模块,通过IC卡支持模块可以控制发卡设备把权限信息写入IC卡,实现脱机门禁控制器(即不与电脑联网的控制器)的授权,另外梯控等需要控制扩展继电器的情况下也需要将楼层权限信息写入IC卡中。
命令字宏定义 |
值 |
说明 |
CMD_CARD_START |
31 |
加载IC卡模块,检测并打开发卡设备。软件启动时调用一次即可。 |
参数 |
说明 |
可选值 |
举例 |
IC读写器端口号 |
JL-501H发卡器在电脑中使用的端口号 |
空表示不加载 0表示加载并且自动检测设备端口号 1-9表示加载并使用指定端口号 建议尽可能通过参数指定设备端口号 |
0 |
调用示例:
char *msg = call(CMD_CARD_START,”0”);
freeBuffer(msg);
2.1.3.18 停止IC卡支持模块
命令字宏定义 |
值 |
说明 |
CMD_CARD_STOP |
32 |
停止卡模块。软件退出前调用一次即可。 |
参数 |
说明 |
可选值 |
举例 |
|
|
|
|
调用示例:
char *msg = call(CMD_CARD_STOP,””);
freeBuffer(msg);
2.1.3.19 写入权限到IC卡
命令字宏定义 |
值 |
说明 |
CMD_CARD_ADDRIGHT |
33 |
写入权限到IC卡,可以用于控制器没有联网络的情况下,通过将权限写入IC卡后在脱机控制器上直接使用。需要电脑连接了501H读写器并且设备的串口端口号小于10。 |
参数 |
说明 |
可选值 |
举例 |
控制器序号 |
未使用,填任意值或者空。 |
1-65535 |
60102 |
控制器IP地址 |
未使用,填任意值或者空。 |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
姓名 |
未使用,填任意值或者空。 |
最大四个汉字或者空 |
张三 |
卡号或证件号码 |
卡号,0表示自动检测并操作读卡区内的卡片 |
10位数字
|
0016232123 |
生效时间 |
权限生效时间 |
格式为24小时制 YYYY-MM-DD HH:MI:SS |
2013-05-06 10:00:00 |
失效时间 |
权限失效时间 |
格式为24小时制 YYYY-MM-DD HH:MI:SS |
2020-01-01 23:59:59 |
可用读头 |
当前卡可以在此控制器的哪些读头上使用 |
取值为0-255,按位表示1-8号读头。如255表示所有读头。1表示1号读头可用,其它读头不可用。 |
255 |
刷卡数次 |
当前卡可用的次数余额。 |
0-65535 0表示没有权限 65535表示不限次 |
3 65535 |
可用时段 |
当前卡可用时段,时段含义参考“综合门禁控制器工具”中的时段配置。 |
0-255 0表示随时可以开门。1表示禁止开门。 |
0 |
人员类型 |
人员类型,可以用于控制刷卡提示音。 |
0-7人员类型分类,默认为0 |
0 |
加密密码 |
为空或者为0表示不加密。用于软件开发商将其专用控制器和市场上通用的控制器区分开,需要与我司约定加密密码后,开发商使用约定密码调用,配合特供控制板使用。 |
无符号整数
|
0 |
反潜回开关 |
启用反潜回。写入IC卡中的权限信息启用了反潜回后还需要控制器上启用反潜回功能才会生效。 |
0表示不启用反潜回 1表示启用反潜回 |
0 |
楼层/扩展继电器 |
最大支持14个(组)控制器,每个控制器最大支持128个楼层。 |
以分号分隔多个控制器的信息。每个控制器内以分号分隔控制器标志和控制器上有权限的楼层列表。楼层列表间以#分隔。 |
10:1#15#25;11:1#2#3#4 表示当前卡有10号控制器组的1,15,25号扩展继电器的权限,有11号控制器组的1,2,3,4号扩展继电器的权限 |
调用示例:
char * msg = call(CMD_CARD_ADDRIGHT,
"|||0|2000-01-01 00:00:00|2030-01-01 23:59:59|255|65535|0|0|0|0|10:1#15#25;11:1#2#3#4");
freeBuffer(msg);
2.1.3.20 清除IC卡权限
命令字宏定义 |
值 |
说明 |
CMD_CARD_REMOVERIGHT |
34 |
清除IC卡权限。需要电脑连接了501H读写器并且设备的串口端口号小于10。 |
参数 |
说明 |
可选值 |
举例 |
|
|
|
|
调用示例:
char *msg = call(CMD_CARD_REMOVERIGHT,””);
freeBuffer(msg);
2.1.3.21 获取权限
命令字宏定义 |
值 |
说明 |
CMD_GETRIGHT |
17 |
获取指定卡号的权限 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
卡号或证件号码 |
卡号或者身份证号码 |
10位数字 8位区位码格式卡号 18位身份证号码
|
0016232123 123,22312 510723197609114433 |
调用示例:
char * msg = call(CMD_GETRIGHT,"60102|192.168.0.111|1234567890");
freeBuffer(msg);
2.1.3.22 检查权限
命令字宏定义 |
值 |
说明 |
CMD_CHECKRIGHT |
18 |
检查指定卡号是否有效 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
卡号或证件号码 |
卡号或者身份证号码 |
10位数字 8位区位码格式卡号 18位身份证号码
|
0016232123 123,22312 510723197609114433 |
调用示例:
char * msg = call(CMD_CHECKRIGHT,"60102|192.168.0.111|1234567890");
freeBuffer(msg);
2.1.3.23 设备搜索
命令字宏定义 |
值 |
说明 |
CMD_FIND_DEV |
82 |
搜索设备 |
参数 |
说明 |
格式及可选值 |
举例 |
搜索IP地址 |
控制器的IP:PORT,可以是广播地址,如255.255.255.255或者192.168.0.255,也可以是控制板内置的组播地址224.10.0.0,如果想搜索特定的设备,也可以直接指定的设备IP |
广播地址,组播地址或者设备IP |
255.255.255.255 |
搜索端口 |
对于广播地址或者指定设备的IP的情况下,端口通常为65534。对于组播地址224.10.0.0,端口为3366 |
65534 |
|
注意:调用此请求后,开发包发送搜索消息后立即返回操作成功。实际设备的响应消息将通过回调函数返回,回调类型为CBC_FIND_DEV,值为9,因此需要调用者通过实现回调函数取得搜索结果。返回消息格式参考2.3.2.3
调用示例:
char * msg = call(CMD_FIND_DEV,"224.10.0.0|3366");
freeBuffer(msg);
2.1.3.24 运行文本指令
命令字宏定义 |
值 |
说明 |
CMD_CALL_TEXT |
83 |
运行文本指令 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
命令内容 |
命令内容,长度小于500字节的文本指令。支持的指令内容参考本文后面的《支持的文本指令集》小节。 |
|
open1=300 |
调用示例:
char * msg = call(CMD_TEXT_CMD,"60102|192.168.0.111|open1=300");
freeBuffer(msg);
2.1.3.25 卡号转换
命令字宏定义 |
值 |
说明 |
CMD_CARD_CONV |
84 |
卡号格式转换,转换出来的卡号可以用于权限操作 |
参数 |
说明 |
格式及可选值 |
举例 |
要转换的卡号 |
根据目标格式可以参数需要提供不同的内容。 ü 目标格式为8时:本参数可以是任何不大于8字节的字符串,如姓名车牌号等 ü 目标格式为18时:本参数是带少量字母的卡号,一个字母当2个字节计算时总长度不超过17 ü 目标格式为20:本参数可以是任意字符串 |
|
川A1234 AC55023 http://www.baidu.com |
目标卡号格式 |
8:取8字节任意数据对应的20位数字卡号 18:将带少量字母的数据卡号转成身份证号码形式 20:任意条码字符串转成20位数字卡号 |
|
|
调用示例:
char * msg = call(CMD_CARD_CONV,"A12345|18");
freeBuffer(msg);
2.1.3.26 控制器设备监控
命令字宏定义 |
值 |
说明 |
CMD_DEV_MON |
26 |
获取设备状态及日志信息 |
参数 |
说明 |
格式及可选值 |
举例 |
控制器序号 |
控制器序号,可以使用“综合门禁控制器工具”搜索设备后得到。控制器的兼容模式打开时,可以使用65535控制所有设备。 |
1-65535 |
60102 |
控制器IP地址 |
控制器的IP:PORT |
所有合法IP地址,也可以带英文冒号加端口明确目标端口,不带则使用默认端口65534 |
192.168.0.111 |
获取的日志索引 |
0表示取最新日志,>0表示取指定位置的日志 |
|
0 |
调用示例:
char * msg = call(CMD_DEV_MON,"60102|192.168.0.111|0");
freeBuffer(msg);
2.2 释放请求命令返回的字符串
2.2.1 原型
void freeBuffer(char *buffer);
2.2.2 功能说明
释放由call操作返回的字符串。所有调用了call返回的字符串都需要使用此函数释放,否则会造成内存泄漏。
2.3 设置回调函数
2.3.1 原型
void setCallback(Callback func);
回调函数原型
typedef int (*Callback)( int callbackCode, char *content );
其中:
callbackCode为回调类型代码,应用实现的回调函数通过此值判断事件类型
content为字符串格式的数据,以|分隔多个数据段。最后一个数据段固定是来源设备IP:PORT
注意:
因为产品发展需要,回调函数中content数据可能发生变化,通常是其返回数据段增加(新增数据段在来源设备IP:PORT前,原有数据段后),建议应用使用灵活的方式处理content数据,以便软件能够与新版本的控制器兼容。
实际上,就是要注意不要假定倒数第N个字段是某个内容(倒数第一个字段除外,其固定是来源设备IP:PORT)。
比如,某回调函数在旧版本中返回的content数据为 控制器标志|控制器名称,加上SDK在回调前自动附加上的数据来源设备的IP:PORT,可能内容如下:
23136|正门闸机|192.168.0.100:50000
可能在你更新SDK后,新版本中此接口进行了扩展,添加了新的字段(为了前向兼容,通常不会减少字段)设备全球唯一标志和固件版本号,则新接口content内容可能为
23136|正门闸机|6234126987968269|v1236-10|192.168.0.100:50000
可以采用如下方式处理方式content:
1. 将content以|为分隔符分拆成多个字符串,假设分拆后字符串数量为N(包含空字符串)
2. 最后一个字符串即是消息来源IP:PORT
3. 前N-1个字段即是消息内容,使用下标直接访问这些数据
2.3.2 功能说明
调用者按规定要求实现一个回调函数,然后设置回调函数到开发包框架,当控制器同步或者异步事件发生时,框架会自动调用用户的回调函数。用户可在回调函数中实现自己的处理逻辑。
控制器生成的事件主要有两种类型,一种为实时(同步)事件,一种是非实时事件(异步)。实时事件指事件发生时控制器立刻向管理软件发送的事件,非实时事件则可能在事件发生后(通常是定时,如每分钟检查是否有事件需要上报)才上报。
2.3.2.1 实时消息上报
当控制器上发生某事件时,控制器立即生成消息发送到指定上报地址。
#define CBC_RT_SIGNAL 11 //信号变化实时消息(如门磁或者开门按钮等变化)
#define CBC_RT_CONN 12 //连接检测实时消息(用于检测网络状态的消息)
#define CBC_RT_MESSAGE 13 //调试通知信息
#define CBC_RT_SCAN 14 //刷卡实时消息(刷IC卡或者身份证的详细信息)
当用户的回调函数被调用后,判断回调代码callbackCode为上述值时,对应的content参数中即是此事件的详细信息。详细介绍见后面章节对实时消息的说明。
Ø 信号变化消息(CBC_RT_SIGNAL=11)回调content参数格式
信号是指控制器S1-S8输入端子的状态,信号变化消息用于通知应用S1-S8端子的短接或者断开。
255;251|25138|2016-07-21 16:09:47|258|259|514|515|770|771|1026|1027|25138|192.168.0.155:50000
以|分隔的各字段的含义为:
变化前信号总值: 变化后信号总值|控制器标志|时间|信息配置1|信息配置2|信息配置3|信息配置4|信息配置5|信息配置6|信息配置7|信息配置8|设备名称|对端通信地址
变化前信号值255(二进制11111111) 由低位到高位分别表示8个信号端子的状态(0表示信号端子和GND端子是短接着的,1表示是断开的),8个1就表示8个端子都是断开的
变化后信号值251(二进制11111011)表示除第3个端子(S3)是闭合的,其它都是断开的
因此此事件表示第3端子(S3)由断开状态切换为闭合状态了
注意:控制器启动时,系统默认信号值为0,因此会出现一个信号值从0变为某实际值的事件通知。比如假定所有端子都是断开的,此时如果控制器加电启动,就会生成一个从0变到255的事件通知。
回调函数中的内容是连接检测消息的内容,如果需要通过原始TCP/IP或UDP协议接收和处理此消息,请参考使用协议直接操作设备的相关说明。
Ø 连接检测消息(CBC_RT_CONN=12)回调content参数格式
连接检测消息用于检查控制器与服务器间通信是否正常,控制器也通过此消息向服务器通报自己的设备标志(5位短标志及16位全局标志)。
控制器工作在TCP客户端模式下时,设备加电启动后或者连接断开后,会自动尝试跟服务器建立连接,如果连接建立成功则控制器会立即向服务器发送连接检测消息,消息中有控制器的短标志、全局标志等信息。
无论是在TCP客户端模式还是在UDP模式,如果配置了控制器选项中的“08.网络连接检测”,则控制器向定时向服务器发送连接检测消息。定时时间可以通过综合门禁控制器工具,配置选项-选项-设备网络超时秒数修改,点击确定后配置将存储在软件侧配置文件中,然后通过选择控制器并点击“保存配置”更新配置到控制器。定时检测消息的发送周期大致为配置的超时时间的1/4到1/2。
25138|120|60|1|25138|4530154638128612|25138|192.168.0.155:50000
以|分隔的各字段的含义为:
控制器标志|连接超时时间|剩余超时时间|网络复位次数|设备名称|全局标志|固定版本|设备短序号|生产时间|对端通信地址
回调函数中的content参数内容即是消息的内容,如果需要通过原始TCP/IP或UDP协议接收和处理此消息,请参考使用协议直接操作设备的相关说明。
Ø 调试实时消息(CBC_RT_ MESSAGE=13)回调content参数即是调试信息内容
Ø 刷卡实时消息(CBC_RT_SCAN=14)回调content参数格式
0000000000|||||2342093362||||||1|27186|4|2016-07-21 12:59:42|6|2|2|||192.168.0.155:50000
以|分隔的各字段的含义为:
固定为10个0|姓名|性别|民族|生日|卡号或证件号码|地址|发卡机关|开始有效期|结束有效期|身份证附加信息|应用分类标志|设备标志|控制器验证结果0表示控制器已经直接开门其它表示错误|刷卡时间|读头号|门号|方向1进2出|类型|子类型|身份证芯片内码|全局设备标志|对端通信地址
回调函数中的content参数内容即是消息的内容,如果需要通过原始TCP/IP或UDP协议接收和处理此消息,请参考使用协议直接操作设备的相关说明。
2.3.2.2 异步日志上报
异步日志上报指控制器在空闲时自动尝试把控制器上生成的日志向指定上报地址发送,发送成功则继续发送下一条,如果发送失败则延迟一段时间再尝试。日志上报功能可以通过“综合门禁控制器工具”的选项“05.允许设备自动主动上报刷卡记录”关闭。
#define CBC_LOG_2ND 1 //身份证刷卡日志
#define CBC_LOG_CARD 2 //普通刷卡日志
#define CBC_LOG_EVENT 3 //事件变化日志
当用户的回调函数被调用后,判断回调代码callbackCode为上述值时,对应的content参数中即是此事件的详细信息。
上报日志格式为:
卡号数据|应用类型|设备标志|控制器结果|刷卡时间|读头|门号|方向1进2出|设备名称|日志类型|日志子类型|身份证卡芯片号|全局设备标志|base64编码数据|base64编码头像|实时上报确认Id或者异步日志离线标志|对端通信地址
接收到异步日志后,需要向控制器返回确认消息,否则控制器会重复发送此消息。对于使用SDK开发应用,在实现的回调函数中返回0即可。
2.3.2.3 设备搜索响应
#define CBC_FIND_DEV 4 //设备搜索上报
发送设备搜索请求CMD_FIND_DEV后,设备的响应消息将通过此回调函数返回给应用。由于网络中可能有多个设备,一次发送指令可能产生多次回调操作。
返回内容content格式为
控制器名称|控制器标志|控制器通信IP:控制器通信端口|控制器全局标志|权限数量|日志数量|上报索引位置|对端通信地址
3 框架内置服务
详细信息参考文档《JL-IDD-Z4二次开发说明书-使用服务软件.doc》
4 基于TCP/UDP协议交互
详细信息参考文档《JL-IDD-Z4二次开发说明书-通过TCP或UDP协议交互.doc》
5 基于HTTP协议交互
详细信息参考文档《JL-IDD-Z4二次开发说明书-通过HTTP协议交互.doc》
6 附表
详细信息参考文档《JL-IDD-Z4二次开发说明书.doc》