酒店门锁管理系统接口说明.docx
《酒店门锁管理系统接口说明.docx》由会员分享，可在线阅读，更多相关《酒店门锁管理系统接口说明.docx（20页珍藏版）》请在冰豆网上搜索。
酒店门锁管理系统接口说明
深圳市同创新佳科技有限公司技术文件
LS-PMS酒店门锁管理系统
集成发卡接口说明书
HotelLocksManagementSystem
PMSIntegrateKeycardsEncode
SDKUserGuide
版本号：
2.0
版本号
发布日期
制定
审核
批准
V1.0
2009-03-31
V2.0
2010-06-26
前言
本说明书由深圳市同创新佳科技有限公司提出。
本说明书主要起草单位：
深圳市同创新佳科技有限公司技术部。
本说明书主要起草人：
颜炜东、凌彬。
本说明书于2009年3月25日首次制定。
修订记录
版本号
修订内容
日期
批准
1.0
首次制定
2009-3-25
2.0
新增示例应用说明，接口适用版本
2010-06-26
LS-PMS酒店门锁管理系统集成发卡接口说明书
HotelLocksManagementSystemPMSIntegrationKeycardsEncodeSDKUserGuide
1目的和范围
该接口主要为酒店管理软件与我公司的读写卡设备提供标准的接口，以便酒店管理软件可以通过该接口对我公司设备进行操作。
2系统组成
WindowsAPI接口与TCP/IP接口.
系统结构
WindowsAPI接口系统结构:
TCP/IP接口系统结构:
:
3WindowsAPI接口
接口特点以及接口使用条件
该接口具有单机与网络2种接口，其特点是不管是单机还是网络接口，每个接口都必须安装一台发卡机，只能在安装了发卡机的电脑上调用ICDLL动态库完成制卡操作。
正常使用该接口必须满足如下要求：
3.1.1首先安装创佳门锁公司提供的门锁软件，正常运行软件，发行各种设置卡（包括：
授权卡、时钟卡、房号卡），使用设置卡完成门锁设置（如果有多台电脑发卡，则每台电脑都必须安装我们门锁软件并注册，然后用主电脑上的授权卡恢复授权，详细操作请参考门锁设置说明）。
3.1.2使用前先调用初始化函数初始化软件使用环境即调用init函数
3.1.3使用windows98/2000/XP操作系统.
3.1.4动态库ICDLL.dll
WindowsAPI接口文件说明
WindowsAPI接口文件如表:
文件名
文件说明
Demo.exe
接口示例可执行文件
..\ICDLL\Ver4.2\ICDLL.dll
接口函数库文件,IC门锁,适用门锁管理软件IC-NK2.0以上，发卡机型号RW-IC-32C。
..\RFDLL\USB接口\ICDLL.dll
接口函数库文件,RF门锁,适用门锁管理软件LS-RF-CN-ALL-ALLVer8.0以上，发卡机型号RW-RF-34U
..\RFDLL\ver6.33兼容\ICDLL.dll
接口函数库文件,RF门锁,适用门锁管理软件RF-NK6.33前升级为LS-RF-CN-ALL-ALLVer8.0以上版本时使用，其主要用于新老线路板混合使用的酒店，发卡机型号RW-RF-32C
..\RFDLL\ver8.1\ICDLL.dll
接口函数库文件,RF门锁,适用门锁管理软件LS-RF-CN-ALL-ALLVer8.0以上，发卡机型号RW-RF-32C
..\MFDLL\Ver3.3\ICDLL.dll
接口函数库文件,MF门锁，适用门锁管理软件LS-MF-CN-U-WLVer3.0-3.3，发卡机型号RW-M1-32C
..\MFDLL\Ver3.5\ICDLL.dll
接口函数库文件,MF门锁，适用门锁管理软件LS-MF-CN-U-WLVer3.5，发卡机型号RW-M1-32C
附加说明:
..\表示Demo.exe所在目录
WindowsAPI接口函数库说明
ICDLL.dll接口函数库包括4个函数，用于控制发卡机发行客人卡及读取客人卡。
函数调用采用stdcall方式，PMS集成应遵循该WindowsAPI标准。
函数名
函数说明
Init
接口初始化
IssueCard
发行客人卡
ReadCard
读取客人卡
CancelCard
注销客人卡（功能卡无法用该函数注销）
4WindowsAPI接口函数说明
Init–接口初始化
函数说明
用于初始化环境变量。
根据安装的门锁管理软件使用数据库设定版本类型；设定门锁软件的安装目录。
PMS每次运行后，调用其它接口函数前须调用一次，若门锁管理软件安装目录和类型没有发生变化则只需调用一次。
语法–Delphi
functionInit（SoftType:
integer;SoftPath:
PChar）:
Boolean;
语法–C#
publicstaticexternBooleaninit（intSoftType,stringSoftPath）;
语法-PB
Functionbooleaninit（integerSoftType,refstringSoftPath）
语法-VB
FunctioninitLib"ICDLL.dll"（ByValSoftTypeAsInteger,ByValSoftPathAsString）AsBoolean
参数
[in]整型数，安装的门锁管理软件类型版本。
=0；ACESS数据库类型版本；
=1；SQL2000数据库类型版本。
[in]字符指针，指向门锁管理软件安装路径字符串。
返回值
布尔值TrueorFalse
示例delphi
init（0,pchar（’C:
\ProgramFiles\RFsystem\RFsystem’））
示例c#
init（0,@”C:
\ProgramFiles\RFsystem\RFsystem”）
示例pb
init（0,”C:
\ProgramFiles\RFsystem\RFsystem”）
示例vb
init（0,”C:
\ProgramFiles\RFsystem\RFsystem”）
附加说明
此路径为锁管软件的安装路径
IssueCard–发行客人卡
函数说明
用于发行客人卡。
发行成功后，更新数据库，记录相应客人信息、发卡操作员信息。
返回发行结果。
语法–Delphi
functionIssueCard（RoomNo,GuestInfo:
ShortString,OpInfo:
pchar,Loss:
Integer;CheckIn,CheckOut:
pchar）:
Integer;
语法–c#
publicstaticexternintIssueCard（stringRoomNo,stringGuestInfo,stringOpInfo,intLoss,DateTimeCheckIn,DateTimeCheckOut）;
语法–PB
functionlongIssueCard（refstringRoomNo,refstringGuestInfo,refstringOpInfo,intLoss,refstringCheckIn,refstringCheckOut）Library"icdll.dll"
语法–VB
PublicDeclareFunctionIssueCardLib"ICDLL.dll"（ByValRoomNoAsString,ByValGuestInfoAsString,ByValOpInfoAsString,ByValLossAsInteger,ByValCheckInAsString,ByValCheckOutAsString）AsInteger
参数
[in]字符指，房间号，长度不大于20。
注意须与门锁管理软件设定房间号码一致，且不能为空。
[in]字符指，客人信息，可以为空。
[in]字符指，操作员信息，可以为空。
[in]整数型，指示是否需要设定挂失。
设定挂失，该卡首次开门后之前发行的客人卡即失效。
一般新客人入住发行首张客人卡须设定挂失；复制发行已入住客人卡不得设定挂失，除非已入住客人主动挂失后重发客人卡。
=0；不设定挂失；
=1；设定挂失。
[in]字符指针，入住时间。
格式yymmddhhmm
[in]字符指针，退房时间。
格式yymmddhhmm
返回值
=0，1，2，3，4，9，10，11，15，85，86，87，89
示例delphi
IssueCard（pchar（’8101’）,pchar（’张三’）,pchar（’李四’）,0,pchar（‘0904011011’）,pchar（‘0904021011’））
示例c#
IssueCard（”8101”,”张三”,”李四”,0,2009-1-18：
00：
00,2009-1-212：
00）
示例pb
IssueCard（”8101”,”张三”,”李四”,0,“0901010800”,“0901021200”）
示例vb
IssueCard（”8101”,”张三”,”李四”,0,“0901010800”,“0901021200”）
附加说明
1、房号为锁管软件中房号设置中设置的房号，可在主界面中或者房号设置界面中找到。
2、酒店第一个入住的客人发行的是新卡
3、酒店发行同住的客人时发行的是加卡（复制卡）
4、酒店发行新卡时，传入的入住时间为第一个客人的入住时间，挂失标志位必须为1。
5、酒店发行加卡（复制卡）时，传入的入住时间为在住的上一个客人的新卡的入住时间，挂失标志必须为0。
6、当酒店有客人在住，但是客人把卡片弄丢了，要补卡，此时酒店必须发行的是新卡。
7、补卡完成后再次发行同住卡片则必须发行加卡（复制卡）。
8、卡片要被挂失2张卡之间的入住时间必须相差大于1分钟，而且时间较晚的卡必须带有挂失标志。
9、如果酒店使用退房卡，则锁管软件中的系统设置中的提前发卡必须设置为不提前（具体设置请参考使用手册中的系统设置部分）。
ReadCard–读取客人卡
函数说明
用于读取客人卡信息。
读取成功后，读取卡片上信息并查询数据库对应卡片发卡时记录的客人信息、发卡操作员信息。
返回读取结果。
语法–Delphi
functionReadCard（RoomNo,GuestInfo,OpInfo,CheckIn,CheckOut,CardNo:
pchar）:
Integer;
语法–C#
publicstaticexternintReadCard（StringBuilderRoomNo,StringBuilderGuestInfo,StringBuilderOpInfo,StringBuilderCheckIn,StringBuilderCheckOut,StringBuilderCardNo）;
语法–PB
FunctionlongReadCard（refstringRoomNo,refstringGuestInfo,refstringOpInfo,refstringCheckIn,refstringCheckOut,refstringCardNo）Library"ICDLL.dll"
语法–VB
PublicDeclareFunctionReadCardLib"ICDLL.dll"（ByValRoomNoAsString,ByValGuestInfoAsString,ByValOpInfoAsString,ByValCheckInAsString,ByValCheckOutAsString,ByValCardNoAsString）AsInteger
参数
[Out]字符指针，房间号。
[Out]字符指针，客人信息。
[Out]字符指针，操作员信息。
[Out]字符指针，入住时间。
[Out]字符指针，退房时间。
[Out]字符指针，卡号（MF为物理卡号,,RF为流水号,IC为我厂出厂时的一个固定的序号）
返回值
=0，1，2，3，4，7，9，10，15，85，86，87，89
示例delphi
ReadCard（RoomNo,GuestInfo,OpInfo,CheckIn,CheckOut,CardNo）
示例c#
ReadCard（RoomNo,GuestInfo,OpInfo,CheckIn,CheckOut,CardNo）
示例pb
ReadCard（RoomNo,GuestInfo,OpInfo,CheckIn,CheckOut,CardNo）
示例vb
ReadCard（RoomNo,GuestInfo,OpInfo,CheckIn,CheckOut,CardNo）
CancelCard–注销客人卡
函数说明
注销客人卡,使卡片回复新卡状态，并更新数据库。
该函数不能注销功能卡
语法–Delphi
functionCancelCard（OpInfo:
pchar）:
Integer;
语法–C#
publicstaticexternintCancelCard（stringOpInfo）;
语法–PB
functionintCancelCard（refstringOpInfo）library“icdll.dll”
语法–VB
PublicDeclareFunctionCancelCardLib“ICDLL.dll”（ByValOpInfoAsString）AsInteger
参数
[in]字符指针，操作员信息。
返回值
=0，1，2，3，4，7，9，10，15，85，86，87，88，89
示例delphi
CancelCard（pchar（’张三’））
示例c#
CancelCard（“张三”）
示例pb
CancelCard（“张三”）
示例vb
CancelCard（“张三”）
WindowsAPI接口示例使用说明
打开软件接口说明示例文件，
根据安装的锁管软件找到相应的动态库文件，选择软件类型，如果锁管软件为单机版则软件类型选择ACESS,如果为网络类型则选择SQL2000：
在桌面的锁管软件快捷方式上右键-属性单击查找目标按钮。
将地址栏中的地址复制到示例当中的软件安装路径：
然后单击初始化按钮进行初始化，初始化完成之后即可对卡片进行读写注销等操作
5WindowsAPI接口返回值说明
返回值
返回值说明及故障原因
排错方法
0
操作成功
1
无卡。
查看卡片位置是否放好
2
非法卡。
人工注销后，重新发行使用。
3
授权错误。
必须返回厂或代理商处重新初始化
4
串口通信错误。
发卡机串口连接中断；串口被其它程序占用；连续多次调用函数时未插入延时。
检查发卡机连接；更改门锁管理软件串口或其它程序串口设置；连续调用函数时插入500毫秒以上延时。
7
新卡。
读卡或注销时返回的一个值，表示该卡无须注销
9
非客人卡。
使用门锁管理软件进行注销卡操作。
（接口只提供客人卡操作，非客人卡则会提示此信息）
10
调用错误。
检查调用函数语法、输入参数类型、拼写。
11
房号不存在
检查传入的房间号码是否正确
15
数据库连接错误。
检查Init函数输入参数；SQL数据库用户密码设定（此为和门锁软件数据库同步连接，如果传入参数错误则无法建立连接）。
85
系统日前错误。
重新计算升迁号
86
未计算升迁号。
计算升迁号
87
系统过期。
重新计算升迁号
89
升迁号被破坏。
重新计算升迁号
6.TCP/IP接口
6.1接口特点以及接口使用条件
该接口特点在于可以通过网络控制安装了发卡机设备的电脑完成发卡，无须在每台电脑上安装发卡机设备。
正常使用该接口必须满足如下要求：
6.1.1首先安装创佳门锁公司提供的门锁软件，正常运行软件，发行各种设置卡（包括：
授权卡、时钟卡、房号卡），使用设置卡完成门锁设置（如果有多台电脑发卡，则每台电脑都必须安装我们门锁软件并注册，然后用主电脑上的授权卡恢复授权，详细操作请参考门锁设置说明）。
6.1.2使用windows98/2000/XP操作系统.
6.2TCP/IP接口文件如下表:
文件名
文件说明
Server.exe
服务端可执行文件（在服务器端运行，唯一）
Client.exe
客户端可执行文件（在客户端运行，每个客户端一个）
Computer.mdb
数据库（客户端与网络端都需要）
..\ICDLL\ICDLL.dll
客户端库文件,IC门锁
..\RFDLL\ICDLL.dll
客户端库文件,RF门锁
..\MFDLL\ICDLL.dll
客户端库文件,MF门锁
附加说明:
..\表示server.exe文件所在目录
该协议采用TCP/IP协议，接口使用方利用SocketClient按照固定格式发送数据和指令，接口系统（SocketServer）实时响应。
接口网络系统包括服务端（server.exe,computer.MDB）与客户端（client.exe,icdll.dll,computer.mdb）两部分。
服务端完成通信管理、参数设置、客户端管理等功能，接口网络只能有一个服务管理端（即服务端只能安装一台计算机）。
客户端是发卡端，完成发卡与信息显示功能，安装在发卡工作站或读卡与信息显示工作站上。
客户端数量不受任何限制，可以安装在所有需要发卡的工作站上，不同工作站也可以共用一个客户端发卡。
酒店管理系统与接口服务端通信，接口服务端接收指令并分配到指定客户端执行。
客户端执行命令后将执行状态反馈到服务端，服务端再将执行状态转换为应答信息回应酒店管理系统。
7TCP/IP数据通讯协议
7.1控制字符
STX（0x02）：
用于标记数据记录的开始。
ETX（0x03）：
用于标记数据记录的结束。
RS（0x7C）：
即分割符’|’，用于标记新字段（域）的开始，其后紧跟字段标识码。
7.2信息格式
信息格式为：
ddssff[data]。
信息域
说明
dd
目标地址，目标（客户端）地址（此地址为服务器添加客户端数据中的发行机编号）
ss
源地址，标明信息来源（此地址为服务器添加客户端数据中的发行机编号）
ff
命令或应答代码
[data]
数据区（非必须）
目标地址：
2字节，有效值00-99，接收信息的目的地址或指定执行命令的客户端。
源地址：
2字节，有效值00-99（00系统保留），标明信息来源。
例子说明：
假如在server.exe中添加了客户端2个客户端发行机编号01电脑名称为c1,发行机编号02电脑名称为c2,如果从c1电脑要在c2电脑上发行卡，则dd为02ss为01.
命令代码：
1字节，ASCII码，指定执行的命令。
B-客人退房（注销卡）
E-读卡
G-客人入住（发卡）
I-新客人入住（发卡，同时将在住客人退房）
应答代码：
1-2字节，ASCII码，指定命令执行的结果。
0-成功完成
1-未确定的错误
2-错误的（无效的）目标地址
3-无效的命令代码
4-串口错误
5-发行机正忙
6-无效的客房
7-新卡
8-发行机等候超时
10-无效的时间
11-客户端没有连接
12-客户端通信错误
数据区（data）：
数据可根据需要给出不同数据，格式为：
|data。
|（0x7C即分割符’|’）标明字段（域）开始。
字段（域）标识，1-2字节ASCII码，标明字段（域）数据意义。
字段ID
说明
数据长度
格式
示例
R（0x52）
房号
1-7
803
D（0x44）
客人入住时间
12
yyyymmddhhnn
200405081200
O（0x4F）
客人预离时间
12
yyyymmddhhnn
200410011200
N（0x4E）
客人姓名
1-30
C（0x43）
发卡数量
1
仅数字
7.3命令详解
以下示例中LIS（LocstarInterfaceSystem）代表创佳接口系统，PMS代表酒店管理系统接口，<>括号括起来的部分代表1字节的控制字符。
7.3.1客人入住/退房命令
新客人入住（I）：
此命令首先将指定房间内所有客人退房（仅数据库操作，不注销客人卡）再发行新的客人卡。
此命令仅适用于第一位客人入住，在同一房间添加客人请使用“客人入住”命令。
必须字段：
R,N,D,O；可选字段：
P。
示例：
PMS：
0103I|R101|P00|NDuck|D200212201200|O200212302100
LIS：
03010
客人入住（G）：
此命令根据指定房间和时间发行客人卡（当前在住客人不受任何影响）。
必须字段：
R,N,D,O；可选字段：
P。
示例：
PMS：
0103G|R102|P00|NDu|D200212201200|O200212302100
LIS：
03010
客人退房（B）：
此命令将指定房间内客人退房。
必须字段：
R；可选字段：
N。
此命令的dd（目标地址）有特殊用途，当dd为‘00’时只将客人退房不注销客人卡，当dd为合法地址时，将客人退房并注销客人卡（磁卡客人卡且使用手动发行机不予注销）。
不包括N（客人姓名）时将房间内所有客人退房，包括客人姓名时将房间内指定客人退房。
示例：
PMS：
0000B|R101
LIS：
00000
7.3.2验卡/读客人卡命令
命令码（E），此命令读客人卡信息，并从数据库中检索卡信息。
若检索成功，将相关信息（R,P,N,D,O）返回。
示例：
PMS：
0103E
LIS：
03010|R101|P010203|NDuck|D200212201200|O200212302100
2.4TCP/IP接口数据传输规则
（1）接口系统为SocketServer，酒店系统为SocketClient。
（2）双方必须设置相同的端口号。
（3）接口系统对每一个请求都有应答，应检查应答信息，以确定请求是否成功完成。
建议接口使用方等待接口系统回应时使用“超时跳出”的方式，防止系统异常造成的意外中断引发死循
升级会员 