酒店门锁管理系统接口说明.docx

1、酒店门锁管理系统接口说明深圳市同创新佳科技有限公司技术文件 LS-PMS酒店门锁管理系统集成发卡接口说明书Hotel Locks Management SystemPMS Integrate Keycards EncodeSDK User Guide版本号：2.0版本号发布日期制定审核批准V1.02009-03-31V2.02010-06-26前 言本说明书由深圳市同创新佳科技有限公司提出。本说明书主要起草单位：深圳市同创新佳科技有限公司技术部。本说明书主要起草人：颜炜东、凌彬。本说明书于2009年3月25日首次制定。修订记录版本号修订内容日期批准1.0首次制定2009-3-252.0新增示例

2、应用说明，接口适用版本2010-06-26LS-PMS酒店门锁管理系统集成发卡接口说明书Hotel Locks Management System PMS Integration Keycards Encode SDK User Guide1目的和范围该接口主要为酒店管理软件与我公司的读写卡设备提供标准的接口，以便酒店管理软件可以通过该接口对我公司设备进行操作。2系统组成Windows API接口与TCP/IP接口.系统结构Windows API接口系统结构:TCP/IP接口系统结构:3Windows API接口接口特点以及接口使用条件该接口具有单机与网络2种接口，其特点是不管是单机还是网络接

3、口，每个接口都必须安装一台发卡机，只能在安装了发卡机的电脑上调用ICDLL动态库完成制卡操作。正常使用该接口必须满足如下要求：3.1.1首先安装 创佳门锁公司提供的门锁软件，正常运行软件，发行各种设置卡（包括：授权卡、时钟卡、房号卡），使用设置卡完成门锁设置（如果有多台电脑发卡，则每台电脑都必须安装我们门锁软件并注册，然后用主电脑上的授权卡恢复授权，详细操作请参考门锁设置说明）。3.1.2使用前先调用初始化函数初始化软件使用环境即调用init函数3.1.3使用windows98/2000/XP操作系统.3.1.4 动态库ICDLL.dllWindows API接口文件说明Windows API

4、接口文件如表:文件名文件说明Demo.exe接口示例可执行文件.ICDLLVer4.2ICDLL.dll接口函数库文件,IC门锁,适用门锁管理软件IC-NK2.0以上，发卡机型号RW-IC-32C。.RFDLLUSB接口ICDLL.dll接口函数库文件,RF门锁, 适用门锁管理软件LS-RF-CN-ALL-ALL Ver8.0以上，发卡机型号RW-RF-34U.RFDLLver6.33兼容ICDLL.dll接口函数库文件,RF门锁, 适用门锁管理软件RF-NK6.33前升级为LS-RF-CN-ALL-ALL Ver8.0以上版本时使用，其主要用于新老线路板混合使用的酒店，发卡机型号RW-RF-

5、32C.RFDLLver8.1ICDLL.dll接口函数库文件,RF门锁, 适用门锁管理软件LS-RF-CN-ALL-ALL Ver8.0以上，发卡机型号RW-RF-32C.MFDLLVer3.3ICDLL.dll接口函数库文件,MF门锁，适用门锁管理软件LS-MF-CN-U-WL Ver3.0-3.3，发卡机型号RW-M1-32C.MFDLLVer3.5ICDLL.dll接口函数库文件,MF门锁，适用门锁管理软件LS-MF-CN-U-WL Ver3.5，发卡机型号RW-M1-32C附加说明:.表示Demo.exe所在目录Windows API接口函数库说明ICDLL.dll接口函数库包括4个

6、函数，用于控制发卡机发行客人卡及读取客人卡。函数调用采用stdcall方式，PMS集成应遵循该Windows API标准。函数名函数说明Init接口初始化IssueCard发行客人卡ReadCard读取客人卡CancelCard注销客人卡(功能卡无法用该函数注销)4Windows API接口函数说明Init 接口初始化函数说明用于初始化环境变量。根据安装的门锁管理软件使用数据库设定版本类型；设定门锁软件的安装目录。PMS每次运行后，调用其它接口函数前须调用一次，若门锁管理软件安装目录和类型没有发生变化则只需调用一次。语法 Delphifunction Init(SoftType:integer

7、; SoftPath:PChar ):Boolean;语法 C#public static extern Boolean init(int SoftType,string SoftPath);语法-PBFunction boolean init (integer SoftType,ref string SoftPath)语法-VBFunction init Lib ICDLL.dll (ByVal SoftType As Integer, ByVal SoftPath As String) As Boolean参数in 整型数，安装的门锁管理软件类型版本。 = 0；ACESS数据库类型版本；

