2024年1月20日发(作者：)
发卡器DLL接口使用手册
V1.3.0
XX公司
2021年1月5日
概述
本手册是酒店发卡器动态链接库的使用说明。
一、定义
1.
应用函数开发包含下列文件：
2.
适用操作系统：
Win7或Win10
3.
说明：
目前除停止发送空白卡接口外，不接受多个接口同时调用，请在上一个接口接收到返回值后再进行下一步操作。本套接口与通通酒店客户端及相关系列产品不通用，通通酒店下添加的锁及已初始化的卡片无法使用dll。
二、错误说明
1. 常规错误码
值 意义
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
21
26
28
31
201
202
203
1001
1002
1003
1004
1005
1006
OK
操作失败
参数错误
通信错误（指令发送错误）
通信错误（指令读取错误，请重新插拔）
通信错误（指令错误）
密钥未设置
操作失败，未进入发卡模式
操作中断失败（停止发送空白卡操作时失败）
操作中断（停止发送空白卡操作，原始操作返回）
服务器地址未配置（1.3.0内部默认设置，不再返回）
网络请求失败，请检查您的网络是否正常
接口返回的数据不符合格式要求，请重新配置服务器
hotelInfo无效
非本酒店读卡器
发卡器未初始化（1.3.0新增）
设备未连接，无法操作（1.3.0新增）
非IC卡（读取IC卡卡号时，放置卡片非IC卡）
断开连接失败（1.3.0新增）
配置串口失败（1.3.0新增）
无法打开日志文件（1.3.0新增）
配置密钥失败
配置卡密钥失败
配置酒店信息失败
配置服务器地址失败（内部使用，暂不开放）
获取设备注册信息列表失败（内部使用，暂不开放）
找不到相关的发卡器设备（内部使用，暂不开放）
设备已被占用（内部使用，暂不开放）
设备初始化失败，需要重新插拔（内部使用，暂不开放）
获取设备列表失败（内部使用，暂不开放）
2. 设备相关错误
值
101
102
104
105
106
107
108
意义
其它错误
操作超时
IC卡存储空间不足
解密失败或密钥未配置
卡解密失败
IC卡内不存在该条数据
密文校验失败
109
酒店ID未配置
3. 数据解析相关错误
值
301
301
304
305
307
420
意义
数据解析的其他错误
数据解析的其他错误
扇区空间不足
密钥解密失败或未配置
IC卡数据不存在
数据未正常返回
三、特殊获取说明
1. hotelInfo获取
通过固定Cloud API服务器接口获取，若未在本地配置特殊的Cloud API服务器，请固定使用接口：***.com/v3/hotel/getInfo
接 口：/v3/hotel/getInfo, GET
说 明：获取hotelInfo串
参 数：
参数名
clientId
clientSecret
是否必须
Y
Y
类型
String
String
含义
开放平台注册时分配的app_id
开放平台注册时分配的app_secret
示例
缺少该参数，请前往开放平台后台注册账号并创建应用：***.com/
例如：******** date
返 回 值：
值
hotelInfo
errcode
errmsg
Y Long 当前时间13位长度时间戳
意义
获取到的hotelInfo串，24小时有效
错误码，错误时返回
错误信息，错误时返回
四、函数说明
1. 配置服务器接口地址
原 型：bool CE_ConfigServer (const char *url)
说 明：本函数用于配置请求的服务器域名地址。未配置本地服务器时，默认不再调用该接口，使用公网地址进行访问，url配置为具体的目标接口
参 数：
参数名
const char *url
含义
服务器具体接口地址
取值范围
1. 没有配置本地服务器时，传入空值或字符串，访问公网地址
2. 传入具体的https服务器接口地址，不需要以’/’结束
返 回 值：
值
true
false
意义
配置成功
配置失败
2. 连接设备
原 型：int CE_ConnectComm (const char *portName)
说 明：本函数用于PC与酒店发卡器设备的连接与初始化。
参 数：portName：连接串口（COM1~COM256）
参数名
const char *portName
返 回 值：
值
0
1
26
意义
正确
操作失败（建立连接失败，设备被占用或未插入或安装驱动程序）
断开连接失败
含义
串口名称
取值范围
COM1~COM256
28
配置串口失败
更多错误码
3. 关闭连接
原 型：int CE_DisconnectComm(void)
说 明：本函数用于关闭PC到酒店发卡器的连接。
返 回 值：
值
0
1
意义
正确
失败
4. 配置发卡器
原 型：int CE_InitCardEncoder(const char *hotelInfo)
说 明：将发卡器配置给指定的酒店。
参 数：
参数名
const char *hotelInfo
返 回 值：
值
0
2
201
202
203
意义
正确
参数错误
配置密钥失败
配置卡密钥失败
配置酒店信息失败
更多错误码
说明
发卡器配置成功
1.3.0过期
1.3.0过期
1.3.0过期
含义
酒店信息串，从服务器获取
取值范围
5. 将空白卡写成酒店专用卡
原 型：CE_InitCard(const char *hotelInfo)
说 明：将空白卡初始化成指定酒店的卡，操作前请终止其它操作
参 数：
参数名
const char *hotelInfo
返 回 值：
返回值
0
2
7
9
意义
正确
参数错误
操作失败，未进入发卡模式
操作中断
更多错误码
说明
含义
酒店信息串，从服务器获取
取值范围
6. 停止发送空白卡操作
原 型：int CE_StopInitCard(void)
说 明：本函数用于打断酒店发卡操作，请另启线程执行，执行完成后再执行其它操作！否则可能出现未知错误！！
返 回 值：
值
0
1
16
意义
正确
失败
设备未连接，无法操作(1.3.0新增)
7. 新增单条IC卡数据
原 型：int CE_WriteCard(const char *hotelInfo, int buildNo, int floorNo, const char
*mac,unsigned long timestamp, bool allowLockOut)
说 明：向IC卡中写入一条开锁数据
参 数：
参数名 含义 取值范围
const char *hotelInfo
int buildNo
int floorNo
const char *mac
unsigned long timestamp
bool allowLockOut
返 回 值：
返回值
0
2
9
11
酒店信息串，从服务器获取
楼栋号
楼层号
要开的锁的MAC地址
有效期截止时间的时间戳
是否允许开反锁
0 ~ 254
0 ~ 255
不带冒号的12位字符串
单位:秒
意义
正确
参数错误
操作中断
网络请求失败
更多错误码
说明
新增卡数据部分参数说明：
新增数据类型
总卡
楼栋卡
楼层卡
房间卡
buildNo
0
√
√
√
floorNo
0
0
√
√
mac
“********”
“********”
“********”
√ 允许离线操作
备注
禁止离线操作
8. 清空IC卡数据
原 型：int CE_ClearCard(const char *hotelInfo)
说 明：清空IC卡中写入的开锁数据
参 数：
参数名
const char *hotelInfo
返 回 值：
返回值
0
2
意义
正确
参数错误
说明
含义
酒店信息串，从服务器获取
取值范围
9 操作中断
更多错误码
9. 读取IC卡中的所有数据
原 型：int CE_ReadCard(const char *hotelInfo, char **hotelArray)
说 明：从IC卡中读取所有写入的数据
参 数：
参数名
const char *hotelInfo
char **hotelArray
含义
酒店信息串，从服务器获取
IC卡中的返回所有数据
取值范围
使用前初始化：char
*hotelarray = NULL，参数取地址,以JSON格式返回
返 回 值：
返回值
0
2
意义
正确
参数错误
更多错误码
hotelArray参数：
值
count
hotelArray
rray参数说明：
值
buildNo
floorNo
mac
allowLockOut
意义
楼栋号
楼层号
MAC地址
是否允许开反锁，取值true/false，VB定制取值1/0，分别对应true/false
timestamp
有效期截止时间
意义
卡内数据量
数据数组
说明
10. 获取IC卡卡号
原 型：int CE_GetCardNo(char **cardNumber)
说 明：本函数用于获取IC卡卡号
参 数：
参数名
char **cardNumber
含义
获取到的卡号数据
取值范围
使用前初始化：char
*cardnumber = NULL，参数取地址
返回字符串为十进制卡号字符串
返 回 值：
返回值
0
2
21
意义
正确
参数错误
非IC卡
更多错误码
说明
读取IC卡卡号时，放置卡片非IC卡
11. 蜂鸣器发声
原 型：int CE_Beep(int voiceLen, int interval, int voiceCount)
说 明：本函数用于使得蜂鸣器发声，在连续操作接口时，请完成其他操作后调用
参 数：
参数名
int voiceLen
int interval
int voiceCount
返 回 值：
返回值
0
意义
正确
说明
含义
每次发声时间长度
每次发声时间间隔
发声次数
取值范围
1-10000（单位毫秒）
1-10000（单位毫秒）
1-50
2
9
参数错误
操作中断
更多错误码
12. 获取设备的版本信息
原 型：int CE_GetVersion(char **versions)
说 明：获取发卡器的版本信息
参 数：
参数名
char **versions
含义
获取到的版本信息
取值范围
使用前初始化：char
*version = NULL，参数取地址，以JSON格式返回
返 回 值：
返回值
0
2
意义
正确
参数错误
更多错误码
versions返回值：
值
model
hardware
software
dll
意义
型号
硬件版本
软件版本
dll版本
说明
13. 发工程卡
原 型：int CE_InitConstructionCard()
说 明：将空白卡初始化成工程卡，工程卡可用来打开所有未初始化的酒店锁
返 回 值：
返回值
0
2
9
意义
正确
参数错误
操作中断
更多错误码
说明
14. 恢复空白卡
原 型：int CE_DeInitCard(const char *hotelInfo)
说 明：将酒店卡反初始化为空白卡
参 数：
参数名
const char *hotelInfo
返 回 值：
返回值
0
2
意义
正确
参数错误
更多错误码
说明
含义
卡片原本所属酒店的信息串
取值范围
15. 写入挂失卡信息
原 型：int CE_CancelCard(const char *hotelInfo, const char *cardNo, unsigned long
timestamp)
说 明：向A卡内写入一条需要挂失的卡B的信息
参 数：
参数名
const char *hotelInfo
const char *cardNo
unsigned long timestamp
返 回 值：
含义
卡片原本所属酒店的信息串
需要挂失的目标卡卡号
卡B有效期截止时间
取值范围
十进制字符串
精确到秒
返回值
0
2
意义
正确
参数错误
更多错误码
说明
16. 读取IC卡中的挂失相关数据
原 型：int CE_ReadCancellationInfo(const char *hotelInfo, char **infoArray)
说 明：从IC卡中读取所有挂失相关的数据
参 数：
参数名
const char *hotelInfo
char **infoArray
含义
酒店信息串，从服务器获取
IC卡中返回的挂失数据
取值范围
使用前初始化：char
*infoArray = NULL，参数取地址,以JSON格式返回
返 回 值：
返回值
0
2
意义
正确
参数错误
更多错误码
infoArray参数：
值
count
infoArray
ray参数说明：
值
cardNo
timestamp
意义
被挂失的卡号
挂失到期时间（该参数为写入的到期时间之后的5年，非实际记录到期时间，请注意）
意义
卡内数据量
数据数组
说明
17. 设置扇区可用性
原 型：int CE_SetSectors(const char *sectors)
说 明：设置各个扇区的可用性
参 数：
参数名
const char *sectors
含义
设置各个扇区的可用性，1代表可用，0代表不可用
取值范围
如”********”.
以’0’和’1’组合的16字符长度，加结束符长度17，分别对应16个扇区。
1为可用，0为不可用。
特殊说明：全1和全0表示所有扇区都可用，传入全1数据会自动转换为全0设置
返 回 值：
返回值
0
2
9
意义
正确
参数错误
操作中断
更多错误码
说明
18. 读取扇区可用性
原 型：int CE_GetSectors(char **sectorStr);
说 明：读取各个扇区可用性
参 数：
参数名
char **sectorStr
含义
获取到的扇区禁用区块
取值范围
以’0’和’1’组合的16字符长度，加结束符长度17，分别对应16个扇区。
1为可用，0为不可用。
特殊说明：全1和全0表示所有扇区都可用
使用前初始化：char
*infoArray = NULL，参数取地址,以JSON格式返回
返 回 值：
返回值
0
2
意义
正确
参数错误
更多错误码
说明
19. 解析单个扇区的数据（1.2.0）
原 型：int CE_ParseResData(const char *hotelInfo, unsigned char *sectorData, bool
isLowestSector, char **hotelArray);
说 明：解析单个扇区的数据，该接口可脱离本公司发卡器使用
参 数：
参数名
const char *hotelInfo
unsigned char *sectorData
bool isLowestSector
含义
酒店信息串，从服务器获取
当前所选扇区数据内容
当前扇区是否为可操作性扇区中的第一个扇区
char **hotelArray 用于接收扇区解析的所有IC卡数据
使用前初始化：char
*hotelarray = NULL，参数取地址,以JSON格式返回
返 回 值：
返回值
0
2
意义
正确
参数错误
更多错误码
hotelArray参数：
说明
取值范围
固定长度48位
该参数由用户自行管理
值
count
hotelArray
rray参数说明：
值
buildNo
floorNo
mac
allowLockOut
意义
卡内数据量
数据数组
意义
楼栋号
楼层号
MAC地址
是否允许开反锁，取值true/false，VB定制取值1/0，分别对应true/false
timestamp
有效期截止时间
20. 创建单个扇区数据（1.2.0）
原 型：int CE_GenerateSectorData(const char *hotelInfo, unsigned char *sectorData,
bool isLowestSector, int buildNo, int floorNo, const char *mac, unsigned long timestamp, bool
allowLockOut);
说 明：获取向单个扇区内写入一条数据的扇区数据，该接口可脱离本公司发卡器使用， 该接口必须配置远程服务器地址
参 数：
参数名
const char *hotelInfo
unsigned char *sectorData
bool isLowestSector
含义
酒店信息串，从服务器获取
扇区数据
当前扇区是否为可操作性扇区中的第一个扇区
int buildNo
int floorNo
const char *mac
unsigned long timestamp
bool allowLockOut
返 回 值：
返回值 意义 说明
楼栋号
楼层号
要开的锁的MAC地址
有效期截止时间的时间戳
是否允许开反锁
0 ~ 254
0 ~ 255
不带冒号的12位字符串
单位:秒
取值范围
固定长度48位
该参数由用户自行管理
0
2
11
正确
参数错误
网络请求失败
更多错误码
新增卡数据部分参数说明：
新增数据类型
总卡
楼栋卡
楼层卡
房间卡
buildNo
0
√
√
√
floorNo
0
0
√
√
mac
“********”
“********”
“********”
√ 允许离线操作
备注
禁止离线操作
21. 创建用于删除扇区数据的数据（1.2.0）
原 型：int CE_GenerateClearData(unsigned char *srcBytes);
说 明：创建用于删除扇区数据的数据，该接口可脱离本公司发卡器使用
参 数：
参数名
unsigned char *srcBytes
含义
产生的数据写入卡后，会清空扇区数据
返 回 值：
返回值
0
2
意义
正确
参数错误
更多错误码
说明
取值范围
固定长度48位
22. 获取新增挂失信息的单个扇区数据（1.2.1）
原 型：int CE_GenerateCancelCardData(const char *hotelInfo, unsigned char
*sectorData, bool isLowestSector, const char *cardNo, unsigned long timestamp);
说 明：获取向单个扇区内写入一条挂失信息的扇区数据，该接口可脱离本公司发卡器使用，必须配置远程服务器地址
参 数：
参数名
const char *hotelInfo
unsigned char *sectorData
bool isLowestSector
含义
酒店信息串，从服务器获取
扇区数据
当前扇区是否为可操作性扇区中的第一个扇区
const char *cardNo
unsigned long timestamp
返 回 值：
返回值
0
2
意义
正确
参数错误
更多错误码
说明
需要挂失的目标卡卡号
被挂失卡有效期截止时间
十进制字符串
精确到秒
取值范围
固定长度48位
该参数由用户自行管理
23. 解析单个扇区内挂失相关数据（1.2.1）
原 型：int CE_ParseLossData(const char *hotelInfo, unsigned char *sectorData, bool
isLowestSector, char **infoArray);
说 明：解析挂失卡单个扇区内写入的挂失数据信息，该接口可脱离本公司发卡器使用， 该接口必须配置远程服务器地址
参 数：
参数名
const char *hotelInfo
unsigned char *sectorData
bool isLowestSector
char **infoArray
含义
酒店信息串，从服务器获取
扇区数据
当前扇区是否为可操作性扇区中的第一个扇区
扇区数据解析后返回的挂失数据
使用前初始化：char
*infoArray = NULL，参数取地址,以JSON格式返回
返 回 值：
返回值 意义 说明
取值范围
固定长度48位
该参数由用户自行管理
0
2
正确
参数错误
更多错误码
24. 创建工程卡块区数据（1.2.1）
原 型：int CE_GenerateConstructionCardData(unsigned char *blockData, const char
*cardNo);
说 明：获取创建工程卡的块区数据，该接口可脱离本公司发卡器使用，必须配置远程服务器地址，工程卡数据必须写入第0个扇区的第2块区（以0,1,2块区标准）
参 数：
参数名
unsigned char *blockData
const char *cardNo
返 回 值：
返回值
0
2
意义
正确
参数错误
更多错误码
说明
含义
块区数据
工程卡卡号
取值范围
固定长度16位
十进制字符串
五、常见问题说明
1.
操作卡片返回错误106
(1) 卡片为空白卡，无法进行读卡、写卡、清卡、挂失等相关卡数据操作。
方法：CE_InitCard将空白卡写成对应酒店的酒店卡
(2) 卡片已初始化为其它酒店的卡，无法将该卡写成当前酒店的酒店卡。
方法：将卡片在原来的酒店下恢复为空白卡，再在当前酒店下进行相关操作。
(3) 卡片已初始化为酒店卡，无法进行发工程卡的操作。
方法：将卡片在原来的酒店下恢复为空白卡，再在当前酒店下进行相关操作。
(4) 卡片使用的扇区与发卡器当前扇区不对应，无法解析。
方法：CE_SetSectors将发卡器设置成卡片当前使用的扇区，然后进行相关操作。
2. 发卡成功但无法开锁
(1) 开错锁。
(2) 锁时间不对。
(3) 卡扇区与锁扇区不一致。
(4) 锁被反锁，卡片无法开反锁。
(5) IC卡已在锁上被挂失。
(6) 门锁异常，如：在A系统添加，重置后又添加在B系统，A系统中此门锁还在，但无法继续使用。
3. 网络正常但返回错误11
(1) 网络状态差或请求接口失败。
(2) 部分情况下网络和接口正常但HTTP请求初始化失败，可进行重试操作。
(3) 1.3.0起详细情况可通过输出日志查看
4. 返回通信错误3/4/5
发卡器交互发生异常，请重新调用接口或插拔后重试。
5. 返回nfo无效
(1) HotelInfo已过期。
(2) HotelInfo被截断或修改，dll无法解析当前的hotelInfo.
(3) 1.3.0起详细情况可通过输出日志查看
6. 返回错误码101
卡片放置不正确或其它原因导致。
7. 连接设备返回1
(1) 设备未插入或连接的串口不正确。
(2) 没有安装设备驱动，设备无法被识别。
(3) 设备已被其它程序占用。
8. 在通通酒店使用的卡片发卡返回106/通通酒店的锁开不了
通通酒店及同一系列的产品与dll方案不兼容。
(1) 在通通酒店下使用的IC卡需要反初始化为空白卡后才能使用，否则返回106.
(2) 在通通酒店下添加的智能锁不能使用dll发卡，需重置后使用对应的APP重新添加，或使用酒店锁助手重新添加。
9. 楼栋楼层号怎么填？是否需要补0？
楼栋号（buildNo）楼层号 (floorNo)为正整数，有取值范围，没有补0的概念。
数据和通通酒店客户端不互通，通通酒店客户端中查询到的数据在这里无法使用。
10. 通通酒店拿过来的发卡器，初始化后卡片发成功了无法开锁
(1) 通通酒店默认使用的1-10号扇区，锁助手默认添加时使用1-16号扇区，请通过CE_GetSectors读取当前发卡器扇区，和锁助手中设置的扇区进行核对。
(2) 请参考第五部分 常见问题说明第1点。
11. 读取挂失数据中的有效期和写入挂失数据的有效期不对应
实际写入IC卡的挂失到期时间为传入时间之后的5年，该数据不是实际传入时间，实际退房时间请通过服务器进行管理。
12. 返回错误码105
hotelInfo正确设置，但扇区中可能存在脏数据，需清空数据后才能重新操作
发布评论