MT明泰读卡器API接口函数库使用说明.docx
《MT明泰读卡器API接口函数库使用说明.docx》由会员分享，可在线阅读，更多相关《MT明泰读卡器API接口函数库使用说明.docx（83页珍藏版）》请在冰点文库上搜索。
MT明泰读卡器API接口函数库使用说明
MT明泰-读卡器-API接口函数库使用说明
D
V1.0.9
2014-06-03
二代证相关操作函数及调用说明完善
余菊萍
V1.0.10
2014-06-10
增加1604卡、删除二代证照片文件接口
杨亚军
V1.0.11
2014-06-17
增加二代证扩展二接口及设置保存二代证照片名字的接口
杨亚军
V1.0.12
2014-06-30
增加二代证接口扩展三及wlt转bmp函数
杨亚军
V1.0.1.3
2014-07-07
增加金融IC卡读姓名与卡号函数
蔡拔群
V1.0.14
2014-07-24
实现AT88SC1604卡伪个人化
杨亚军
V1.0.15
2014-11-06
修改二代证解码动态库动态加载失败的问题及磁条卡读取的BUG、添加二代证调用流程图
杨亚军
V1.0.16
2014-12-24
打开设备端口做了处理，如果已经打开就不再去打开,增加了获取接触、非接卡片是否存在、安全模块是否存在的
杨亚军
V1.0.17
2015-01-16
增加AT24C卡包括AT24C01、AT24C02、AT24C04、AT24C08、AT24C16、AT24C32、AT24C64、AT24C128、AT24C256
杨亚军
V1.0.18
2015-01-23
增加LED4个灯灭、亮、闪烁控制
杨亚军
V1.0.19
2015-01-27
增加非接触式CPU卡卡状态获取：
无卡、一张卡、多张卡
杨亚军
V1.0.20
2015-04-20
增加接触卡、非接A卡，非接B卡到位状态获取：
无卡、有卡
余菊萍
1.文档概述
1.1.文档范围
该手册主要介绍二代证读写器、相关接口函数库的使用以及相关API的介绍。
在附录中介绍了读写器支持的卡型的卡片特性。
1.2.面向对象
购买了二代证读写器，欲使用二代证读写器进行二次开发的开发人员。
1.3.参考资料
（农行）金融IC卡读写器通讯协议说明
2.函数库介绍
2.1.功能
API函数库提供了使用二代证读卡器对卡片操作时所用到的函数接口，包括以下几个方面：
A.设备操作函数组
B.接触式卡片操作函数
C.非接触式卡片操作函数
D.身份证操作函数
E.磁条卡操作函数
F.外挂键盘操作函数
2.2.性能
1.读写器通过串口或HID无驱设备与PC机进行通讯，不需要安装驱动程序。
2.API接口函数库封装了通过PC机来操作二代证读卡器时用到的各个函数，用户在执行操作时，只需调用相应的函数接口即可，不需要编写对读卡器的操作函数。
3.运行环境
3.1.硬设备
为运行本产品，您需要的硬设备的最小配置如下：
A.处理器：
80X86
B.内存：
64KB
C.硬盘：
2.0GB
D.USB接口一个
E.RS232串口一个
3.2.软件的运行平台
为运行本产品，您需要的支持软件如下：
A.操作系统：
Win7/WindowsVista/Win2003/WinXP/Win2000；
B.程序编写工具：
VC/VB/PB/Delphi等；
3.3.函数调用方法
3.3.1.Delphi调用32位动态库的方法
语法：
[PublicPrivate|protected]FunctionFunctionName（[Var][Arg1:
DataType1;][Arg2:
DataType2;...]）[:
ReturnDataType];far;stdcall;external‘libname’[NameAliasName];
调用语句的语法包含下面部分：
●关键字Public（可选），表示函数可以被程序代码中的任意部分访问。
●关键字Private（可选），表示函数在声明类的单元（源代码）外不能访问。
●关键字Protected（可选），表示保护函数，保护元素只能被当前类和它的子类访问。
●关键字Function（必选），表示调用函数，函数有返回值。
●FunctionName（必选），调用外部函数的名称，区分大小写。
●关键字Var（可选），表示通过引用传递参数，函数参数可以用值传递，也可以通过引用传递。
通过引用传递参数，它的值没被复制到存放函数例程参数的堆栈中，程序执行速度快。
通过引用传值，将允许过程和函数改变参数的值。
●ArgN:
DataTypeN（可选），参数名以及参数类型，传递的参数类型可以是：
Shorint，Smallint，Longint，Integer（16/32），Single，Double，Extended，Currency，Date，Pchar，Object，Variant等。
●ReturnType（可选），函数返回值的类型。
●Stdcall（必选），表示传递约定，这样调用模块（应用程序），与被调用模块（DLL）就使用相同的参数约定。
●关键字external（必选），声明访问外部函数。
●Libname（必选），访问的DLL名称，16位Delphi中外部声明不带扩展名的库名。
●Name‘AliasName’（可选），Name指令可以为外部函数起别名，避免与系统例程和函数名称冲突。
外部程序调用的DLL函数，必须遵照下列规则：
（1）必须列在DLL的exports子句中。
（2）在Delphi3中，调用函数还需被声明为stdcall，来使用标准的WIN32参数传递技术。
代替优化的register参数传递技术。
（3）在WIN32中，DLL可以使用全局数据，该数据将不会通过调用应用程序来分享，每当应用程序装载DLL时，它在自己的地址空间中存储着DLL的全部数据。
注：
详细请参考ICCard\EXAMPLES目录下的使用范例。
3.3.2.VB调用32位动态库的方法
语法：
[Public|Private]DeclareFunctionnameLib"libname"[Alias"aliasname"][（[arglist]）][Astype]
Declare语句的语法包含下面部分：
●Public（可选）用于声明在所有模块中的所有过程都可以使用的函数。
●Private（可选），用于声明只能在包含该声明的模块中使用的函数。
●Name（必选），任何合法的函数名。
动态链接库的入口处（entrypoints）区分大小写。
●Libname（必选），包含所声明的函数动态链接库名或代码资源名。
●Alias（可选），表示将被调用的函数在动态链接库（DLL）中还有另外的名称。
当外部函数名与某个函数重名时，就可以使用这个参数。
当动态链接库的函数与同一范围内的公用变量、常数或任何其它过程的名称相同时，也可以使用Alias。
如果该动态链接库函数中的某个字符不符合动态链接库的命名约定时，也可以使用Alias。
●Aliasname（可选）动态链接库。
如果首字符不是数字符号（#），则aliasname是动态链接库中该函数入口处的名称。
如果首字符是（#），则随后的字符必须指定该函数入口处的顺序号。
●Arglist（可选），代表调用该函数时需要传递参数的变量表。
●Type（可选），Function返回值的数据类型；可以是Byte、Boolean、Integer、Long、Currency、Single、Double、Decimal（目前尚不支持）、Date、String（只支持变长）或Variant，用户定义类型，或对象类型。
arglist参数的语法如下：
[Optional][ByVal|ByRef][ParamArray]varname[（）][Astype]
部分描述：
●Optional（可选），表示参数不是必需的。
如果使用该选项，则arglist中的后续参数都必需是可选的，而且必须都使用Optional关键字声明。
如果使用了ParamArray，则任何参数都不能使用Optional。
●ByVal（可选），表示该参数按值传递。
●ByRef（可选），表示该参数按地址传递。
●ParamArray（可选），只用于arglist的最后一个参数，表示最后参数是一个Variant元素的Optional数组。
使用ParamArray关键字可以提供任意数目的参数。
ParamArray关键字不能与ByVal、ByRef或Optional一起使用。
●Varname（必选），代表传给该函数参数的变量名；遵循标准的变量命名约定。
●（）对数组变量是必需的。
指明varname是一个数组。
●type（可选），传递给函数参数的数据类型；可以是除Decimal以外的任何类型。
说明：
Function的数据类型决定其返回值的数据类型。
可以在arglist之后使用As子句来指定函数返回值的数据类型。
在arglist中，可以使用As子句来指定任何传给该函数参数的数据类型。
不单可以指定为任何标准数据类型，还可以在arglist中指定AsAny来禁止类型检查，从而允许将任意数据类型传递给该函数。
空圆括号表示该Function没有参数，且VisualBasic应确保不会传递任何参数。
注意：
（1）当所调用的外部函数需要一个值为0的字符串时，就要使用vbNullString常数。
该常数与零长度字符串（""）是不相同的。
（2）VB5调用32位动态库，对于ASCII码值大于128的读写操作，请参考Examples中24系列的BYREF传递方式；16位动态库可以直接使用CHR函数转换。
（3）详细请参考ICCard\EXAMPLES目录下的使用范例。
3.3.3.VC调用32位动态库的方法
（1）在.CPP中包含“mtx_32.h”头文件；
（2）在工程文件中加入mtx_32.lib文件。
（3）在C:
\WINDOWS\system32或工程文件中加入GetInfo.dll文件。
4.API介绍
4.1.函数调用流程
4.1.1.非接触式存储卡API调用流程
建立连接成功后软件中基于Mifareone卡测试一般的操作过程是：
读数
建立连接->寻卡->验证写数据中止卡片
值操作
4.1.2.非接触式CPU卡片API调用流程
软件中基于非接触CPU卡片，一般的操作过程是：
建立连接成功->打开卡片->发送APDU命令->设置卡片状态为halt->中止卡片操作
4.1.3.接触式CPU卡片API调用流程
软件中基于接触式CPU卡片，一般的操作过程是：
建立连接成功->上电复位->获取卡片状态/发送APDU命令->卡片下电。
4.1.4.接触式存储卡片API调用流程
软件中基于接触式存储卡片，一般的操作过程是：
建立连接成功->设置存储卡种类->识别存储卡种类->密码校验->读数据/写数据/更改密码
4.1.5.身份证API调用流程
软件中基于身份证，一般的操作过程是：
目前我们的二代证接口有五套操作接口，下面分别对五套接口的操作流程都做一下详细描述，具体如下:
1.对于只需要读取二代证的情况，操作流程如下:
方案1、直接读取身份证信息的UNICODE码，通过返回的UNICODE码传入相关函数获取身份证信息。
建立连接成功->读卡，获取身份证信息的UNICODE码（IDCard_Read）->获取姓名（IDCard_Name）/获取性别（IDCard_Sex）.../（保存照片IDCard_PhotoSave_Ex）->关闭设备
流程图如下：
方案2、不需要二代证照片，直接读取身份证信息
建立连接成功->读卡（IDCard_ReadCard）->解析数据（IDCard_GetCardInfo）->关闭设备
流程图如下：
方案3、需要设置二代证照片保存全路径（包括照片名字）及获取身份证信息
建立连接成功->读二代证扩展一（IDCard_ReadCard_Extra）->解析数据（IDCard_GetCardInfo）->关闭设备
流程图如下所示:
方案4、需要设置二代证照片路径、照片保存名字、需要照片信息的Base64码.
建立连接成功->设置照片存放路径（IDCard_SetPhotoPath）->设置照片名字（IDCard_SetPhotoName）->读二代证扩展二（IDCard_ReadCard_Ex）->关闭设备
具体流程图如下所示:
注意：
上述四个方案，实际是四个身份证读卡函数，不建议一次二代证读卡，调用四个身份证读卡函数中的多个，
如果只是需要身份证部分信息（比如身份证号码），建议采用方案一；
如果只是需要读取身份证信息的明文，不需要保存照片，可以采用方案二、方案三（照片文件传空）、方案四（照片保存参数填0）；
如果需要保存照片，并且指定照片保存的全路径（包括照片名字,比如:
C:
\zp.bmp），那么建议采用方案三；
如果需要修改保存照片的名字或者获取照片信息的Base64码，那么建议采用方案四。
2.对于需要读取多种非接卡的情况，操作流程如下：
建立连接成功->判断卡类型（CLCard_Open）->解析数据（IDCard_GetCardInfo）->关闭设备
4.1.6.函数操作结果信息表
说明：
实际返回的错误信息为表中数据的负数形式，例如：
命令超时，返回-0x0011。
StatusH
StatusL
说明
00H
00H
命令执行正确回应
00H
01H
可选的功能接口或参数不支持（包括可选的通讯波特率参数、显示屏功能等）
00H
02H
调用sdtapi.dll错误
00H
03H
相片解码错误
00H
04H
wlt文件后缀错误
00H
05H
wlt文件打开错误
00H
06H
wlt文件格式错误
00H
07H
软件未授权
00H
08H
设备连接错误
00H
09H
相片解码其他错误
00H
11H
命令超时
00H
12H
无效的通讯句柄
00H
13H
打开通讯端口错误
00H
14H
通讯端口已被占用
00H
15H
获取通讯端口状态错误
00H
16H
设置通讯端口状态错误
00H
17H
从读写器读取数据出错
00H
18H
向读写器写入数据出错
00H
21H
STX错误
00H
22H
ETX错误
00H
23H
校验位错误
00H
24H
数据长度大于最大长度
00H
25H
数据值错误
00H
31H
获取身份证信息，下标有误
00H
32H
身份证读卡错误
10H
01H
不支持接触用户卡
10H
02H
接触用户卡未插到位
10H
03H
接触用户卡已上电
10H
04H
接触用户卡未上电
10H
05H
接触用户卡上电失败
10H
06H
操作接触用户卡数据无回应
10H
07H
操作接触用户卡数据出现错误
20H
01H
不支持PSAM卡
20H
03H
PSAM卡已上电
20H
04H
PSAM卡未上电
20H
05H
PSAM卡上电失败
20H
06H
操作PSAM卡数据无回应
20H
07H
操作PSAM卡数据出现错误
30H
01H
不支持非接触用户卡
30H
04H
非接触用户卡未激活
30H
05H
非接触用户卡激活失败
30H
06H
操作非接触用户卡无回应（等待超时）
30H
07H
操作非接触用户卡数据出现错误
30H
08H
非接触用户卡halt失败
30H
09H
有多张卡在感应区
60H
01H
不支持逻辑操作
60H
20H
卡片类型不对（卡状态6A82）
60H
21H
余额不足（卡状态9401）
60H
22H
卡片功能不支持（卡状态6A81）
60H
23H
扣款失败（卡状态9302）
60H
30H
卡片未启用
60H
31H
卡片不在有效期
60H
32H
交易明细无此记录
60H
33H
交易明细记录未处理完成
60H
40H
需要做防拔处理
60H
41H
防拔处理中出错,非原来卡
60H
42H
交易中断,没有资金损失
4.2.设备操作函数组
4.2.1打开读写器device_open
函数功能：
与读写器建立连接
函数声明:
HANDLE__stdcalldevice_open（char*portname__int16port,unsignedlongbaud）;
入口参数：
portname连接方式，分为“USB”和“COM”。
port串口号,0对应COM1,1对应COM2……，取值范围0~31。
baud（入）通讯波特率，9600bps（缺省设置）19200bps，38400bps，57600bps，115200bps
通讯方式为HID时，port和baud可为任意值。
返回值:
<0错误
>0通讯设备标识符
举例:
icdev=device_open（“USB”,0,9600）;
4.2.2关闭读写器device_close
函数功能：
与读写器断开连接
函数声明:
__int16device_close（HANDLEicdev）
入口参数:
icdev表示通讯设备标识符
返回值:
<>0错误
=0正确
举例:
st=device_close（icdev）;
4.2.3判断设备通讯类型device_gettype
函数功能：
获取设备与PC机的通讯方式
函数声明:
__int16device_gettype（unsignedchar*devicetype）;
出口参数:
devicetype:
1字节设备与PC机的通讯方式，1--HID，0--串口
返回值:
≡0
举例:
unsignedcharcDeviceType=0;
st=device_gettype（&cDeviceType）;
4.2.4设置通讯波特率device_setbaud
函数功能：
设置串口通讯波特率
函数声明：
__int16device_setbaud（HANDLEicdev,unsignedcharmodule,unsignedlongbaud）;
入口参数：
icdev通讯设备标识符
module功能模块1字节00H：
接触式,01H：
非接触式
baud串口波特率9600bps（缺省设置）
19200bps
38400bps
57600bps
115200bps
返回值：
<0错误
=0正确
举例:
__int16st=device_setbaud（icdev,0,9600）;//设置接触式模块的通讯波特率为9600bps.
4.2.5获取读写器版本信息device_version
函数功能：
查看读写器版本信息
函数声明:
__int16device_version（HANDLEicdev,unsignedcharmodule,unsignedchar*verlen,unsignedchar*verdata）;
入口参数:
icdev通讯设备标识符
module功能模块1字节00H：
接触式,01H：
非接触式
出口参数：
verlen版本信息字节长度
verdata读写器版本信息
返回值:
<0错误
=0正确
举例：
__int16st=0;
unsignedcharverlen=0;
unsignedcharverdata[100];
memset（verdata,0,100）;
st=device_version（icdev,0,&verlen,verdata）;//获取读写器接触式模块的版本信息
4.2.6读写器蜂鸣device_beep
函数功能：
控制读写器蜂鸣器的单声鸣叫延迟时间和鸣叫次数
函数声明:
__int16device_beep（HANDLEicdev,unsignedshortdelaytime,unsignedchartimes）;
入口参数:
icdev通讯设备标识符
delaytime蜂鸣器鸣叫时间,单位为100毫秒。
其中，第一字节是一次鸣叫持续时间，第二字节是一次鸣叫停止时间（多次蜂鸣时的蜂鸣间隔时间）。
times蜂鸣器鸣叫次数
返回值:
<>0错误
=0正确
举例：
intst=0;
unsignedshortDelayTime=1285;
st=device_beep（icdev,DelayTime,2）;
4.2.7LED灯控制device_ledctrl
函数功能：
控制读写器对应LED灯的开关状态
函数声明：
__int16device_ledctrl（HANDLEicdev,unsignedcharledctrl）;
入口参数：
icdev通讯设备标识符
ledctrl1字节位7对应绿灯，0关，1开
其他保留
返回值：
<>0错误
=0正确
举例：
__int16st=device_ledctrl（icdev,128）;
4.2.8获取读写器生产序列号device_readsnr
函数功能：
获取读写器生产序列号
函数声明：
__int16__stdcalldevice_readsnr（HANDLEicdev,unsignedcharnSnrLen,char*sSnrData）;
入口参数：
icdev通讯设备标识符
nSnrLen1字节序列号长度，1--20.
出口参数：
sSnrDatanSnrLen字节序列号数据，ASCII码字符形式
返回值：
<>0错误
=0正确
举例：
intst=0;
unsignedcharsSnrData[30];
memset（sSnrData,0,30）;
st=device_readsnr（icdev,20,sSnrData）;
4.2.9获取设备状态get_device_status
函数功能：
获取设备状态，判断设备是否正常
函数功能：
__int16__stdcallget_device_status（HANDLEicdev,unsignedchar*ndev_status）
入口参数：
icdev通讯设备标识符
出口参数：
ndev_status设备状态字节一字节取值0~3
0正常
1接触卡通道异常
2非接卡通道异常
3接触卡和非接卡通道异常
4安全模块通道异常
5接触卡和安全模块通道异常
6非接卡和安全模块通道异
升级会员 