8、= 1；SQL2000数据库类型版本。in 字符指针，指向门锁管理软件安装路径字符串。返回值布尔值 True or False示例delphiinit(0,pchar( C:Program FilesRF systemRF system)示例c#init(0,”C:Program FilesRF systemRF system”)示例pbinit(0,” C:Program FilesRF systemRF system”)示例vbinit(0,” C:Program FilesRF systemRF system”)附加说明此路径为锁管软件的安装路径IssueCard 发行客人卡函数说明用于

9、发行客人卡。发行成功后，更新数据库，记录相应客人信息、发卡操作员信息。返回发行结果。语法 Delphifunction IssueCard(RoomNo, GuestInfo:ShortString, OpInfo: pchar, Loss:Integer; CheckIn, CheckOut: pchar):Integer;语法 c#public static extern int IssueCard(string RoomNo, string GuestInfo, string OpInfo, int Loss, DateTime CheckIn, DateTime CheckOut);语

10、法 PBfunction long IssueCard (ref string RoomNo,ref string GuestInfo,ref string OpInfo, int Loss,ref string CheckIn,ref string CheckOut) Library icdll.dll语法 VBPublic Declare Function IssueCard Lib ICDLL.dll (ByVal RoomNo As String, ByVal GuestInfo As String, ByVal OpInfo As String, ByVal Loss As Inte

11、ger, ByVal CheckIn As String, ByVal CheckOut As String) As Integer参数in 字符指，房间号，长度不大于20。注意须与门锁管理软件设定房间号码一致，且不能为空。in 字符指，客人信息，可以为空。in 字符指，操作员信息，可以为空。in 整数型，指示是否需要设定挂失。设定挂失，该卡首次开门后之前发行的客人卡即失效。一般新客人入住发行首张客人卡须设定挂失；复制发行已入住客人卡不得设定挂失，除非已入住客人主动挂失后重发客人卡。 = 0；不设定挂失； = 1；设定挂失。in 字符指针，入住时间。格式yymmddhhmmin 字符指针，退房

12、时间。格式yymmddhhmm返回值= 0，1，2，3，4，9，10，11，15，85，86，87，89示例delphiIssueCard（pchar(8101),pchar(张三),pchar(李四),0, pchar(0904011011), pchar(0904021011)）示例c#IssueCard（”8101”,”张三”,”李四”,0, 2009-1-1 8：00：00, 2009-1-2 12：00）示例pbIssueCard（”8101”,”张三”,”李四”,0, “0901010800”, “0901021200”）示例vbIssueCard（”8101”,”张三”,”李四”

13、,0, “0901010800”, “0901021200”）附加说明1、房号为锁管软件中房号设置中设置的房号，可在主界面中或者房号设置界面中找到。2、酒店第一个入住的客人发行的是新卡3、酒店发行同住的客人时发行的是加卡（复制卡）4、酒店发行新卡时，传入的入住时间为第一个客人的入住时间，挂失标志位必须为1。5、酒店发行加卡（复制卡）时，传入的入住时间为在住的上一个客人的新卡的入住时间，挂失标志必须为0。6、当酒店有客人在住，但是客人把卡片弄丢了，要补卡，此时酒店必须发行的是新卡。7、补卡完成后再次发行同住卡片则必须发行加卡（复制卡）。8、卡片要被挂失2张卡之间的入住时间必须相差大于1分钟，而且

14、时间较晚的卡必须带有挂失标志。9、如果酒店使用退房卡，则锁管软件中的系统设置中的提前发卡必须设置为不提前（具体设置请参考使用手册中的系统设置部分）。ReadCard 读取客人卡函数说明用于读取客人卡信息。读取成功后，读取卡片上信息并查询数据库对应卡片发卡时记录的客人信息、发卡操作员信息。返回读取结果。语法 Delphifunction ReadCard(RoomNo, GuestInfo, OpInfo, CheckIn, CheckOut, CardNo:pchar):Integer;语法 C#public static extern int ReadCard(StringBuilder R

15、oomNo, StringBuilder GuestInfo, StringBuilder OpInfo, StringBuilder CheckIn, StringBuilder CheckOut, StringBuilder CardNo);语法 PBFunction long ReadCard (ref string RoomNo, ref string GuestInfo, ref string OpInfo, ref string CheckIn, ref string CheckOut, ref string CardNo) Library ICDLL.dll语法 VBPublic

