MT明泰读卡器API接口函数库使用说明Word文档下载推荐.docx

1、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、装驱动程序。2.API接口函数库封装了通过PC机来操作二代证读卡器时用到的各个函数，用户在执行操作时，只需调用相应的函数接口即可，不需要编写对读卡器的操作函数。3.运行环境3.1.硬设备为运行本产品，您需要的硬设备的最小配置如下：A. 处理器：80X86B. 内存：64KBC. 硬盘：2.0GBD. USB接口一个E. RS232串口一个3.2.软件的运行平台为运行本产品，您需要的支持软件如下：A. 操作系统：Win 7/Windows Vista/Win2003/WinXP/Win2000；B. 程序编写工具：VC/VB/PB/Delphi等；3.3.函数调用方法3.3.1.Delphi调用

3、32位动态库的方法语法：Public Private | protected Function FunctionName（Var Arg1:DataType1; Arg2:DataType2;.） :ReturnDataType; far;stdcall;externallibname Name AliasName;调用语句的语法包含下面部分：关键字Public（可选），表示函数可以被程序代码中的任意部分访问。关键字Private（可选），表示函数在声明类的单元（源代码）外不能访问。关键字Protected（可选），表示保护函数，保护元素只能被当前类和它的子类访问。关键字Function（必选

4、），表示调用函数，函数有返回值。FunctionName（必选），调用外部函数的名称，区分大小写。关键字Var（可选），表示通过引用传递参数，函数参数可以用值传递，也可以通过引用传递。通过引用传递参数，它的值没被复制到存放函数例程参数的堆栈中，程序执行速度快。通过引用传值，将允许过程和函数改变参数的值。ArgN:DataTypeN（可选），参数名以及参数类型，传递的参数类型可以是：Shorint，Smallint，Longint，Integer（16/32），Single，Double，Extended，Currency，Date，Pchar，Object，Variant等。ReturnTyp

5、e（可选），函数返回值的类型。Stdcall（必选），表示传递约定，这样调用模块（应用程序），与被调用模块（DLL）就使用相同的参数约定。关键字external（必选），声明访问外部函数。Libname（必选），访问的DLL名称，16位Delphi中外部声明不带扩展名的库名。NameAliasName（可选），Name指令可以为外部函数起别名，避免与系统例程和函数名称冲突。外部程序调用的DLL函数，必须遵照下列规则：（1）必须列在DLL的exports子句中。（2）在Delphi3中，调用函数还需被声明为stdcall，来使用标准的WIN32参数传递技术。代替优化的register参数传递技术

6、。（3）在WIN32中，DLL可以使用全局数据，该数据将不会通过调用应用程序来分享，每当应用程序装载DLL时，它在自己的地址空间中存储着DLL的全部数据。注：详细请参考ICCardEXAMPLES目录下的使用范例。3.3.2. VB调用32位动态库的方法 语法：Public | Private Declare Function name Lib libname Alias aliasname （arglist） As typeDeclare 语句的语法包含下面部分：Public （可选）用于声明在所有模块中的所有过程都可以使用的函数。Private（可选），用于声明只能在包含该声明的模块中使用

7、的函数。Name（必选），任何合法的函数名。动态链接库的入口处（entry points）区分大小写。Libname（必选），包含所声明的函数动态链接库名或代码资源名。Alias（可选），表示将被调用的函数在动态链接库 （DLL） 中还有另外的名称。当外部函数名与某个函数重名时，就可以使用这个参数。当动态链接库的函数与同一范围内的公用变量、常数或任何其它过程的名称相同时，也可以使用 Alias。如果该动态链接库函数中的某个字符不符合动态链接库的命名约定时，也可以使用 Alias。Aliasname（可选）动态链接库。如果首字符不是数字符号 （#），则 aliasname 是动态链接库中该函数入

8、口处的名称。如果首字符是 （#），则随后的字符必须指定该函数入口处的顺序号。Arglist（可选），代表调用该函数时需要传递参数的变量表。Type（可选），Function返回值的数据类型；可以是 Byte、Boolean、Integer、Long、Currency、Single、Double、Decimal（目前尚不支持）、Date、String（只支持变长）或 Variant，用户定义类型，或对象类型。arglist 参数的语法如下：Optional ByVal | ByRef ParamArray varname（ ） As type部分描述：Optional（可选），表示参数不是必需的

9、。如果使用该选项，则 arglist 中的后续参数都必需是可选的，而且必须都使用 Optional 关键字声明。如果使用了 ParamArray，则任何参数都不能使用 Optional。ByVal（可选），表示该参数按值传递。ByRef（可选），表示该参数按地址传递。ParamArray（可选），只用于 arglist 的最后一个参数，表示最后参数是一个 Variant 元素的Optional 数组。使用 ParamArray 关键字可以提供任意数目的参数。ParamArray 关键字不能与 ByVal、ByRef或 Optional 一起使用。Varname（必选），代表传给该函数参数的变量

