发卡器DLL接口使用手册.docx
《发卡器DLL接口使用手册.docx》由会员分享，可在线阅读，更多相关《发卡器DLL接口使用手册.docx（27页珍藏版）》请在冰点文库上搜索。
发卡器DLL接口使用手册
发卡器DLL接口使用手册
V1.3.0
杭州赛脑智能控制技术有限公司
2021年1月5日
概述
本手册是酒店发卡器动态链接库的使用说明。
一、定义
1.应用函数开发包含下列文件：
CardEncoder.dll
mfc140ud.dll
msvcp140d.dll
ucrtbased.dll
vcruntime140d.dll
2.适用操作系统：
Win7或Win10
3.说明：
目前除停止发送空白卡接口外，不接受多个接口同时调用，请在上一个接口接收到返回值后再进行下一步操作。
本套接口与通通酒店客户端及相关系列产品不通用，通通酒店下添加的锁及已初始化的卡片无法使用dll。
二、错误说明
1.常规错误码
值
意义
0
OK
1
操作失败
2
参数错误
3
通信错误（指令发送错误）
4
通信错误（指令读取错误，请重新插拔）
5
通信错误（指令错误）
6
密钥未设置
7
操作失败，未进入发卡模式
8
操作中断失败（停止发送空白卡操作时失败）
9
操作中断（停止发送空白卡操作，原始操作返回）
10
服务器地址未配置（1.3.0内部默认设置，不再返回）
11
网络请求失败，请检查您的网络是否正常
12
接口返回的数据不符合格式要求，请重新配置服务器
13
hotelInfo无效
14
非本酒店读卡器
15
发卡器未初始化（1.3.0新增）
16
设备未连接，无法操作（1.3.0新增）
21
非IC卡（读取IC卡卡号时，放置卡片非IC卡）
26
断开连接失败（1.3.0新增）
28
配置串口失败（1.3.0新增）
31
无法打开日志文件（1.3.0新增）
201
配置密钥失败
202
配置卡密钥失败
203
配置酒店信息失败
1001
配置服务器地址失败（内部使用，暂不开放）
1002
获取设备注册信息列表失败（内部使用，暂不开放）
1003
找不到相关的发卡器设备（内部使用，暂不开放）
1004
设备已被占用（内部使用，暂不开放）
1005
设备初始化失败，需要重新插拔（内部使用，暂不开放）
1006
获取设备列表失败（内部使用，暂不开放）
2.设备相关错误
值
意义
101
其它错误
102
操作超时
104
IC卡存储空间不足
105
解密失败或密钥未配置
106
卡解密失败
107
IC卡内不存在该条数据
108
密文校验失败
109
酒店ID未配置
3.数据解析相关错误
值
意义
301
数据解析的其他错误
301
数据解析的其他错误
304
扇区空间不足
305
密钥解密失败或未配置
307
IC卡数据不存在
420
数据未正常返回
三、特殊获取说明
1.hotelInfo获取
通过固定CloudAPI服务器接口获取，若未在本地配置特殊的CloudAPI服务器，请固定使用接口：
接口：
/v3/hotel/getInfo,GET
说明：
获取hotelInfo串
参数：
参数名
是否必须
类型
含义
示例
clientId
Y
String
开放平台注册时分配的app_id
缺少该参数，请前往开放平台后台注册账号并创建应用：
clientSecret
Y
String
开放平台注册时分配的app_secret
date
Y
Long
当前时间13位长度时间戳
例如：
157********00
返回值：
值
意义
hotelInfo
获取到的hotelInfo串，24小时有效
errcode
错误码，错误时返回
errmsg
错误信息，错误时返回
四、函数说明
1.配置服务器接口地址
原型：
boolCE_ConfigServer（constchar*url）
说明：
本函数用于配置请求的服务器域名地址。
未配置本地服务器时，默认不再调用该接口，使用公网地址进行访问，url配置为具体的目标接口
参数：
参数名
含义
取值范围
constchar*url
服务器具体接口地址
1.没有配置本地服务器时，传入空值或字符串，访问公网地址
2.传入具体的https服务器接口地址，不需要以’/’结束
返回值：
值
意义
true
配置成功
false
配置失败
2.连接设备
原型：
intCE_ConnectComm（constchar*portName）
说明：
本函数用于PC与酒店发卡器设备的连接与初始化。
参数：
portName：
连接串口（COM1~COM256）
参数名
含义
取值范围
constchar*portName
串口名称
COM1~COM256
返回值：
值
意义
0
正确
1
操作失败（建立连接失败，设备被占用或未插入或安装驱动程序）
26
断开连接失败
28
配置串口失败
更多错误码
3.关闭连接
原型：
intCE_DisconnectComm（void）
说明：
本函数用于关闭PC到酒店发卡器的连接。
返回值：
值
意义
0
正确
1
失败
4.配置发卡器
原型：
intCE_InitCardEncoder（constchar*hotelInfo）
说明：
将发卡器配置给指定的酒店。
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
返回值：
值
意义
说明
0
正确
发卡器配置成功
2
参数错误
201
配置密钥失败
1.3.0过期
202
配置卡密钥失败
1.3.0过期
203
配置酒店信息失败
1.3.0过期
更多错误码
5.将空白卡写成酒店专用卡
原型：
CE_InitCard（constchar*hotelInfo）
说明：
将空白卡初始化成指定酒店的卡，操作前请终止其它操作
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
返回值：
返回值
意义
说明
0
正确
2
参数错误
7
操作失败，未进入发卡模式
9
操作中断
更多错误码
6.停止发送空白卡操作
原型：
intCE_StopInitCard（void）
说明：
本函数用于打断酒店发卡操作，请另启线程执行，执行完成后再执行其它操作！
否则可能出现未知错误！
！
返回值：
值
意义
0
正确
1
失败
16
设备未连接，无法操作（1.3.0新增）
7.新增单条IC卡数据
原型：
intCE_WriteCard（constchar*hotelInfo,intbuildNo,intfloorNo,constchar*mac,unsignedlongtimestamp,boolallowLockOut）
说明：
向IC卡中写入一条开锁数据
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
intbuildNo
楼栋号
0~254
intfloorNo
楼层号
0~255
constchar*mac
要开的锁的MAC地址
不带冒号的12位字符串
unsignedlongtimestamp
有效期截止时间的时间戳
单位:
秒
boolallowLockOut
是否允许开反锁
返回值：
返回值
意义
说明
0
正确
2
参数错误
9
操作中断
11
网络请求失败
更多错误码
新增卡数据部分参数说明：
新增数据类型
buildNo
floorNo
mac
备注
总卡
0
0
“000000000000”
禁止离线操作
楼栋卡
√
0
“000000000000”
楼层卡
√
√
“000000000000”
房间卡
√
√
√
允许离线操作
8.清空IC卡数据
原型：
intCE_ClearCard（constchar*hotelInfo）
说明：
清空IC卡中写入的开锁数据
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
返回值：
返回值
意义
说明
0
正确
2
参数错误
9
操作中断
更多错误码
9.读取IC卡中的所有数据
原型：
intCE_ReadCard（constchar*hotelInfo,char**hotelArray）
说明：
从IC卡中读取所有写入的数据
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
char**hotelArray
IC卡中的返回所有数据
使用前初始化：
char*hotelarray=NULL，参数取地址,以JSON格式返回
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
hotelArray参数：
值
意义
count
卡内数据量
hotelArray
数据数组
hotelArray.hotelArray参数说明：
值
意义
buildNo
楼栋号
floorNo
楼层号
mac
MAC地址
allowLockOut
是否允许开反锁，取值true/false，VB定制取值1/0，分别对应true/false
timestamp
有效期截止时间
10.获取IC卡卡号
原型：
intCE_GetCardNo（char**cardNumber）
说明：
本函数用于获取IC卡卡号
参数：
参数名
含义
取值范围
char**cardNumber
获取到的卡号数据
使用前初始化：
char*cardnumber=NULL，参数取地址
返回字符串为十进制卡号字符串
返回值：
返回值
意义
说明
0
正确
2
参数错误
21
非IC卡
读取IC卡卡号时，放置卡片非IC卡
更多错误码
11.蜂鸣器发声
原型：
intCE_Beep（intvoiceLen,intinterval,intvoiceCount）
说明：
本函数用于使得蜂鸣器发声，在连续操作接口时，请完成其他操作后调用
参数：
参数名
含义
取值范围
intvoiceLen
每次发声时间长度
1-10000（单位毫秒）
intinterval
每次发声时间间隔
1-10000（单位毫秒）
intvoiceCount
发声次数
1-50
返回值：
返回值
意义
说明
0
正确
2
参数错误
9
操作中断
更多错误码
12.获取设备的版本信息
原型：
intCE_GetVersion（char**versions）
说明：
获取发卡器的版本信息
参数：
参数名
含义
取值范围
char**versions
获取到的版本信息
使用前初始化：
char*version=NULL，参数取地址，以JSON格式返回
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
versions返回值：
值
意义
model
型号
hardware
硬件版本
software
软件版本
dll
dll版本
13.发工程卡
原型：
intCE_InitConstructionCard（）
说明：
将空白卡初始化成工程卡，工程卡可用来打开所有未初始化的酒店锁
返回值：
返回值
意义
说明
0
正确
2
参数错误
9
操作中断
更多错误码
14.恢复空白卡
原型：
intCE_DeInitCard（constchar*hotelInfo）
说明：
将酒店卡反初始化为空白卡
参数：
参数名
含义
取值范围
constchar*hotelInfo
卡片原本所属酒店的信息串
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
15.写入挂失卡信息
原型：
intCE_CancelCard（constchar*hotelInfo,constchar*cardNo,unsignedlongtimestamp）
说明：
向A卡内写入一条需要挂失的卡B的信息
参数：
参数名
含义
取值范围
constchar*hotelInfo
卡片原本所属酒店的信息串
constchar*cardNo
需要挂失的目标卡卡号
十进制字符串
unsignedlongtimestamp
卡B有效期截止时间
精确到秒
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
16.读取IC卡中的挂失相关数据
原型：
intCE_ReadCancellationInfo（constchar*hotelInfo,char**infoArray）
说明：
从IC卡中读取所有挂失相关的数据
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
char**infoArray
IC卡中返回的挂失数据
使用前初始化：
char*infoArray=NULL，参数取地址,以JSON格式返回
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
infoArray参数：
值
意义
count
卡内数据量
infoArray
数据数组
infoArray.infoArray参数说明：
值
意义
cardNo
被挂失的卡号
timestamp
挂失到期时间（该参数为写入的到期时间之后的5年，非实际记录到期时间，请注意）
17.设置扇区可用性
原型：
intCE_SetSectors（constchar*sectors）
说明：
设置各个扇区的可用性
参数：
参数名
含义
取值范围
constchar*sectors
设置各个扇区的可用性，1代表可用，0代表不可用
如”0000111100001111”.
以’0’和’1’组合的16字符长度，加结束符长度17，分别对应16个扇区。
1为可用，0为不可用。
特殊说明：
全1和全0表示所有扇区都可用，传入全1数据会自动转换为全0设置
返回值：
返回值
意义
说明
0
正确
2
参数错误
9
操作中断
更多错误码
18.读取扇区可用性
原型：
intCE_GetSectors（char**sectorStr）;
说明：
读取各个扇区可用性
参数：
参数名
含义
取值范围
char**sectorStr
获取到的扇区禁用区块
以’0’和’1’组合的16字符长度，加结束符长度17，分别对应16个扇区。
1为可用，0为不可用。
特殊说明：
全1和全0表示所有扇区都可用
使用前初始化：
char*infoArray=NULL，参数取地址,以JSON格式返回
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
19.解析单个扇区的数据（1.2.0）
原型：
intCE_ParseResData（constchar*hotelInfo,unsignedchar*sectorData,boolisLowestSector,char**hotelArray）;
说明：
解析单个扇区的数据，该接口可脱离本公司发卡器使用
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
unsignedchar*sectorData
当前所选扇区数据内容
固定长度48位
boolisLowestSector
当前扇区是否为可操作性扇区中的第一个扇区
该参数由用户自行管理
char**hotelArray
用于接收扇区解析的所有IC卡数据
使用前初始化：
char*hotelarray=NULL，参数取地址,以JSON格式返回
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
hotelArray参数：
值
意义
count
卡内数据量
hotelArray
数据数组
hotelArray.hotelArray参数说明：
值
意义
buildNo
楼栋号
floorNo
楼层号
mac
MAC地址
allowLockOut
是否允许开反锁，取值true/false，VB定制取值1/0，分别对应true/false
timestamp
有效期截止时间
20.创建单个扇区数据（1.2.0）
原型：
intCE_GenerateSectorData（constchar*hotelInfo,unsignedchar*sectorData,boolisLowestSector,intbuildNo,intfloorNo,constchar*mac,unsignedlongtimestamp,boolallowLockOut）;
说明：
获取向单个扇区内写入一条数据的扇区数据，该接口可脱离本公司发卡器使用，该接口必须配置远程服务器地址
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
unsignedchar*sectorData
扇区数据
固定长度48位
boolisLowestSector
当前扇区是否为可操作性扇区中的第一个扇区
该参数由用户自行管理
intbuildNo
楼栋号
0~254
intfloorNo
楼层号
0~255
constchar*mac
要开的锁的MAC地址
不带冒号的12位字符串
unsignedlongtimestamp
有效期截止时间的时间戳
单位:
秒
boolallowLockOut
是否允许开反锁
返回值：
返回值
意义
说明
0
正确
2
参数错误
11
网络请求失败
更多错误码
新增卡数据部分参数说明：
新增数据类型
buildNo
floorNo
mac
备注
总卡
0
0
“000000000000”
禁止离线操作
楼栋卡
√
0
“000000000000”
楼层卡
√
√
“000000000000”
房间卡
√
√
√
允许离线操作
21.创建用于删除扇区数据的数据（1.2.0）
原型：
intCE_GenerateClearData（unsignedchar*srcBytes）;
说明：
创建用于删除扇区数据的数据，该接口可脱离本公司发卡器使用
参数：
参数名
含义
取值范围
unsignedchar*srcBytes
产生的数据写入卡后，会清空扇区数据
固定长度48位
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
22.获取新增挂失信息的单个扇区数据（1.2.1）
原型：
intCE_GenerateCancelCardData（constchar*hotelInfo,unsignedchar*sectorData,boolisLowestSector,constchar*cardNo,unsignedlongtimestamp）;
说明：
获取向单个扇区内写入一条挂失信息的扇区数据，该接口可脱离本公司发卡器使用，必须配置远程服务器地址
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
unsignedchar*sectorData
扇区数据
固定长度48位
boolisLowestSector
当前扇区是否为可操作性扇区中的第一个扇区
该参数由用户自行管理
constchar*cardNo
需要挂失的目标卡卡号
十进制字符串
unsignedlongtimestamp
被挂失卡有效期截止时间
精确到秒
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
23.解析单个扇区内挂失相关数据（1.2.1）
原型：
intCE_ParseLossData（constchar*hotelInfo,unsignedchar*sectorData,boolisLowestSector,char**infoArray）;
说明：
解析挂失卡单个扇区内写入的挂失数据信息，该接口可脱离本公司发卡器使用，该接口必须配置远程服务器地址
参数：
参数名
含义
取值范围
constchar*hotelInfo
酒店信息串，从服务器获取
unsignedchar*sectorData
扇区数据
固定长度48位
boolisLowestSector
当前扇区是否为可操作性扇区中的第一个扇区
该参数由用户自行管理
char**infoArray
扇区数据解析后返回的挂失数据
使用前初始化：
char*infoArray=NULL，参数取地址,以JSON格式返回
返回值：
返回值
意义
说明
0
正确
2
参数错误
更多错误码
24.创建工程卡块区数据（1.2.1）
原
升级会员 