16、 Declare Function ReadCard Lib ICDLL.dll (ByVal RoomNo As String, ByVal GuestInfo As String, ByVal OpInfo As String, ByVal CheckIn As String, ByVal CheckOut As String, ByVal CardNo As String) As Integer参数Out 字符指针，房间号。Out 字符指针，客人信息。Out 字符指针，操作员信息。Out 字符指针，入住时间。Out 字符指针，退房时间。Out 字符指针，卡号(MF为物理卡号,RF为流水号

17、,IC为我厂出厂时的一个固定的序号)返回值= 0，1，2，3，4，7，9，10，15，85，86，87，89示例delphiReadCard(RoomNo,GuestInfo,OpInfo,CheckIn,CheckOut,CardNo)示例c#ReadCard(RoomNo, GuestInfo, OpInfo, CheckIn, CheckOut, CardNo)示例pbReadCard(RoomNo, GuestInfo, OpInfo, CheckIn, CheckOut, CardNo)示例vbReadCard(RoomNo, GuestInfo, OpInfo, CheckIn,

18、CheckOut, CardNo)CancelCard 注销客人卡函数说明注销客人卡,使卡片回复新卡状态，并更新数据库。该函数不能注销功能卡语法 Delphifunction CancelCard(OpInfo:pchar):Integer;语法 C#public static extern int CancelCard(string OpInfo);语法 PBfunction int CancelCard (ref string OpInfo) library “icdll.dll”语法 VBPublic Declare Function CancelCard Lib “ICDLL.dll”

