中控售饭机SDK用户手册.docx

案卷号

日期

用 户 手 册
作者：
完成日期：
签收人：
签收日期：
修改情况记录：
版本号
修改批准人
修改人
安装日期
签收人

目录
1 SDK开发说明1
1.1 简介1
1.2 背景1
1.3 定义1
1.4 SDK 安装1
接口调用流程7
l修改密码（加密）7
l初始化IC卡（清空IC卡）8
l发卡8
l读卡9
l充值10
2 数据结构说明11
2.1 消费机器数据结构11
l消费机中数据表说明：11
l数据添加格式16
2.2 卡片数据结构16
2.3 状态报告16
l返回状态码及意义16
3 SDK开发函数说明18
3.1 消费机器sdk开发函数18
3.2 卡操作sdk卡发函数18
l1． ZK_PosClearICCard18
l2．ZK_PosIssueICCard18
l3．ZK_PosReadICCard19
l4．ZK_PosWriteICCardMoney19
l5．ZK_PosWriteICCardPassWord19
l6．ZK_PosUpdateParam20
l7．ZK_PosReadCardSerial20
4 开发建议20
1 SDK开发说明
1.1 简介
SDK：是针对独立软件开发商（ISV）和系统集成商（SI）的软件开发
及技术产品服务的需求，提供的消费软件系统与消费机及IC卡读写器通讯的开发组件（SDK，Software Development Kit)
1.2 背景
Ø 系统名称：SDK消费系统开发组件
1.3 定义
Ø 参数KEY值卡密码,格式为每个字节密码以逗号分隔如“FF,FF,FF,FF,FF,FF”， 每个字节是该数字的ASCII码的16进制表示形式，如：卡密码是123456，那么转化后为“31，32，33，34，35，36 ”， 所有函数的卡密码格式相同，不在赘述
1.4 SDK 安装
l 使用消费机sdk接口函数需要用到多个动态库文件，详见“消费机dll库”文件夹，把该文件夹的所以dll文件放到工程目录下即可，具体应用参考例程
l 使用卡操作sdk时，采用ocx控件形式，需要安装本公司提供的驱动程序获得控件库文件。驱动程序在“控件”文件夹中,安装好驱动后，默认目录（xp系统）在c:\windows\system32下找到以下两个文件。
Biokey.ocx 控件库文件
控件库文件
l 分别注册控件控件库文件：
regsvr32.exe c:\windows\system32\
regsvr32.exe c:\windows\system32\ZKO
注意：Windows Vista客户需要以管理员权限才能正确执行regsvr32；
l 注册成功后，就可以在相应的开发环境中导入控件。
A：在Delphi 7 开发环境:
第一步：ComponentàImport Activex Control…如下图所示：

进入如下界面，按下图所示操作，安装两个控件

B：在Microsoft Visual Studio .NET 2003的VB项目中
第一步：注册控件，如下图所示进入注册界面

然后进入ActiveX控件测试容器界面，如下图：

选择“文件à注册控件”，找到注册文件，如下图所示：

注册成功后，多了刚才注册的选项，如下图所示：

第二步：添加控件到工具栏中，方法如下图所示：

添加好后，在控件里就添加好了该控件，如下图所示：

C：在中使用
第一步：注册控件，方法跟VB的类似。
第二步：使用控件，操作如下图所示

在下图中选择要插入的控件：

接口调用流程
接口调用流程如下：
Ø 消费机器接口调用流程
Ø IC卡操作业务流程
l 修改密码（加密）
连接发卡器
读取卡序列号
成功
修改主、备份扇区密码
结束
Y
N
没有找到IC卡或卡是否损坏
判断是否白卡
白卡
Y
N

l 初始化IC卡（清空IC卡）
连接发卡器
读取卡序列号
成功
清空主、备份扇区密码
结束
Y
N
没有找到IC卡或卡是否损坏

l 发卡
连接发卡器
读取卡序列号
成功
判断是否白卡
结束
Y
N
没有找到IC卡或卡是否损坏
白卡
Y
判断各参数
正确
这不是一张空白卡，不能发卡。请将该卡先初始化!

发卡写主扇区
N
Y
N
成功
发卡写备份扇区
成功
清空主扇区卡信息块
N
N
Y
Y

l 读卡
连接发卡器
读取卡序列号
成功
解析数据
结束
Y
N
没有找到IC卡或卡是否损坏
读主扇区数据
成功
Y
N
读备份扇区数据
成功
Y
N

l 充值
N
Y
读卡
成功
写主扇区金额
结束
Y
N
判断充值参数
正确
N
Y
判断是否同一张
（读两次序列号）
同一卡
N
Y
成功
读主扇区金额
成功且写=读
写备份扇区金额
成功
读备份扇区金额
成功且写=读
执行次数< 10
Y
Y
Y
Y
N
N
N
N

