电子通行证读卡接口说明文档

### 电子通行证读卡接口说明文档 #### 一、总体架构及编写目的 本文档旨在详细介绍用于读取中国大陆居民往来港澳通行证以及往来台湾通行证芯片数据的封装接口控件`Readcard21.ocx`及其使用方法。随着科技的发展，电子化成为趋势，特别是在身份验证领域。电子通行证作为重要的身份证明工具，其读取技术变得尤为重要。 **1.1 编写目的** 本文档的主要目的是为了方便业务系统的集成和开发人员更好地理解和使用`Readcard21.ocx`控件提供的功能。通过对控件功能的详细介绍，帮助开发人员能够快速地将该控件集成到现有的业务系统中，实现对电子通行证芯片数据的有效读取。 **1.2 接口函数** 本应用软件的接口发布部分，封装成ActiveX控件，便于业务系统通过HTML方式进行调用。该控件包括以下三个主要函数： 1. **1.2.1 连接加密机** - **函数名**: `OcxSetKEYIP` - **说明**: 用于连接加密机。 - **参数**: - `IP(string)`: 应用服务器IP地址。 - `Port(string)`: 应用服务器端口。 - **返回**: - `Int`: 0 表示成功，其他值表示失败，并可通过错误码列表查询具体错误原因。 2. **1.2.2 列出读写器** - **函数名**: `OcxGetReaders` - **说明**: 用于列出可用的读写器设备。 - **参数**: 无。 - **返回**: - `string`: 包含读写器名称的字符串。 3. **1.2.3 读芯片** - **函数名**: `OcxReadGetInfo` - **说明**: 用于读取通行证芯片中的信息。 - **参数**: - `readerName(In)`: 阅读器名称。 - `strOCR(In)`: 证件机读码（长度大于等于30位时以BAC方式读取；小于30位时以FAC方式读取）。 - `readtype(In)`: 卡片类型，如港澳通行证正式卡21，台湾通行证正式卡25等。 - `readPram(In)`: 10位0、1字符串，代表所需获取的信息种类。 - **返回**: - `string`: 包含XML格式的数据结构字符串。通过`<RESULT>`节点判断读取是否成功，0表示成功，其他值表示失败并可根据错误码列表查询具体错误原因。 #### 二、数据结构与调用说明 **1.3 港澳通行证返回的阅读信息结构（XML格式）** 读取港澳通行证芯片后返回的数据采用XML格式。下面是一个具体的例子： ```xml <?xml version="1.0" encoding="utf-8"?> <Cardinfo> <PersonInfomemo="个人基本信息"> <DG1Data>CSC100001026<2312019<7903214<8MMLIMAPGMEMIZHENGJIAN<<YANGBEN<<<<FAAB000144<<<<<<<<<<<<<<<<<<</DG1Data> <ChineseName>证件样本</ChineseName> <CompletePinName>ZHENGJIAN<<YANGBEN</CompletePinName> <PersonKey>BIFDFPHPBKPDIFOOJJKEFOEPEANCAOKJ</PersonKey> ... <SelfMade2/> <Reserve/> </PersonInfo> <BioInfomemo="个人生物特征信息"> <nFaceDataLen>15946</nFaceDataLen> <nFingerImageLen>0</nFingerImageLen> <nFingerImpLen>0</nFingerImpLen> <FaceData></FaceData> <FingerImage></FingerImage> <FingerTmp></FingerTmp> </BioInfo> </Cardinfo> ``` - `<PersonInfomemo>`: 包含个人基本信息，如姓名、性别、出生日期等。 - `<BioInfomemo>`: 包含个人生物特征信息，如面部图像数据、指纹数据等。 **1.4 台湾通行证返回的阅读信息结构（XML格式）** 台湾通行证芯片读取后的数据结构与港澳通行证类似，但具体字段可能有所不同。例如，台湾通行证可能会包含不同的个人基本信息和生物特征信息。 #### 三、调用与说明 **2.1 调用示例** 为了帮助开发者更好地理解如何调用上述接口，下面提供一个简单的示例： 1. **连接加密机**: 使用`OcxSetKEYIP`函数。 2. **列出读写器**: 使用`OcxGetReaders`函数。 3. **读取芯片**: 使用`OcxReadGetInfo`函数，并传递适当的参数。 **2.2 错误码列表** 错误码列表对于诊断问题非常重要。通常情况下，错误码可以帮助开发者快速定位问题所在。例如，在`OcxReadGetInfo`函数中，如果返回值不是0，则可以通过查阅错误码列表来了解具体错误原因。 在实际使用过程中，开发者需要注意以下几点： - 确保正确设置了服务器的IP地址和端口号。 - 正确选择读写器名称。 - 根据实际情况设置读取参数`readPram`，确保只读取所需的数据。 `Readcard21.ocx`控件提供了强大的功能，可以方便快捷地读取港澳台通行证的芯片数据。通过本文档的详细介绍，开发者应该能够更加熟练地使用这些接口，从而提高开发效率和用户体验。