# 华视电子身份证阅读器SDK使用手册
**版本：V3.3.0.7**
**发布：深圳华视电子读写设备有限公司**
**日期：2018年08月20日**
---
## 📋 目录
1. [版本信息](#版本信息)
2. [文件说明](#文件说明)
3. [函数列表](#函数列表)
4. [数据结构](#数据结构)
5. [函数详细说明](#函数详细说明)
6. [函数调用流程](#函数调用流程)
7. [核心函数说明](#核心函数说明)
8. [信息格式说明](#信息格式说明)
9. [其他函数用法](#其他函数用法)
---
## 📝 版本信息
| 序号 | 版本号 | 修改日期 | 修改内容 |
|------|---------|----------|----------|
| 1 | V3.3.0.1 | 2016-09-20 | 在上一版本的基础上，修复多出动态库BUG，重新撰写使用说明 |
| 2 | V3.3.0.2 | 2016-12-19 | 增加对穿青人和达斡尔族民族的显示 |
| 3 | V3.3.0.3 | 2017-06-23 | 增加对外国人永居证的读取 |
| 4 | V3.3.0.4 | 2017-08-08 | 增加对革家人民族的显示 |
| 5 | V3.3.0.5 | 2017-11-09 | 增加对windows64位系统的支持 |
| 6 | V3.3.0.6 | 2018-07-03 | 增加PB语言的示例代码 |
| 7 | V3.3.0.7 | 2018-08-20 | 增加对港澳台居民居住证的读取 |
| 8 | V3.3.0.8 | 2023-09-26 | 增加新版外国人 |
---
## 📁 文件说明
### 🔧 SDK组件
| 文件名 | 说明 | 用途 |
|--------|------|------|
| `termb.dll` | API函数的动态联接库 | 主要接口库 |
| `sdtapi.dll` | 安全模块通讯函数 | 安全通信 |
| `WltRs.dll` | 身份证相片解码库 | 照片处理 |
| `SysInfo.dll` | 系统信息库 | 系统支持 |
### 💻 系统支持
- **操作系统**：Windows XP、Windows7（32位和64位）等常见操作系统
- **开发语言**：
- Visual C++ 6.0 及以后版本
- Visual Basic 6.0 及以后版本
- Delphi 6.0 及以后版本
- PowerBuilder 6.0 及以后版本
- Visual C# 2005 及以后版本
**技术支持联系人：13723716489 何工**
---
## 🔧 函数列表
### 主要API函数
```c
int CVR_InitComm(int Port); // 初始化连接
int CVR_Authenticate(); // 卡认证
int CVR_AuthenticateForNoJudge(); // 卡认证一直成功版本
int CVR_Read_Content(int active); // 读卡操作
int CVR_Read_FPContent(); // 读卡操作，含指纹
int CVR_CloseComm(); // 关闭连接
int CVR_FindCard(); // 找卡
int CVR_SelectCard(); // 选卡
```
---
## 📊 数据结构
### 1. 居民身份证结构
| 名称 | 含义 | 长度 | 备注 |
|------|------|------|------|
| 姓名 | 姓名 | 不超过30字节 | |
| 性别 | 性别 | 不超过2个字节 | 符合GB/T 2261.1的规定 |
| 民族 | 民族 | 不超过20个字节 | 或10个unicode字符 |
| 出生日期 | 出生日期 | 不超过16个字节 | 格式为YYMMDD |
| 住址 | 户口所在地 | 不超过70个字节 | 或35个unicode字符 |
| 公民身份证号码 | 证件号码 | 不超过36个字节 | 或18个unicode字符 |
| 签发机关 | 签发机关 | 不超过30字节 | |
| 有效期起始日期 | 有效期起始日期 | 不超过16个字节 | 格式为YYMMDD |
| 有效期终止日期 | 有效期终止日期 | 不超过16个字节 | 格式为YYMMDD |
| 指纹数据 | 指纹数据 | 不超过1024字节 | 二进制数据，需证件内含有指纹 |
### 2. 外国人居留证结构
| 名称 | 含义 | 长度 | 备注 |
|------|------|------|------|
| 英文姓名 | 外国人英文姓名 | 不超过120字节 | |
| 性别 | 外国人性别 | 不超过2个字节 | 符合GB/T 2261.1的规定 |
| 永久居留证号码 | 证件号码 | 不超过30个字节 | 或15个unicode字符 |
| 国籍、地区代码 | 国籍或所在地区代码 | | 参考GB/T 2659-2000中文缩写 |
| 中文姓名 | 中文姓名 | 不超过30个字节 | 或15个unicode双字节(UTF16)字符 |
| 证件签发日期 | 证件签发日期 | 不超过16个字节 | 格式为YYMMDD |
| 证件终止日期 | 证件终止日期 | 不超过16个字节 | 格式为YYMMDD |
| 出生日期 | 出生日期 | 不超过16个字节 | 格式为YYMMDD |
| 证件版本号 | 证件版本号 | 不超过4字节 | |
| 受理机关代码 | 当次申请受理机关代码 | 不超过8个字节 | |
| 证件类别 | 证件类别 | | "I" |
| 照片内容 | 照片内容 | | 若取得bmp数据，则不超过38862字节，jpg数据长度可变 |
### 3. 港澳台居住证结构
| 名称 | 含义 | 长度 | 备注 |
|------|------|------|------|
| 姓名 | 姓名 | 不超过30字节 | |
| 性别 | 性别 | 不超过2个字节 | 符合GB/T 2261.1的规定 |
| 出生日期 | 出生日期 | 不超过16个字节 | 格式为YYMMDD |
| 住址 | 户口所在地 | 不超过70个字节 | 或35个unicode字符 |
| 公民身份证号码 | 证件号码 | 不超过36个字节 | 或18个unicode字符 |
| 签发机关 | 签发机关 | 不超过30字节 | |
| 有效期起始日期 | 有效期起始日期 | 不超过16个字节 | 格式为YYMMDD |
| 有效期终止日期 | 有效期终止日期 | 不超过16个字节 | 格式为YYMMDD |
| 通行证号码 | 通行证号码 | 不超过18个字节 | |
| 签发次数 | 签发次数 | 不超过4字节 | |
| 证件类别 | 证件类别 | | "J" |
| 照片内容 | 照片内容 | | 若取得bmp数据，则不超过38862字节，jpg数据长度可变 |
| 指纹数据 | 指纹数据 | 不超过1024字节 | 2进制数据 |
### 4. 新版外国人居留证结构
| 名称 | 含义 | 长度 | 备注 |
|------|------|------|------|
| 英文姓名 | 外国人英文姓名 | 不超过92字节 | |
| 性别 | 外国人性别 | 不超过2个字节 | 符合GB/T 2261.1的规定 |
| 永久居留证号码 | 证件号码 | 不超过30个字节 | 或15个unicode字符 |
| 国籍、地区代码 | 国籍或所在地区代码 | | 参考GB/T 2659-2000中文缩写 |
| 中文姓名 | 中文姓名 | 不超过30个字节 | 或15个unicode双字节(UTF16)字符 |
| 证件签发日期 | 证件签发日期 | 不超过16个字节 | 格式为YYMMDD |
| 证件终止日期 | 证件终止日期 | 不超过16个字节 | 格式为YYMMDD |
| 出生日期 | 出生日期 | 不超过16个字节 | 格式为YYMMDD |
| 换证次数 | 换证次数 | 4字节 | |
| 旧版证件号码 | 旧版证件号码 | 6字节 | |
| 证件类别 | 证件类别 | | "Y" |
| 照片内容 | 照片内容 | | 若取得bmp数据，则不超过38862字节，jpg数据长度可变 |
> **注意**：CVR_Authenticate功能和CVR_FindCard+ CVR_SelectCard一样，CVR_Authenticate内部调用了找卡和选卡函数，接口分开是为了调用者开发方便。
---
## 🔍 函数详细说明
### 数据获取函数（多字节版本）
#### 基本信息获取
```c
int GetPeopleName(char *strTmp, int *strLen); // 得到姓名信息
int GetPeopleSex(char *strTmp, int *strLen); // 得到性别信息
int GetPeopleNation(char *strTmp, int *strLen); // 得到民族信息
int GetPeopleBirthday(char *strTmp, int *strLen); // 得到出生日期
int GetPeopleIDCode(char *strTmp, int *strLen); // 得到身份证号信息
int GetPeopleAddress(char *strTmp, int *strLen); // 得到地址信息
int GetDepartment(char *strTmp, int *strLen); // 得到发证机关信息
int GetStartDate(char *strTmp, int *strLen); // 得到有效开始日期
int GetEndDate(char *strTmp, int *strLen); // 得到有效截止日期
```
#### 扩展信息获取
```c
int GetNationCode(unsigned char *nationData, int *strLen); // 得到民族代码
int GetSexCode(unsigned char *sexData, int *pLen); // 得到性别代码
int GetCertType(unsigned char *nationData, int *pLen); // 获取证件类别
int GetFPDate(unsigned char *pData, int *pLen); // 得到指纹数据
int GetPassCheckID(unsigned char *strTmp, int *strLen); // 通行证号码
int GetIssuesNum(int *IssuesNum); // 签发次数
int GetNewAppMsg(unsigned char *nationData, int *pLen); // 获取追加地址
```
#### 照片数据获取
```c
int GetBMPData(unsigned char *pData, int *pLen); // 得到头像照片bmp数据
int Getbase64BMPData(unsigned char *pData, int *pLen); // 得到头像照片base64编码数据
int Getbase64JpgData(unsigned char *pData, int *pLen); // 得到头像照片jpg数据
int GetJpgData(unsigned char *jpgData, int *pLen); // 获取jpg二进制数据
```
#### 外国人专用函数
```c
int GetPeopleChineseName(unsigned char *strTmp, int *strLen); // 获取外国人中文姓名
int GetOldIDCardNumber(unsigned char *strTmp, int *strLen); // 获取旧版外国人证件号码
int GetStandbyEName(unsigned char *strTmp, int *strLen); // 获取英文备用名
int GetPeopleCertVersion(unsigned char *strTmp, int *strLen); // 得到外国人证件版本
```
#### 系统函数
```c
int CVR_GetSAMID(char *SAMID); // 得到安全模块号
```
### Unicode版本函数
所有上述函数都有对应的Unicode版本，函数名后缀加"U"：
```c
int GetPeopleNameU(char *strTmp, int *strLen); // Unicode版本姓名获取
int GetPeopleSexU(char *strTmp, int *strLen); // Unicode版本性别获取
// ... 其他Unicode版本函数
```
---
## 🔄 函数调用流程
```mermaid
graph TD
A[CVR_InitComm] --> B{初始化成功?}
B -->|否| C[返回错误]
B -->|是| D[CVR_Authenticate]
D --> E{认证成功?}
E -->|否| F[返回错误]
E -->|是| G[CVR_Read_Content]
G --> H[GetPeopleName
GetPeopleSex
GetPeopleNation
...
其他getter函数]
H --> I[CVR_CloseComm]
```
---
## ⚙️ 核心函数说明
### 1. 初始化连接
```c
int CVR_InitComm(int Port)
```
**说明**：本函数用于PC与华视电子第二代居民身份证阅读器的连接。
**参数**：
| 参数名 | 含义 | 取值范围 |
|--------|------|----------|
| int Port | 端口编号 | 见端口编号表 |
**端口编号表**：
| 值 | 意义 | 值 | 意义 |
|----|------|----|------|
| 1 | 串口1 | 1001 | USB口1 |
| 2 | 串口2 | 1002 | USB口2 |
| 3 | 串口3 | 1003 | USB口3 |
| ... | ... | ... | ... |
| 16 | 串口16 | 1016 | USB口16 |
**返回值**：
| 值 | 意义 |
|----|------|
| 1 | 正确 |
| 2 | 端口打开失败 |
| -1 | 未知错误 |
| -2 | 动态库加载失败 |
### 2. 关闭端口
```c
int CVR_CloseComm(void)
```
**说明**：本函数用于关闭PC到阅读器的连接。
**参数**：无
**返回值**：
| 值 | 意义 |
|----|------|
| 1 | 关闭成功 |
| 0 | 端口号不合法 |
| -1 | 端口已经关闭 |
| -2 | 动态库加载失败 |
### 3. 卡认证
```c
int CVR_Authenticate(void)
```
**说明**：本函数用于读卡器和卡片之间的合法身份确认。卡认证循环间隔大于300ms。
**参数**：无
**返回值**：
| 值 | 意义 | 说明 |
|----|------|------|
| 1 | 正确 | 卡片认证成功 |
| 2 | 错误 | 寻卡失败 |
| 3 | 错误 | 选卡失败 |
| 4 | 错误 | 未连接读卡器 |
| 0 | 错误 | 动态库未加载 |
> **注意**：若卡片放置后发生认证错误时，请移走卡片重新放置。
```c
int CVR_AuthenticateForNoJudge(void)
```
**说明**：使用此接口读卡不用每次都拿起放下，可以一直读。此函数返回值一直为1。
### 4. 读卡操作
```c
int CVR_Read_FPContent(void)
```
**说明**：本函数用于通过阅读器从第二代居民身份证中读取相应信息。卡认证成功以后才可做读卡操作，读卡完毕若继续读卡应移走二代证卡片重新放置做卡认证。
**参数**：无
**返回值**：
| 返回值 | 意义 |
|--------|------|
| 1 | 正确 |
| 0 | 错误，读身份证失败 |
| 4 | 错误，身份证读卡器未连接 |
| 99 | 动态库未加载 |
### 5. 获取性别代码
```c
int GetSexCode(unsigned char *sexData, int *pLen)
```
**说明**：本函数获取性别代码
**参数**：
| 参数名 | 含义 | 取值范围 |
|--------|------|----------|
| unsigned char *sexData | 缓冲区地址 | |
| int *pLen | 缓冲区长度指针 | 4字节 |
**返回值**：
| 值 | 意义 |
|----|------|
| 1 | 正确 |
| 0 | 错误 |
### 6. 获取民族代码
```c
int GetNationCode(unsigned char *nationData, int *pLen)
```
**说明**：本函数获取民族代码
**参数**：
| 参数名 | 含义 | 取值范围 |
|--------|------|----------|
| unsigned char *nationData | 缓冲区地址 | |
| int *pLen | 缓冲区长度指针 | 4字节 |
**返回值**：
| 值 | 意义 |
|----|------|
| 1 | 正确 |
| 0 | 错误 |
### 7. 获取设备状态
```c
int CVR_GetStatus(void)
```
**说明**：本函数获取设备状态
**返回值**：
| 值 | 意义 |
|----|------|
| 1 | 状态正常 |
| -1 | 状态异常 |
---
## 📄 信息格式说明
### 1. 居民身份证txt文件格式
读卡成功后在当前目录下生成`wz.txt`（文字信息）和`zp.bmp`（照片信息）
**wz.txt内容示例**：
```
张红叶
女
汉
19881118
河北省邯郸市临漳县称勾镇称勾东村复兴路25号
130423198811184328
临漳县公安局
20110330-20210330
```
### 2. 外国人永居证txt文件格式
读卡成功后在当前目录下生成`wz.txt`（文字信息）和`zp.bmp`（照片信息）
**wz.txt内容示例**：
```
ZHENGJIAN,YANGBEN
证件样本
女
19810803
加拿大
CAN
20151025-20251024
CAN110081080319
1500
01
```
**从上到下依次为**：英文姓名，中文姓名，性别，出生日期，国籍，国籍代码，有效期限，证件号码，签发机关代码，证件版本号。
### 3. 港澳台居民居住证TXT文件格式
读卡成功后在当前目录下生成`wz.txt`（文字信息）和`zp.bmp`（照片信息）
**wz.txt内容示例**：
```
金鑫
女
19940823
北京市西城区复兴门外大街999号院11号楼3单元502室
810000199408230013
北京市公安局西城分局
20171027-20221026
000000000
1
```
### 4. 新版外国人永局证TXT文件格式
**wz.txt内容示例**：
```
ZHENGJIAN, YANGBEN ZHENG JIAN YANG
证件样本证件样本
女
2016-01-01
巴基斯坦
PAK
20230808-20280807
931586201601010026
BEN
0
```
---
## 🛠️ 其他函数用法
### 读各项文字信息到自定义内存缓冲
**函数原型**：
```c
int GetPeopleName(char *strTmp, int *strLen); // 得到姓名信息
int GetPeopleSex(char *strTmp, int *strLen); // 得到性别信息
int GetPeopleNation(char *strTmp, int *strLen); // 得到民族信息
int GetPeopleBirthday(char *strTmp, int *strLen); // 得到出生日期
int GetPeopleAddress(char *strTmp, int *strLen); // 得到地址信息
int GetPeopleIDCode(char *strTmp, int *strLen); // 得到卡号信息
int GetDepartment(char *strTmp, int *strLen); // 得到发证机关信息
int GetStartDate(char *strTmp, int *strLen); // 得到有效开始日期
int GetEndDate(char *strTmp, int *strLen); // 得到有效截止日期
int CVR_GetSAMID(char *SAMID); // 得到安全模块号码
```
**参数说明**：
- `*strTmp`：返回的信息缓存指针
- `*strLen`：返回的信息长度指针
**返回值**：
| 返回值 | 意义 |
|--------|------|
| 1 | 正确 |
| 0 | 错误 |
> **注意**：若采用查询方式自动判断卡片是否放置，则间隔时间建议大于600ms。
---
**本手册是操作身份证阅读器动态库应用函数的定义格式、调用方法和返回值的说明。**