发卡器DLL接口使用手册.docx

发卡器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）

原