2 数据结构说明
2.1消费机器数据结构
l 消费机中数据表说明：
1．UserInfo：（用户信息表）
字段名
说明
SysID
系统卡号
UserID
用户编号
PIN
用户工号
CardNo
卡号
Name
姓名
PassWord
差额密码
SegNo

UserType
用户类型(1黑名单,0白名单)
Privage
权限(1管理员,0普通用户)
2．Template：(指纹信息)
3．OpLog：（管理日志）
字段名
说明
OPID
操作员ID
TIME
操作时间
OP
操作编码
4．PosLog：（消费记录）
字段名
说明
SysID
系统卡号
CardNo
卡号
PosTime
消费时间
PosMoney
消费金额
Balance
余额
RecNo
机器流水号
CardRecID
卡流水号
State
消费类型
Mealtype
餐别
MealDate
记餐日期
OPID
操作员ID
5．PRESSKEY(键值信息表)
字段名
说明
KeyID
键值编号
Price
价格
6．StoreInfo：（商品信息）
字段名
说明
StoreNo
商品编号
Name
商品名称
Bc
条码
Price
价格
agio
折扣
7．Mealtype：（餐别信息）
字段名
说明
Mlid
餐别编号
Name
餐别名称
Start
开始时间
End
结束时间
8．TimeSeg：（就餐批次时间段信息）
字段名
说明
SegID
批次编号（1为固定时段）
TsID
时段编号
Start
开始时间
End
结束时间
9．FIXED（分段定值表）
字段名
说明
TsID
时段编号
Start
开始时间
End
结束时间
Price
价格
10．PayDetail：（商品消费明细信息， 商品消费时对应消费记录的明细信息）
字段名
说明
RecNo
机器流水号
StoreNo
商品编号
Price
实收价格
RecSum
单笔消费商品流水号
11．KEYDETAIL 键值消费明细表
字段名
说明
RecNo
机器流水号
KeyID
键值编号
Price
实收价格
RecSum
单笔消费商品流水号
12．TmPosLog：（记时消费数据）
字段名
说明
SysID
卡号
StartTme
开始时间
StartBanlance
开始金额
EndTime
结束时间
EndBanlance
结束金额（余额）
13．CARDTYPE（卡类设置表）
字段名
说明
SortID
卡类序号
Name
卡类名称
rebate
折扣
Timemaxmoney
次消费最大金额
Daymaxmoney
天消费最大金额
Mealmaxmoney
餐消费最大金额
Daymaxtimes
天消费最大次数
Mealmaxtimes
餐消费最大次数
Lowlimit
最小卡余额
Maxlimit
最大卡余额
MealType
可用餐别
Enable
是否可用
limit
有效天数
BatchNo
使用时段
UseFinger
是否使用指纹（1或0）
14．FULLVALUE（充值记录表）
字段名
说明
SysID
系统卡号
CardNo
卡号
CardRecNO
卡流水号
Money
充值金额
Balance
余额
LogType
充值类型
OPID
操作员ID
RecNo
机器流水号
15．SUBSIDYLOG（补贴流水记录表）
字段名
说明
SysID
系统卡号
CardNo
卡号
Batch
补贴批号
Money
补贴金额
allowDate
补贴日期
16．SIDYLOG（已补贴记成功录表）
字段名
说明
SysID
系统卡号
CardNo
卡号
CardRecID
卡流水号
Batch
补贴批号
AllowTime
补贴时间
AllowMoney
补贴金额
Balance
余额
state
补贴方式 0：清零补贴
BaseBatch
补贴基次
RecNo
机器流水号
17．SubSidy：（待补贴记录表）
字段名
说明
SysID
系统卡号
CardNo
卡号
Batch
补贴批号
AllowMoney
补贴金额
BaseBatch
补贴基次
allowDate
补贴日期
l 数据添加格式
向消费机中的表添加数据，是将记录组合成一个字符串发送到机器中的，字符串格式为：字段名=值（tab键）字段名=值…
记录与记录之间以换行符号连接
如商品资料的一条记录为“StoreNo=1 Name=包子Bc=464654646 Price=0.5 agio=80”，注意：字段之间是tab符号
从消费机读取的格式也相同，需要自行解析字符串，得到每条记录每个字段的数据。
2.2 卡片数据结构
l 读取卡片返回数据的组成结构
数据格式采用“字段名1=值1，字段名2=值2”的形式字段名为上述余额扇区结构说明中的字段名
2.3 状态报告
l 返回状态码及意义
-1:
Result := '传入参数非法';
-2:
Result := '主、备份扇区数据不一致';
1:
Result := '操作失败';
2:
Result := '数据丢包';
3:
Result := '没有选择准确的COM口';
4:
Result := '和卡通讯超时';
5, 7:
Result := 'XOR校验出错';
$A:
Result := '输入的参数大于最大允许范围，溢出';
$80:
Result := '参数设置成功';
$81:
Result := '参数设置失败';
$82:
Result := '通讯超时';
$83:
Result := '卡不存在';
$84:
Result := '接收卡数据出错';
$85:
Result := '输入参数或者输入命令格式错误';
$87:
Result := '未知的错误';
$8A:
Result := '在块初始化中出现错误';
$8B:
Result := '在防冲突过程中得到错误的序列号';
$8C:
Result := '密码认证没通过';
$8F:
Result := '读写设备接收到了未定义的命令';
$90:
Result := '卡不支持这个命令';
$91:
Result := '命令格式有错误';
$92:
Result := '在命令的FLAG参数中, 不支持OPTION模式';
$93:
Result := '要操作的BLOCK不存在';
$94:
Result := '要操作的对象已经别锁定, 不能进行修改';
$95:
Result := '锁定操作不成功';
$96:
Result := '写操作不成功';
l 用途
获得接口函数执行结果状态描述内容（适用与卡操作函数）
3SDK开发函数说明
3.1 消费机器sdk开发函数
详细参阅《dataapi接口使用指南》
3.2 卡操作sdk卡发函数
l 1．ZK_PosClearICCard
【功能】
对卡进行初始化，清除卡片数据，将扇区字节写为0X 00
【需要参数说明】
commHandle: int：无符号整型，发卡器端口资源句柄，默认为0
key: string：卡密码。
mainsec：整型，1—15，主扇区号，每个扇区的三个块
backsec：整型，1—15，备份扇区号，每个扇区的三个块
【返回值】
=0：初始化成功
<>0：其它见
l 2．ZK_PosIssueICCard
【功能】
对卡写数据，发放卡片
【需要参数说明】
commHandle：整型，发卡器设备句柄
key：卡密码
overPwd：整型，六位数字，超额密码
Cardno：整型，1—999999999，卡号
money：整型，初始金额，1—999900，
cardtype：整型，1—99，卡片类别号
batchNo：整型，卡片版本号
miansec：整型，1—15，主扇区号
backsec：整型，1—15，备份扇区号
【返回值】
=0：发卡成功
<>0：其它见
l 3．ZK_PosReadICCard
【功能】
读取卡片数据，数据包括卡号，余额等信息
【参数说明】
commHandle：整型，发卡器设备句柄，0
key：卡密码
miansec：整型，1—15，主扇区号
backsec：整型，1—15，备份扇区号
Data：字符串，返回读取的数据，数据格式采用“字段名1=值1，字段名2=值2”的形式
【返回值】
返回字符串”字段名1=值,字段名1=值”，可以判断字符串是否包含＝或字符串长度，不包含则失败，其它见
l 4．ZK_PosWriteICCardMoney
【功能】
对卡片写入金额充值，主扇区和备份扇区的 第二和第三块需要写成相同的数据。
【参数说明】
commHandle：无符号整型，发卡器设备句柄
key：卡密码
Money：整型，1—999900，写入金额
mainsect：整型。1—15，存储数据的主扇区号
backsec：整型，1—15，备份扇区号
【返回值】
=0：充值成功
<>1：其它见
l 5．ZK_PosWriteICCardPassWord
【功能】
修改卡密码
【参数说明】
commHandle：整型，发卡器设备句柄
oldkey：六位数字字符串，原卡密码
newkey：六位数字字符串，新密码
mainsect：整型。1—15，存储数据的主扇区号
backsec：整型，1—15，备份扇区号
【返回值】
=0：成功
<>1：其它见
l 6．ZK_PosUpdateParam
【功能】
修改卡片参数，可以修改卡片超额密码、发卡日期、卡类
【参数说明】
commHandle：无符号整型，发卡器设备句柄
key：卡密码
overPwd: 整型，新超额密码
issueDate:字符串，新发卡日期，如：2011-10-08
cardType：整型，new卡类
mainSec: int
backSec: int
【返回值】
=0：成功
<>1：失败，其它见
l 7．ZK_PosReadCardSerial
【功能】
读取卡片序列号
【参数说明】
commHandle：整型，发卡器设备句柄
【返回值】
字符串，正常为卡号可以通过判断字符串长度大于4，其它见
4开发建议
l 准备工作
合作伙伴必须通过中控科技或是中控科技代理商，取得SDK开发包和相关文档，及相关技术支持。
l 开发建议
Ø 获取开发包及 相关说明文档之后，可先看一下说明文档，之后运行开发包中的例程进行初步的试用。
Ø 调用SDK各接口时，需参考SDK使用说明文档 对接口返回值做相应的处理。
Ø 在实际的应用中，卡操作必须参考文档给出的业务流程去开发。因为sdk函数只执行底层的数据读写操作及简单的数据合法判断，未包括发作的业务流程，所以在开发调用的时候，必须按照上面的流程或实际的业务流程来执行，以保证数据的正确性。例如：A、卡片初始化函数，它只负责把卡里的数据清0 ，不管里面是有数据、是否在正常使用。B、发卡函数：该函数把新的数据写入卡中，如果卡内已有数据，将被覆盖，所以必须先弄清楚卡是否是白卡，是白卡才能发卡，等等。。。