19、 (ByVal OpInfo As String) As Integer参数in 字符指针，操作员信息。返回值= 0，1，2，3，4，7，9，10，15，85，86，87，88，89示例delphiCancelCard(pchar(张三)示例c#CancelCard(“张三”)示例pbCancelCard(“张三”)示例vbCancelCard(“张三”)Windows API接口示例使用说明打开软件接口说明示例文件，根据安装的锁管软件找到相应的动态库文件，选择软件类型，如果锁管软件为单机版则软件类型选择ACESS,如果为网络类型则选择SQL2000：在桌面的锁管软件快捷方式上右键-属性 单击

20、 查找目标 按钮。将地址栏中的地址复制到示例当中的软件安装路径：然后单击初始化按钮进行初始化，初始化完成之后即可对卡片进行读写注销等操作5Windows API接口返回值说明返回值返回值说明及故障原因排错方法0操作成功1无卡。查看卡片位置是否放好2非法卡。人工注销后，重新发行使用。3授权错误。必须返回厂或代理商处重新初始化4串口通信错误。发卡机串口连接中断；串口被其它程序占用；连续多次调用函数时未插入延时。检查发卡机连接；更改门锁管理软件串口或其它程序串口设置；连续调用函数时插入500毫秒以上延时。7新卡。读卡或注销时返回的一个值，表示该卡无须注销9非客人卡。使用门锁管理软件进行注销卡操作。(

21、接口只提供客人卡操作，非客人卡则会提示此信息)10调用错误。检查调用函数语法、输入参数类型、拼写。11房号不存在检查传入的房间号码是否正确15数据库连接错误。检查Init函数输入参数；SQL数据库用户密码设定（此为和门锁软件数据库同步连接，如果传入参数错误则无法建立连接）。85系统日前错误。重新计算升迁号86未计算升迁号。计算升迁号87系统过期。重新计算升迁号89升迁号被破坏。重新计算升迁号6. TCP/IP接口6.1 接口特点以及接口使用条件该接口特点在于可以通过网络控制安装了发卡机设备的电脑完成发卡，无须在每台电脑上安装发卡机设备。正常使用该接口必须满足如下要求：6.1.1首先安装 创佳门

22、锁公司提供的门锁软件，正常运行软件，发行各种设置卡（包括：授权卡、时钟卡、房号卡），使用设置卡完成门锁设置（如果有多台电脑发卡，则每台电脑都必须安装我们门锁软件并注册，然后用主电脑上的授权卡恢复授权，详细操作请参考门锁设置说明）。6.1.2使用windows98/2000/XP操作系统.6.2 TCP/IP接口文件如下表:文件名文件说明Server.exe服务端可执行文件(在服务器端运行，唯一)Client.exe客户端可执行文件(在客户端运行，每个客户端一个)Computer.mdb数据库（客户端与网络端都需要）.ICDLLICDLL.dll客户端库文件,IC门锁.RFDLLICDLL.dl

23、l客户端库文件,RF门锁.MFDLLICDLL.dll客户端库文件,MF门锁附加说明:.表示server.exe文件所在目录该协议采用TCP/IP协议，接口使用方利用Socket Client按照固定格式发送数据和指令，接口系统（Socket Server）实时响应。接口网络系统包括服务端（server.exe, computer.MDB）与客户端（client.exe,icdll.dll, computer.mdb）两部分。服务端完成通信管理、参数设置、客户端管理等功能，接口网络只能有一个服务管理端（即服务端只能安装一台计算机）。客户端是发卡端，完成发卡与信息显示功能，安装在发卡工作站或读卡

24、与信息显示工作站上。客户端数量不受任何限制，可以安装在所有需要发卡的工作站上，不同工作站也可以共用一个客户端发卡。酒店管理系统与接口服务端通信，接口服务端接收指令并分配到指定客户端执行。客户端执行命令后将执行状态反馈到服务端，服务端再将执行状态转换为应答信息回应酒店管理系统。7 TCP/IP数据通讯协议 7.1控制字符STX（0x02）：用于标记数据记录的开始。ETX（0x03）：用于标记数据记录的结束。RS （0x7C）：即分割符|，用于标记新字段（域）的开始，其后紧跟字段标识码。7.2 信息格式信息格式为：ddssffdata。信息域说明dd目标地址，目标（客户端）地址(此地址为服务器添加

25、客户端数据中的发行机编号)ss源地址，标明信息来源(此地址为服务器添加客户端数据中的发行机编号)ff命令或应答代码data数据区（非必须）目标地址：2字节，有效值00-99，接收信息的目的地址或指定执行命令的客户端。源地址：2字节，有效值00-99（00系统保留），标明信息来源。例子说明：假如在server.exe中添加了客户端2个客户端 发行机编号 01 电脑名称为 c1 , 发行机编号 02 电脑名称为 c2,如果从c1电脑要在c2电脑上发行卡，则dd 为 02 ss 为 01.命令代码：1字节，ASCII码，指定执行的命令。B-客人退房（注销卡）E-读卡G-客人入住（发卡）I-新客人入住

26、（发卡，同时将在住客人退房）应答代码：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-7803D(0x44)客人入住时间12yyyymmddhhnn200405081200O(0x

27、4F)客人预离时间12yyyymmddhhnn200410011200N(0x4E)客人姓名1-30C(0x43)发卡数量1仅数字7.3 命令详解以下示例中LIS（Locstar Interface System）代表创佳接口系统，PMS代表酒店管理系统接口，括号括起来的部分代表1字节的控制字符。7.3.1 客人入住/退房命令新客人入住（I）：此命令首先将指定房间内所有客人退房（仅数据库操作，不注销客人卡）再发行新的客人卡。此命令仅适用于第一位客人入住，在同一房间添加客人请使用 “客人入住”命令。必须字段：R,N,D,O；可选字段：P。示例：PMS：0103I|R101|P00|NDuck|D

28、200212201200|O200212302100LIS：03010客人入住（G）：此命令根据指定房间和时间发行客人卡（当前在住客人不受任何影响）。必须字段：R,N,D,O；可选字段：P。示例：PMS：0103G|R102|P00|NDu|D200212201200|O200212302100LIS：03010客人退房（B）：此命令将指定房间内客人退房。必须字段：R；可选字段：N。此命令的dd（目标地址）有特殊用途，当dd为00时只将客人退房不注销客人卡，当dd为合法地址时，将客人退房并注销客人卡（磁卡客人卡且使用手动发行机不予注销）。不包括N（客人姓名）时将房间内所有客人退房，包括客人姓名

29、时将房间内指定客人退房。示例：PMS：0000B|R101LIS：000007.3.2 验卡/读客人卡命令命令码（E），此命令读客人卡信息，并从数据库中检索卡信息。若检索成功，将相关信息（R,P,N,D,O）返回。示例：PMS：0103ELIS：03010|R101|P010203|NDuck|D200212201200|O2002123021002.4 TCP/IP接口数据传输规则（1）接口系统为Socket Server，酒店系统为Socket Client。（2）双方必须设置相同的端口号。（3）接口系统对每一个请求都有应答，应检查应答信息，以确定请求是否成功完成。建议接口使用方等待接口系统回应时使用“超时跳出”的方式，防止系统异常造成的意外中断引发死循