10、名；遵循标准的变量命名约定。（ ） 对数组变量是必需的。指明 varname 是一个数组。type （可选），传递给函数参数的数据类型；可以是除Decimal以外的任何类型。说明：Function的数据类型决定其返回值的数据类型。可以在 arglist 之后使用 As 子句来指定函数返回值的数据类型。在 arglist 中，可以使用 As 子句来指定任何传给该函数参数的数据类型。不单可以指定为任何标准数据类型，还可以在 arglist 中指定 As Any 来禁止类型检查，从而允许将任意数据类型传递给该函数。空圆括号表示该 Function 没有参数，且 Visual Basic 应确保不会传

11、递任何参数。注意：（1）当所调用的外部函数需要一个值为 0 的字符串时，就要使用 vbNullString 常数。该常数与零长度字符串 （）是不相同的。（2）VB5调用32位动态库，对于ASCII码值大于128的读写操作，请参考Examples 中24系列的BYREF传递方式；16位动态库可以直接使用CHR函数转换。（3）详细请参考ICCardEXAMPLES目录下的使用范例。3.3.3.VC调用32位动态库的方法（1）在.CPP中包含“mtx_32.h”头文件；（2）在工程文件中加入mtx_32.lib文件。（3）在C:WINDOWSsystem32或工程文件中加入GetInfo.dll文件

12、。4.API介绍4.1.函数调用流程4.1.1.非接触式存储卡API调用流程 建立连接成功后软件中基于 Mifare one 卡测试一般的操作过程是： 读数 建立连接- 寻卡- 验证 写数据 中止卡片 值操作4.1.2.非接触式CPU卡片API调用流程 软件中基于非接触 CPU 卡片，一般的操作过程是： 建立连接成功-打开卡片-发送 APDU命令-设置卡片状态为halt-中止卡片操作4.1.3.接触式CPU卡片API调用流程 软件中基于接触式CPU卡片，一般的操作过程是：上电复位-获取卡片状态/发送APDU命令-卡片下电。4.1.4.接触式存储卡片API调用流程 软件中基于接触式存储卡片，一般

13、的操作过程是： 建立连接成功-设置存储卡种类-识别存储卡种类-密码校验-读数据/写数据/更改密码4.1.5.身份证API调用流程软件中基于身份证，一般的操作过程是：目前我们的二代证接口有五套操作接口，下面分别对五套接口的操作流程都做一下详细描述，具体如下:1.对于只需要读取二代证的情况，操作流程如下:方案1、直接读取身份证信息的UNICODE码，通过返回的UNICODE码传入相关函数获取身份证信息。建立连接成功-读卡，获取身份证信息的UNICODE码（IDCard_Read）-获取姓名（IDCard_Name）/获取性别（IDCard_Sex）./（保存照片IDCard_PhotoSave_E

14、x）-关闭设备流程图如下：方案2、不需要二代证照片，直接读取身份证信息读卡（IDCard_ReadCard）-解析数据（IDCard_GetCardInfo）-方案3、需要设置二代证照片保存全路径（包括照片名字）及获取身份证信息读二代证扩展一（IDCard_ReadCard_Extra）-流程图如下所示:方案4、需要设置二代证照片路径、照片保存名字、需要照片信息的Base64码.设置照片存放路径（IDCard_SetPhotoPath）-设置照片名字（IDCard_SetPhotoName）-读二代证扩展二（IDCard_ReadCard_Ex）-具体流程图如下所示:上述四个方案，实际是四个身

15、份证读卡函数，不建议一次二代证读卡，调用四个身份证读卡函数中的多个，如果只是需要身份证部分信息（比如身份证号码），建议采用方案一；如果只是需要读取身份证信息的明文，不需要保存照片，可以采用方案二、方案三（照片文件传空）、方案四（照片保存参数填0）；如果需要保存照片，并且指定照片保存的全路径（包括照片名字,比如:C:zp.bmp），那么建议采用方案三；如果需要修改保存照片的名字或者获取照片信息的Base64码，那么建议采用方案四。2.对于需要读取多种非接卡的情况，操作流程如下：判断卡类型（CLCard_Open）-4.1.6.函数操作结果信息表实际返回的错误信息为表中数据的负数形式，例如：命令超

16、时，返回-0x0011。StatusHStatusL说明00H 命令执行正确回应 01H 可选的功能接口或参数不支持（包括可选的通讯波特率参数、显示屏功能等） 00H02H 调用sdtapi.dll错误03H相片解码错误04Hwlt文件后缀错误05Hwlt文件打开错误06Hwlt文件格式错误07H软件未授权08H设备连接错误09H相片解码其他错误11H 命令超时 12H无效的通讯句柄13H打开通讯端口错误14H通讯端口已被占用15H获取通讯端口状态错误16H设置通讯端口状态错误17H从读写器读取数据出错18H向读写器写入数据出错21HSTX错误22HETX错误23H校验位错误24H数据长度大于

