江苏宿迁沭阳铭和医院的华视电子身份证读卡器SDK文档.md 15 KB
华视电子身份证阅读器SDK使用手册
版本：V3.3.0.7
发布：深圳华视电子读写设备有限公司
日期：2018年08月20日
📋 目录
📝 版本信息
| 序号 | 版本号 | 修改日期 | 修改内容 |
|---|---|---|---|
| 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函数
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内部调用了找卡和选卡函数，接口分开是为了调用者开发方便。
🔍 函数详细说明
数据获取函数（多字节版本）
基本信息获取
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); // 得到有效截止日期
扩展信息获取
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); // 获取追加地址
照片数据获取
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二进制数据
外国人专用函数
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); // 得到外国人证件版本
系统函数
int CVR_GetSAMID(char *SAMID); // 得到安全模块号
Unicode版本函数
所有上述函数都有对应的Unicode版本，函数名后缀加"U"：
int GetPeopleNameU(char *strTmp, int *strLen); // Unicode版本姓名获取
int GetPeopleSexU(char *strTmp, int *strLen); // Unicode版本性别获取
// ... 其他Unicode版本函数
🔄 函数调用流程
graph TD
A[CVR_InitComm] --> B{初始化成功?}
B -->|否| C[返回错误]
B -->|是| D[CVR_Authenticate]
D --> E{认证成功?}
E -->|否| F[返回错误]
E -->|是| G[CVR_Read_Content]
G --> H[GetPeopleName<br/>GetPeopleSex<br/>GetPeopleNation<br/>...<br/>其他getter函数]
H --> I[CVR_CloseComm]
⚙️ 核心函数说明
1. 初始化连接
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. 关闭端口
int CVR_CloseComm(void)
说明：本函数用于关闭PC到阅读器的连接。
参数：无
返回值：
| 值 | 意义 |
|---|---|
| 1 | 关闭成功 |
| 0 | 端口号不合法 |
| -1 | 端口已经关闭 |
| -2 | 动态库加载失败 |
3. 卡认证
int CVR_Authenticate(void)
说明：本函数用于读卡器和卡片之间的合法身份确认。卡认证循环间隔大于300ms。
参数：无
返回值：
| 值 | 意义 | 说明 |
|---|---|---|
| 1 | 正确 | 卡片认证成功 |
| 2 | 错误 | 寻卡失败 |
| 3 | 错误 | 选卡失败 |
| 4 | 错误 | 未连接读卡器 |
| 0 | 错误 | 动态库未加载 |
注意：若卡片放置后发生认证错误时，请移走卡片重新放置。
int CVR_AuthenticateForNoJudge(void)
说明：使用此接口读卡不用每次都拿起放下，可以一直读。此函数返回值一直为1。
4. 读卡操作
int CVR_Read_FPContent(void)
说明：本函数用于通过阅读器从第二代居民身份证中读取相应信息。卡认证成功以后才可做读卡操作，读卡完毕若继续读卡应移走二代证卡片重新放置做卡认证。
参数：无
返回值：
| 返回值 | 意义 |
|---|---|
| 1 | 正确 |
| 0 | 错误，读身份证失败 |
| 4 | 错误，身份证读卡器未连接 |
| 99 | 动态库未加载 |
5. 获取性别代码
int GetSexCode(unsigned char *sexData, int *pLen)
说明：本函数获取性别代码
参数：
| 参数名 | 含义 | 取值范围 |
|---|---|---|
| unsigned char *sexData | 缓冲区地址 | |
| int *pLen | 缓冲区长度指针 | 4字节 |
返回值：
| 值 | 意义 |
|---|---|
| 1 | 正确 |
| 0 | 错误 |
6. 获取民族代码
int GetNationCode(unsigned char *nationData, int *pLen)
说明：本函数获取民族代码
参数：
| 参数名 | 含义 | 取值范围 |
|---|---|---|
| unsigned char *nationData | 缓冲区地址 | |
| int *pLen | 缓冲区长度指针 | 4字节 |
返回值：
| 值 | 意义 |
|---|---|
| 1 | 正确 |
| 0 | 错误 |
7. 获取设备状态
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
🛠️ 其他函数用法
读各项文字信息到自定义内存缓冲
函数原型：
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。
本手册是操作身份证阅读器动态库应用函数的定义格式、调用方法和返回值的说明。