精伦身份证二次开发接口说明V32.docx
《精伦身份证二次开发接口说明V32.docx》由会员分享，可在线阅读，更多相关《精伦身份证二次开发接口说明V32.docx（26页珍藏版）》请在冰豆网上搜索。
精伦身份证二次开发接口说明V32
1.概述
精伦电子开发的二代身份证读卡系列机具适用于相关行业的联机型应用。
产品提供了完善的二次软件开发接口（API）。
本手册对开发接口的文件组成、函数定义格式、调用方法及返回值等进行详细的说明。
本通用开发包支持的设备型号如下：
1、iDR200（串口和USB口）。
2、iDR320（必须进入“同步应用”模式）。
3、iDR400-1（必须进入“同步”模式）。
4、iDR210（USB-HID免驱动接口）。
5、iDR210（串口）。
注意：
完全兼容原2.0版本开发接口，支持USB-HID接口和串口的iDR210。
1、如果使用原开发包采用动态调用dll方式，只需直接替换原dll即可。
2、如果使用原开发包采用的静态调用方式，则在不改变代码的情况下，对原程序重新编译链接即可。
2.系统要求
使用本API的PC机，必须满足下列条件：
●Windows98、Windows2000Pro、Windows2000Server、
WindowsXP。
●至少32兆内存（32MRAMorLarger）。
●至少10兆空闲硬盘空间（10MFreeHardDiskSpaceorLarger）。
●至少一个空闲普通串口或USB口（视用户需求而定）。
3.接口文件说明
接口文件包括：
Dewlt.dll相关动态联接库
sdtapi.dll相关动态联接库
JpgDll.dll相关动态联接库
SavePhoto.dll相关动态联接库
sdtapi.h相关动态联接库头文件
适用开发语言：
VisualC++5.0及以后版本
C++Builder5.0及以后版本
VisualBasic5.0及以后版本
Delphi3.0及以后版本
PowerBuilder5.0及以后版本
4.接口函数说明
4.1.端口函数
4.1.1.端口初始化函数
原型：
intInitComm（intiPort）
说明：
本函数用于打开串口或USB并检测读卡设备是否就绪。
参数：
iPort：
设置串口、USB、USB-HID（免驱动）接口
串口
1–16（十进制）
例如：
1：
1（COM1）
2：
2（COM2）
USB
1001
1001
返回值：
值
意义
1
正确
其它
错误
注：
如果读卡机具连接的端口是确定的，可以直接使用相应端口号调用本函数。
否则，可以采用循环查找的方式调用本函数。
4.1.2.端口关闭接口
原型：
intCloseComm（void）
说明：
本函数用于关闭已打开的端口，一般在调用InitComm成功并完成读卡任务后调用。
参数：
无
返回值：
值
意义
1
正确
其它
错误
注意：
如果不再使用已打开的端口，必须使用CloseComm函数关闭端口。
4.2.读二代证相关函数
4.2.1.卡认证接口
原型：
intAuthenticate（void）
说明：
本函数用于发现身份证卡并选择卡。
参数：
无
返回值：
值
意义
1
正确
0
错误
注：
认证卡时，需要将身份证放置于读卡机具上方并做稍许时间的停留。
如果函数返回错误表示没有发现卡或者卡停留时间太短。
4.2.2.读卡信息接口
原型：
intReadBaseMsg（unsignedchar*pMsg,int*len）；
说明：
本函数用于读取卡中基本信息，包括文字信息与图像信息。
文字信息已经分段解析，输出格式为单字节,且每一字段信息已经被表示为字符串。
图象信息被解码后存为文件photo.bmp（在当前工作目录下）。
参数：
pMsg[out]无符号字符指针，指向读到的文本信息。
需要在调用时分配内存，字节数不小于192。
函数调用成功后，各字段的文本信息已经转换为单字节形式，并表示为字符串格式。
字段意义及偏移值如下所示：
项目
长度（字节）
说明
姓名
31
汉字
性别
3
汉字
民族
10
汉字
出生日期
9
CCYYMMDD
住址
71
汉字和数字
公民身份号码
19
数字
签发机关
31
汉字
有效期起始日期
9
CCYYMMDD
有效期截止日期
9
CCYYMMDD
有效期为长期的表示为汉字“长期”
Len[out]整数，返回总字符长度，可以给空值（NULL）。
返回值：
值
意义
1
正确
0
错误
原型2：
intReadBaseMsgPhoto（unsignedchar*pMsg,int*len,char*directory）；
说明：
本函数用于读取卡中基本信息，包括文字信息与图像信息。
文字信息已经分段解析，输出格式为单字节,且每一字段信息已经被表示为字符串。
图象信息被解码后存为文件photo.bmp（在directory指定目录下）。
参数：
pMsg[out]无符号字符指针，指向读到的文本信息。
需要在调用时分配内存，字节数不小于192。
函数调用成功后，各字段的文本信息已经转换为单字节形式，并表示为字符串格式。
字段意义及偏移值如下所示：
项目
长度（字节）
说明
姓名
31
汉字
性别
3
汉字
民族
10
汉字
出生日期
9
CCYYMMDD
住址
71
汉字和数字
公民身份号码
19
数字
签发机关
31
汉字
有效期起始日期
9
CCYYMMDD
有效期截止日期
9
CCYYMMDD
有效期为长期的表示为汉字“长期”
Len[out]整数，返回总字符长度，可以给空值（NULL）。
directory[in]字符指针,表示照片存储路径，路径最后有无“\”均可；可以给空值（NULL），表示照片存储在当前目录中，此时函数效果同ReadBaseMsg。
返回值：
值
意义
1
正确
0
错误
4
目录不存在
原型3：
intReadBaseInfos（char*Name,char*Gender,char*Folk,
char*BirthDay,char*Code,char*Address,char*Agency,char*ExpireStart，char*ExpireEnd）
说明：
本函数用于读取卡中基本信息，包括文字信息与图像信息。
文字信息以字符串格式输出。
照片信息被解码后存为文件photo.bmp，身份证正面图片1.jpg，身份证反面图片2.jpg（在当前工作目录下）。
参数：
Name[out]字符型指针，指向姓名信息。
需要在调用时分配内存，字节数不小31。
Gender[out]字符型指针，指向性别信息（男或者女）。
需要在调用时分配内存，字节数不小3。
Folk[out]字符型指针，指向民族信息。
需要在调用时分配内存，字节数不小10。
BirthDay[out]字符型指针，指向出生日期信息。
需要在调用时分配内存，字节数不小9，前四位为出生年，第5位到第6位是出生月，后两位是出生日，格式为：
CCYYMMDD。
Code[out]字符型指针，指向身份证号码信息。
需要在调用时分配内存，字节数不小19。
Address[out]字符型指针，指向地址信息。
需要在调用时分配内存，字节数不小71。
Agency[out]字符型指针，指向签证机关信息。
需要在调用时分配内存，字节数不小31。
ExpireStart[out]字符型指针，指向有效期起始日期信息。
需要在调用时分配内存，字节数不小9,格式为：
CCYYMMDD。
ExpireEnd[out]字符型指针，指向有效期截至日期信息。
需要在调用时分配内存，字节数不小9，格式为：
CCYYMMDD，有效期为长期的表示为汉字“长期”。
返回值：
值
意义
1
正确
0
错误
原型4：
intReadBaseInfosPhoto（char*Name,char*Gender,char*Folk,char*BirthDay,char*Code,char*Address,char*Agency,char*ExpireStart，char*ExpireEnd,char*directory）
说明：
本函数用于读取卡中基本信息，包括文字信息与图像信息。
文字信息以字符串格式输出。
图象信息被解码后存为照片photo.bmp和photo.jpg，身份证正面图片1.jpg，身份证反面图片2.jpg（在directory指定目录下）。
参数：
Name[out]字符型指针，指向姓名信息。
需要在调用时分配内存，字节数不小31。
Gender[out]字符型指针，指向性别信息（男或者女）。
需要在调用时分配内存，字节数不小3。
Folk[out]字符型指针，指向民族信息。
需要在调用时分配内存，字节数不小10。
BirthDay[out]字符型指针，指向出生日期信息。
需要在调用时分配内存，字节数不小9，前四位为出生年，第5位到第6位是出生月，后两位是出生日，格式为：
CCYYMMDD。
Code[out]字符型指针，指向身份证号码信息。
需要在调用时分配内存，字节数不小19。
Address[out]字符型指针，指向地址信息。
需要在调用时分配内存，字节数不小71。
Agency[out]字符型指针，指向签证机关信息。
需要在调用时分配内存，字节数不小31。
ExpireStart[out]字符型指针，指向有效期起始日期信息。
需要在调用时分配内存，字节数不小9,格式为：
CCYYMMDD。
ExpireEnd[out]字符型指针，指向有效期截至日期信息。
需要在调用时分配内存，字节数不小9，格式为：
CCYYMMDD，有效期为长期的表示为汉字“长期”。
directory[in]字符指针,表示照片存储路径，路径最后有无“\”均可；可以给空值（NULL），表示照片存储在当前目录中，此时函数效果同ReadBaseInfos。
返回值：
值
意义
1
正确
0
错误
4
目录不存在
原型5：
intReadBaseMsgW（unsignedchar*pMsg,int*len）；
说明：
本函数用于读取卡中基本信息，包括文字信息与图像信息。
文字信息未解析，文字信息采用GB13000的UCS-2进行存储，图象信息被解码后存为文件photo.bmp（在当前工作目录下）。
参数：
pMsg[out]无符号字符指针，指向读到的文本信息。
需要在调用时分配内存，字节数不小于256。
偏移值如下所示：
项目
长度（字节）
说明
姓名
30
汉字
性别
2
代码
民族
4
代码
出生
16
年月日：
YYYYMMDD
住址
70
汉字和数字
公民身份号码
36
数字
签发机关
30
汉字
有效期起始日期
16
年月日：
YYYYMMDD
有效期截止日期
16
年月日：
YYYYMMDD
有效期为长期时存储“长期”
最新住址
70
汉字和数字
Len[out]整数，返回基本信息长度。
返回值：
值
意义
1
正确
0
错误
原型6：
intReadBaseMsgWPhoto（unsignedchar*pMsg,int*len,char*directory））；
说明：
本函数用于读取卡中基本信息，包括文字信息与图像信息。
文字信息未解析，文字信息采用GB13000的UCS-2进行存储，图象信息被解码后存为文件photo.bmp（在directory指定目录下）。
参数：
pMsg[out]无符号字符指针，指向读到的文本信息。
需要在调用时分配内存，字节数不小于256。
偏移值如下所示：
项目
长度（字节）
说明
姓名
30
汉字
性别
2
代码
民族
4
代码
出生
16
年月日：
YYYYMMDD
住址
70
汉字和数字
公民身份号码
36
数字
签发机关
30
汉字
有效期起始日期
16
年月日：
YYYYMMDD
有效期截止日期
16
年月日：
YYYYMMDD
有效期为长期时存储“长期”
最新住址
70
汉字和数字
Len[out]整数，返回基本信息长度。
directory[in]字符指针,表示照片存储路径，路径最后有无“\”均可；可以给空值（NULL），表示照片存储在当前目录中，此时函数效果同ReadBaseMsgW。
返回值：
值
意义
1
正确
0
错误
4
目录不存在
注：
读卡基本信息时，需要将身份证置于读卡机具上方做稍许时间的停留。
4.2.3.读追加地址信息
原型1：
intReadNewAppMsg（unsignedchar*pMsg,int*num）；
说明：
本函数用于读取卡中追加地址信息，输出格式为单字节字符串格式。
参数：
pMsg[out]无符号字符指针，指向读到的追加地址信息。
需要在调用时分配内存，字节数不小于284。
字段意义及偏移值如下所示：
项目
长度（字节）
说明
追加地址1
71
汉字和数字
追加地址2
71
汉字和数字
追加地址3
71
汉字和数字
追加地址4
71
汉字和数字
num[out]整数，返回读到的追加地址数。
最多为4个。
返回值：
值
意义
1
正确
0
错误
原型2：
intReadNewAppInfos（unsignedchar*addr1,
unsignedchar*addr2,unsignedchar*addr3,
unsignedchar*addr4,int*num）；
说明：
本函数用于读取卡中追加地址信息，输出格式为单字节字符串格式。
参数：
addr1、addr2、addr3、addr4[out]无符号字符指针，分别指向读到的追加地址信息。
需要在调用时分配内存，字节数分别不小于71。
num[out]整数，返回读到的追加地址数。
最多为4个。
返回值：
值
意义
1
正确
0
错误
原型3：
intReadNewAppMsgW（unsignedchar*pMsg,int*num）；
说明：
本函数用于读取卡中追加地址信息，信息采用GB13000的UCS-2进行存储。
参数：
pMsg[out]无符号字符指针，指向读到的追加地址信息。
需要在调用时分配内存，字节数不小于280。
偏移值如下所示：
项目
长度（字节）
说明
追加地址1
70
汉字和数字
追加地址2
70
汉字和数字
追加地址3
70
汉字和数字
追加地址4
70
汉字和数字
num[out]整数，返回读到的追加地址数。
最多为4个。
返回值：
值
意义
1
正确
0
错误
注：
读追加地址信息时，需要将身份证置于读卡机具上方做稍许时间的停留。
4.2.4.读卡体管理号
原型：
intReadIINSNDN（char*pMsg）；
说明：
本函数用于读取身份证卡的管理号。
参数：
pMsg[out]字符指针，需要在调用时分配内存，字节数不小于16。
返回8个16进制证卡序列号。
返回值：
值
意义
1
正确
0
错误
4.2.5.读模块序列号
原型：
intGetSAMIDToStr（char*pcSAMID）；
说明：
本函数用于读取验证安全控制模块（SAM_V）的序列号。
参数：
pcSAMID[out]字符指针，需要在调用时分配内存，字节数不小于37。
模块序列号分为5个部分，格式为『2字符.2字符－8字符－10字符－10字符』，共36个字符；
返回值：
值
意义
1
正确
0
错误
4.3.TypeA卡相关函数
注意：
串口型iDR200和iDR210支持读写TypeA卡。
iDR210使用Routon开头的相关函数。
串口型iDR200使用dc_开头的相关函数。
4.3.1.找IC卡
原型：
intRouton_IC_FindCard（）；
说明：
本函数用于寻卡。
参数：
无。
返回值：
值
意义
1
正确
0
错误
4.3.2.读IC卡序列号高级函数
原型：
intRouton_IC_HL_ReadCardSN（char*SN）；
说明：
本函数用于读取IC卡的序列号，自动完成找卡、选卡等过程。
参数：
SN[out]字符指针，需要在调用时分配内存，字节数不小于16。
返回值：
值
意义
1
正确
0
错误
4.3.3.读IC卡区块高级函数
原型：
intRouton_IC_HL_ReadCard（intSID,intBID,
intKeyType,unsignedchar*Key,
unsignedchar*data）；
说明：
本函数用于读取IC卡指定扇区的数据内容，自动完成找卡、选卡、认证等过程。
参数：
SID为扇区号，0-15之间（对M1S50卡）。
BID为块号，0-3之间。
KeyType为密钥类型，两种：
0x60keyA，0x61keyB。
Key为密钥。
data为读取到的数据内容，需要在调用时分配内存，字节数不小于16。
返回值：
值
意义
1
正确
0
错误
4.3.4.写IC卡区块高级函数
原型：
intRouton_IC_HL_WriteCard（intSID,intBID,
intKeyType,unsignedchar*Key,
unsignedchar*data）；
说明：
本函数用于向IC卡指定扇区写入数据内容，自动完成找卡、选卡、认证等过程。
参数：
SID为扇区号，0-15之间（对M1S50卡）。
BID为块号，0-3之间。
KeyType为密钥类型，两种：
0x60keyA，0x61keyB。
Key为密钥。
data为准备写入的数据内容，字节数为16。
返回值：
值
意义
1
正确
0
错误
4.3.5.控制蜂鸣器和指示灯
原型1：
intHID_BeepLED（boolBeepON,boolLEDON,unsignedintduration）；
说明：
本函数用于控制iDR210USB-HID设备的LED指示灯和蜂鸣器。
参数：
BeepON和LEDON为布尔类型，值为True时，对应的蜂鸣器和指示灯打开；duration为打开持续的时间，单位为毫秒。
返回值：
值
意义
1
正确
0
错误
原型2：
intRouton_BeepLED（boolBeepON,boolLEDON,unsignedintduration）；
说明：
本函数用于控制iDR200串口型设备LED指示灯和蜂鸣器。
参数：
BeepON和LEDON为布尔类型，值为True时，对应的蜂鸣器和指示灯打开；duration为打开持续的时间，单位为毫秒。
返回值：
值
意义
1
正确
0
错误
4.4.1读取PSAM卡ATR数据
原型：
intPSAM_ReadATR（unsignedcharCardIndex,unsignedcharSpeedIndex,unsignedcharTypeIndex,unsignedchar*_Data）;
说明：
本函数用于读取设备上PSAM卡的ATR数据
参数：
CardIndex：
0x01为卡座1，0x02为卡座2
SpeedIndex:
CPU卡的速率（0:
4800,1:
9600,2:
19200,3:
38400）
TypeIndex:
CPU卡电压类型（0:
5V,1:
3V）
*_Data:
读出数据缓存区指针
返回值：
值
意义
0
正确
-1
未插卡
-2
设置卡座错误
-3
设置速率错误
-4
设置电压错误
-5
设备未连接
4.4.2向PSAM卡发送数据
原型：
intPSAM_SendCMD（unsignedcharCardIndex,unsignedchar*_Cmd,intLen,unsignedchar*_Data）
说明：
本函数用于向PSAM卡发送数据
参数：
CardIndex：
0x01为卡座1，0x02为卡座2
*_Cmd:
向PSAM卡发送命令数据缓冲区指针
Len:
命令的长度
*_Data:
PSAM卡返回数据缓存区指针
返回值：
值
意义
0
正确
-1
未知错误
-2
设置卡座错误
-3
设备未连接
4.4.2PSAM卡下电
原型：
intSTDCALLPSAM_PowerOff（unsignedcharCardIndex）
说明：
本函数用于断开PSAM卡电源，降低功耗
参数：
CardIndex：
0x01为卡座1，0x02为卡座2
返回值：
值
意义
0
正确
-1
未知错误
-2
设置卡座错误
-3
设备未连接
4.3.6.dc_init
注意：
仅串口型iDR200可使用本接口，iDR210使用InitComm（）进行端口初始化。
原型：
intdc_init（intport,longbaud）;
说明：
初始化通讯口。
参数：
port：
取值为1～16。
baud：
为通讯波特率9600～115200。
返回值：
成功则返回串口通讯设备标识符>0，失败返回负值。
4.3.7.dc_exit
注意：
仅串口型iDR200可使用本接口，iDR210使用CloseComm（）关闭端口。
原型：
intdc_exit（intdev）;
说明：
关闭端口。
参数：
icdev：
通讯设备标识符。
返回值：
成功返回0，失败返回负值。
4.3.8.dc_request
原型：
intdc_request（inticdev,unsignedchar_Mode,unsignedint*TagType）;
说明：
寻卡请求。
参数：
icdev：
通讯设备标识符。
_Mode：
寻卡模式。
0表示Standard模式；1表示All模式。
Tagtype：
卡类型值。
返回值：
成功返回0，失败返回负值。
4.3.9.dc_anticoll
原型：
intdc_anticoll
升级会员 