17、最大长度25H数据值错误31H获取身份证信息，下标有误32H身份证读卡错误10H 不支持接触用户卡 接触用户卡未插到位 03H 接触用户卡已上电 04H 接触用户卡未上电 05H 接触用户卡上电失败 06H 操作接触用户卡数据无回应 07H 操作接触用户卡数据出现错误 20H 不支持PSAM卡 PSAM卡已上电 PSAM卡未上电 PSAM卡上电失败 操作PSAM卡数据无回应 操作PSAM卡数据出现错误 30H 不支持非接触用户卡 非接触用户卡未激活 非接触用户卡激活失败 操作非接触用户卡无回应（等待超时） 操作非接触用户卡数据出现错误 08H 非接触用户卡halt失败 09H 有多张卡在感应区

18、 60H 不支持逻辑操作 卡片类型不对（卡状态6A82） 21H 余额不足（卡状态9401） 22H 卡片功能不支持（卡状态6A81） 23H 扣款失败（卡状态9302） 卡片未启用 31H 卡片不在有效期 32H 交易明细无此记录 33H 交易明细记录未处理完成 40H 需要做防拔处理 41H 防拔处理中出错, 非原来卡 42H 交易中断, 没有资金损失 4.2. 设备操作函数组4.2.1 打开读写器device_open函数功能：与读写器建立连接函数声明: HANDLE _stdcall device_open（char* port name _int16 port,unsigned lo

19、ng baud）;入口参数： port name 连接方式，分为“USB”和“COM”。port 串口号,0对应COM1,1对应COM2，取值范围031。 baud （入）通讯波特率，9600bps（缺省设置）19200bps，38400bps，57600bps，115200bps 通讯方式为HID时，port和baud可为任意值。返回值: 0 通讯设备标识符 举例: icdev=device_open （“USB”,0,9600）;4.2.2 关闭读写器device_close 与读写器断开连接 _int16 device_close （HANDLE icdev） 入口参数: icdev 表

20、示通讯设备标识符 =0 正确举例: st=device_close （icdev）;4.2.3 判断设备通讯类型device_gettype 获取设备与PC机的通讯方式 _int16 device_gettype（unsigned char* devicetype）;出口参数: devicetype: 1字节 设备与PC机的通讯方式，1-HID，0-串口 0 unsigned char cDeviceType=0; st=device_gettype （&cDeviceType）;4.2.4 设置通讯波特率device_setbaud设置串口通讯波特率函数声明：_int16 device_se

21、tbaud（HANDLE icdev,unsigned char module,unsigned long baud）;icdev 通讯设备标识符 module 功能模块 1字节 00H：接触式, 01H：非接触式 baud 串口波特率 9600bps（缺省设置） 19200bps 38400bps 57600bps 115200bps返回值： 0 错误 = 0 正确 _int16 st=device_setbaud（icdev,0,9600）; /设置接触式模块的通讯波特率为9600bps.4.2.5 获取读写器版本信息device_version查看读写器版本信息 _int16 devic

22、e_version（HANDLE icdev,unsigned char module,unsigned char* verlen,unsigned char* verdata）; icdev 通讯设备标识符非接触式 出口参数： verlen 版本信息字节长度 verdata 读写器版本信息举例： _int16 st=0; unsigned char verlen=0; unsigned char verdata100; memset（verdata,0,100）; st=device_version（icdev,0,&verlen,verdata）; /获取读写器接触式模块的版本信息4.2.

23、6 读写器蜂鸣device_beep控制读写器蜂鸣器的单声鸣叫延迟时间和鸣叫次数 _int16 device_beep（HANDLE icdev, unsigned short delaytime,unsigned char times）; icdev 通讯设备标识符 delaytime 蜂鸣器鸣叫时间,单位为100毫秒。其中，第一字节是一次鸣叫持续时间，第 二字节是一次鸣叫停止时间（多次蜂鸣时的蜂鸣间隔时间）。 times 蜂鸣器鸣叫次数 int st=0; unsigned short DelayTime=1285; st=device_beep（ icdev,DelayTime,2）;4

24、.2.7 LED灯控制 device_ledctrl控制读写器对应LED灯的开关状态_int16 device_ledctrl（HANDLE icdev,unsigned char ledctrl）; ledctrl 1字节 位7对应绿灯，0关，1开 其他保留 _int16 st=device_ledctrl（icdev,128）;4.2.8 获取读写器生产序列号 device_readsnr获取读写器生产序列号_int16 _stdcall device_readsnr（HANDLE icdev,unsigned char nSnrLen,char* sSnrData）; nSnrLen 1

25、字节 序列号长度，1-20.sSnrData nSnrLen字节 序列号数据，ASCII码字符形式 unsigned char sSnrData30; memset（sSnrData,0,30）; st=device_readsnr（icdev,20,sSnrData）;4.2.9 获取设备状态 get_device_status获取设备状态，判断设备是否正常_int16 _stdcall get_device_status（HANDLE icdev,unsigned char *ndev_status）ndev_status 设备状态字节 一字节 取值 030 正常 1 接触卡通道异常2 非接卡通道异常3 接触卡和非接卡通道异常4 安全模块通道异常5 接触卡和安全模块通道异常6 非接卡和安全模块通道异