精伦IDR210通用二次开发文档.doc

1. 概述精伦电子开发的二代身份证读卡系列机具适用于相关行业的联机型应用。产品提供了完善的二次软件开发接口（API）。本手册对开发接口的文件组成、函数定义格式、调用方法及返回值等进行详细的说明.本通用开发包支持的设备型号如下：1、 iDR200（串口和USB口）。2、 iDR320（必须进入“同步应用模式）。3、 iDR400-1（必须进入“同步模式）。4、 iDR210（USB-HID免驱动接口）.5、 iDR210（串口）.注意：完全兼容原2。0版本开发接口,支持USBHID接口和串口的iDR210。1、如果使用原开发包采用动态调用dll方式，只需直接替换原dll即可。2、如果使用原开发包采用的静态调用方式，则在不改变代码的情况下，对原程序重新编译链接即可。2. 系统要求使用本API的PC机,必须满足下列条件：l Windows 98、Windows 2000 Pro、Windows 2000 Server、Windows XP.l 至少32兆内存(32M RAM or Larger）。l 至少10兆空闲硬盘空间（10M Free Hard Disk Space or Larger).l 至少一个空闲普通串口或USB口（视用户需求而定）。3. 接口文件说明接口文件包括:Dewlt.dll 相关动态联接库sdtapi。dll 相关动态联接库JpgDll。dll 相关动态联接库SavePhoto。dll 相关动态联接库sdtapi。h 相关动态联接库头文件适用开发语言：Visual C+ 5.0 及以后版本C+ Builder 5.0 及以后版本 Visual Basic 5.0 及以后版本 Delphi 3。0 及以后版本 PowerBuilder5。0 及以后版本4. 接口函数说明4.1. 端口函数4.1.1. 端口初始化函数原 型：int InitComm （int iPort）说 明：本函数用于打开串口或USB并检测读卡设备是否就绪.参 数：iPort:设置串口、USB、USB-HID（免驱动）接口串口1 16(十进制)例如:1： 1(COM1）2：2（COM2)USB10011001返 回 值:值意义1正确其它错误注：如果读卡机具连接的端口是确定的，可以直接使用相应端口号调用本函数。否则，可以采用循环查找的方式调用本函数。4.1.2. 端口关闭接口原 型：int CloseComm(void)说 明：本函数用于关闭已打开的端口,一般在调用InitComm成功并完成读卡任务后调用。参 数:无返 回 值：值意义1正确其它错误注意：如果不再使用已打开的端口,必须使用CloseComm函数关闭端口。4.2. 读二代证相关函数4.2.1. 卡认证接口原 型：int Authenticate (void)说 明:本函数用于发现身份证卡并选择卡。参 数:无返 回 值：值意义1正确0错误注：认证卡时，需要将身份证放置于读卡机具上方并做稍许时间的停留。如果函数返回错误表示没有发现卡或者卡停留时间太短.4.2.2. 读卡信息接口原 型:int ReadBaseMsg( unsigned char pMsg， int * len）;说 明:本函数用于读取卡中基本信息，包括文字信息与图像信息。文字信息已经分段解析，输出格式为单字节，且每一字段信息已经被表示为字符串。图象信息被解码后存为文件photo。bmp（在当前工作目录下).参 数： pMsg out 无符号字符指针,指向读到的文本信息。需要在调用时分配内存，字节数不小于192。函数调用成功后，各字段的文本信息已经转换为单字节形式，并表示为字符串格式。字段意义及偏移值如下所示:项目长度(字节）说明姓名31汉字性别3汉字民族10汉字出生日期9CCYYMMDD住址71汉字和数字公民身份号码19数字签发机关31汉字有效期起始日期9CCYYMMDD有效期截止日期9CCYYMMDD 有效期为长期的表示为汉字“长期”Lenout 整数， 返回总字符长度,可以给空值（NULL）。返 回 值:值意义1正确0错误原 型2:int ReadBaseMsgPhoto( unsigned char pMsg， int * len,char * directory）；说 明：本函数用于读取卡中基本信息，包括文字信息与图像信息.文字信息已经分段解析，输出格式为单字节，且每一字段信息已经被表示为字符串.图象信息被解码后存为文件photo。bmp（在directory指定目录下）。参 数: pMsg out 无符号字符指针,指向读到的文本信息。需要在调用时分配内存,字节数不小于192。函数调用成功后，各字段的文本信息已经转换为单字节形式，并表示为字符串格式。字段意义及偏移值如下所示：项目长度（字节)说明姓名31汉字性别3汉字民族10汉字出生日期9CCYYMMDD住址71汉字和数字公民身份号码19数字签发机关31汉字有效期起始日期9CCYYMMDD有效期截止日期9CCYYMMDD 有效期为长期的表示为汉字“长期”Lenout 整数， 返回总字符长度，可以给空值（NULL）。 directoryin 字符指针,表示照片存储路径，路径最后有无“”均可;可以给空值（NULL)，表示照片存储在当前目录中，此时函数效果同ReadBaseMsg。返 回 值：值意义1正确0错误4目录不存在原 型3：int ReadBaseInfos( char Name, char * Gender， char * Folk,char BirthDay, char * Code， char * Address，char *Agency, char ExpireStart，char* ExpireEnd） 说 明：本函数用于读取卡中基本信息,包括文字信息与图像信息。文字信息以字符串格式输出。照片信息被解码后存为文件photo.bmp，身份证正面图片1。jpg，身份证反面图片2。jpg（在当前工作目录下)。参 数： Nameout 字符型指针,指向姓名信息。需要在调用时分配内存，字节数不小31.Genderout 字符型指针，指向性别信息(男或者女）.需要在调用时分配内存，字节数不小3。Folkout 字符型指针，指向民族信息。需要在调用时分配内存，字节数不小10.BirthDayout 字符型指针,指向出生日期信息.需要在调用时分配内存,字节数不小9，前四位为出生年，第5位到第6位是出生月,后两位是出生日，格式为:CCYYMMDD。Codeout 字符型指针，指向身份证号码信息。需要在调用时分配内存,字节数不小19。Addressout 字符型指针，指向地址信息。需要在调用时分配内存,字节数不小71.Agencyout 字符型指针，指向签证机关信息。需要在调用时分配内存，字节数不小31.ExpireStartout 字符型指针,指向有效期起始日期信息。需要在调用时分配内存,字节数不小9, 格式为:CCYYMMDD。ExpireEndout 字符型指针，指向有效期截至日期信息。需要在调用时分配内存，字节数不小9,格式为：CCYYMMDD，有效期为长期的表示为汉字“长期”。返 回 值：值意义1正确0错误原 型4：int ReadBaseInfosPhoto( 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指定目录下)。参 数： Nameout 字符型指针，指向姓名信息。需要在调用时分配内存,字节数不小31。Genderout 字符型指针，指向性别信息(男或者女).需要在调用时分配内存，字节数不小3。Folkout 字符型指针，指向民族信息.需要在调用时分配内存，字节数不小10.BirthDayout 字符型指针，指向出生日期信息。需要在调用时分配内存，字节数不小9，前四位为出生年，第5位到第6位是出生月，后两位是出生日，格式为：CCYYMMDD。Codeout 字符型指针，指向身份证号码信息。需要在调用时分配内存，字节数不小19。Addressout 字符型指针，指向地址信息。需要在调用时分配内存,字节数不小71。Agencyout 字符型指针,指向签证机关信息.需要在调用时分配内存，字节数不小31。ExpireStartout 字符型指针，指向有效期起始日期信息。需要在调用时分配内存，字节数不小9, 格式为：CCYYMMDD。ExpireEndout 字符型指针，指向有效期截至日期信息。需要在调用时分配内存，字节数不小9，格式为：CCYYMMDD，有效期为长期的表示为汉字“长期.directoryin 字符指针,表示照片存储路径，路径最后有无“均可;可以给空值（NULL），表示照片存储在当前目录中，此时函数效果同ReadBaseInfos。返 回 值：值意义1正确0错误4目录不存在原 型5：int ReadBaseMsgW( unsigned char pMsg， int * len）；说 明：本函数用于读取卡中基本信息，包括文字信息与图像信息.文字信息未解析，文字信息采用GB13000的UCS-2进行存储，图象信息被解码后存为文件photo.bmp（在当前工作目录下）。参 数: pMsg out 无符号字符指针，指向读到的文本信息。需要在调用时分配内存，字节数不小于256。偏移值如下所示：项目长度（字节)说明姓名30汉字性别2代码民族4代码出生16年月日:YYYYMMDD住址70汉字和数字公民身份号码36数字签发机关30汉字有效期起始日期16年月日：YYYYMMDD有效期截止日期16年月日：YYYYMMDD有效期为长期时存储“长期”最新住址70汉字和数字Lenout 整数， 返回基本信息长度。返 回 值：值意义1正确0错误原 型6：int ReadBaseMsgWPhoto（ unsigned char * 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汉字和数字Lenout 整数， 返回基本信息长度.directoryin 字符指针,表示照片存储路径,路径最后有无“均可;可以给空值（NULL),表示照片存储在当前目录中,此时函数效果同ReadBaseMsgW。返 回 值：值意义1正确0错误4目录不存在注：读卡基本信息时,需要将身份证置于读卡机具上方做稍许时间的停留。4.2.3. 读追加地址信息原 型1：int ReadNewAppMsg（ unsigned char pMsg， int * num ）；说 明：本函数用于读取卡中追加地址信息，输出格式为单字节字符串格式.参 数： pMsg out 无符号字符指针，指向读到的追加地址信息。需要在调用时分配内存，字节数不小于284.字段意义及偏移值如下所示：项目长度(字节）说明追加地址171汉字和数字追加地址271汉字和数字追加地址371汉字和数字追加地址471汉字和数字numout 整数， 返回读到的追加地址数。最多为4个.返 回 值:值意义1正确0错误原 型2：int ReadNewAppInfos( unsigned char addr1， unsigned char addr2,unsigned char * addr3， unsigned char addr4，int * num ）；说 明:本函数用于读取卡中追加地址信息，输出格式为单字节字符串格式。参 数: addr1、addr2、addr3、addr4out 无符号字符指针,分别指向读到的追加地址信息。需要在调用时分配内存,字节数分别不小于71.numout 整数, 返回读到的追加地址数.最多为4个。返 回 值:值意义1正确0错误原 型3：int ReadNewAppMsgW( unsigned char pMsg, int * num ）；说 明：本函数用于读取卡中追加地址信息，信息采用GB13000的UCS-2进行存储。参 数： pMsg out 无符号字符指针,指向读到的追加地址信息.需要在调用时分配内存，字节数不小于280。偏移值如下所示:项目长度(字节）说明追加地址170汉字和数字追加地址270汉字和数字追加地址370汉字和数字追加地址470汉字和数字numout 整数, 返回读到的追加地址数.最多为4个。返 回 值:值意义1正确0错误注：读追加地址信息时，需要将身份证置于读卡机具上方做稍许时间的停留。4.2.4. 读卡体管理号原 型：int ReadIINSNDN( char * pMsg );说 明:本函数用于读取身份证卡的管理号.参 数： pMsg out 字符指针,需要在调用时分配内存,字节数不小于16。返回8个16进制证卡序列号。返 回 值：值意义1正确0错误4.2.5. 读模块序列号原 型：int GetSAMIDToStr（ char *pcSAMID ）;说 明:本函数用于读取验证安全控制模块（SAM_V）的序列号。参 数： pcSAMID out 字符指针，需要在调用时分配内存，字节数不小于37。模块序列号分为5个部分，格式为2字符.2字符8字符10字符10字符,共36个字符；返 回 值:值意义1正确0错误4.3. Type A卡相关函数注意：串口型iDR200和iDR210支持读写Type A卡。iDR210使用Routon开头的相关函数。串口型iDR200使用dc_开头的相关函数。4.3.1. dc_init注意：仅串口型iDR200可使用本接口，iDR210使用InitComm（）进行端口初始化.原 型：int dc_init(int port,long baud);说 明：初始化通讯口。参 数: port：取值为116。 baud：为通讯波特率9600115200.返 回 值：成功则返回串口通讯设备标识符0,失败返回负值。4.3.2. dc_exit注意：仅串口型iDR200可使用本接口,iDR210使用CloseComm(）关闭端口.原 型：int dc_exit(int dev);说 明：关闭端口。参 数: icdev:通讯设备标识符。返 回 值：成功返回0，失败返回负值.4.3.3. dc_request原 型：int dc_request（int icdev，unsigned char _Mode，unsigned int *TagType)；说 明:寻卡请求.参 数： icdev：通讯设备标识符。_Mode：寻卡模式。0表示Standard模式；1表示All模式。Tagtype：卡类型值.返 回 值：成功返回0，失败返回负值。4.3.4. dc_anticoll原 型：int dc_anticoll（int icdev,unsigned char _Bcnt,unsigned long *_Snr);说 明：防卡冲突，返回卡的序列号.参 数： icdev：通讯设备标识符。 _Bcn： 设为0。 _Snr：返回的卡序列号地址。返 回 值：成功返回0，失败返回负值。4.3.5. dc_select原 型：int dc_select(int icdev,unsigned long _Snr，unsigned char *_Size）;说 明：从多个卡中选取一个给定序列号的卡.参 数： icdev:通讯设备标识符。 _Snr:卡序列号。 _Size：指向返回的卡容量的数据（暂不支持，无返回）.返 回 值：成功返回0,失败返回负值.4.3.6. dc_authentication_passaddr原 型：int dc_authentication_passaddr（int icdev， unsigned char _Mode， unsigned char Addr, unsigned char *passbuff）;说 明：核对密码函数。参 数: Icdev:通讯设备标识符。 _Mode：密码验证模式.0x60 keyA，0x61 keyB. blockAddr：要验证密码的块地址号. passbuff:密码字符串。返 回 值:成功返回0，失败返回负值.4.3.7. dc_read原 型:dc_read(int icdev,unsigned char _Adr，unsigned char _Data）；说 明：读取卡中数据.参 数： icdev:通讯设备标识符. _Adr：M1S50卡-块地址(063），M1S70（0255)。 _Data：读出数据.返 回 值:成功返回0，失败返回负值.4.3.8. dc_write原 型：dc_write（int icdev，unsigned char _Adr,unsigned char *_Data)；说 明：向卡中写入数据.参 数： icdev：通讯设备标识符。 _Adr：M1S50卡-块地址(163）,M1S70（1255). _Data：要写入的数据。返 回 值：成功返回0，失败返回负值。4.3.9. dc_halt原 型:dc_halt(int icdev）;说 明：中止对该卡操作。参 数: icdev：通讯设备标识符。 返 回 值:成功返回0，失败返回负值。4.3.10. dc_BeepLED原 型：dc_BeepLED(int icdev,bool BeepON,bool LEDON，unsigned int duration);说 明:控制LED指示灯和蜂鸣器。参 数： icdev：通讯设备标识符。 BeepON：值为true时,蜂鸣器打开。LEDON：值为true时,指示灯打开。duration为持续的时间，单位为毫秒。返 回 值：成功返回0，失败返回负值。4.3.11. 找IC卡原 型：int Routon_IC_FindCard（)；说 明：本函数用于寻卡。参 数： 无。返 回 值：值意义1正确0错误4.3.12. 读IC卡序列号高级函数原 型：int Routon_IC_HL_ReadCardSN（char SN）；说 明：本函数用于读取IC卡的序列号,自动完成找卡、选卡等过程。参 数: SN out 字符指针，需要在调用时分配内存，字节数不小于16。返 回 值：值意义1正确0错误4.3.13. 读IC卡区块高级函数原 型：int Routon_IC_HL_ReadCard （int SID，int BID,int KeyType,unsigned char * Key,unsigned char data)；说 明：本函数用于读取IC卡指定扇区的数据内容，自动完成找卡、选卡、认证等过程。参 数： SID为扇区号，015之间（对M1S50卡）.BID为块号，0-3之间。KeyType为密钥类型,两种：0x60 keyA，0x61 keyB。Key为密钥。data为读取到的数据内容，需要在调用时分配内存，字节数不小于16。返 回 值：值意义1正确0错误4.3.14. 写IC卡区块高级函数原 型：int Routon_IC_HL_WriteCard （int SID，int BID，int KeyType,unsigned char Key,unsigned char data）；说 明：本函数用于向IC卡指定扇区写入数据内容,自动完成找卡、选卡、认证等过程。参 数： SID为扇区号，0-15之间（对M1S50卡）.BID为块号,03之间。KeyType为密钥类型,两种:0x60 keyA,0x61 keyB.Key为密钥。data为准备写入的数据内容，字节数为16。返 回 值:值意义1正确0错误4.3.15. 控制蜂鸣器和指示灯原 型1：int HID_BeepLED(bool BeepON,bool LEDON,unsigned int duration）;说 明：本函数用于控制iDR210 USB-HID 设备的LED指示灯和蜂鸣器。参 数： BeepON和LEDON为布尔类型，值为True时，对应的蜂鸣器和指示灯打开；duration为打开持续的时间，单位为毫秒。返 回 值:值意义1正确0错误原 型2：int Routon_BeepLED(bool BeepON,bool LEDON,unsigned int duration）；说 明:本函数用于控制iDR200 串口型设备LED指示灯和蜂鸣器.参 数： BeepON和LEDON为布尔类型,值为True时，对应的蜂鸣器和指示灯打开；duration为打开持续的时间，单位为毫秒。返 回 值:值意义1正确0错误4。4。1读取PSAM卡ATR数据原 型：int PSAM_ReadATR（unsigned char CardIndex，unsigned char SpeedIndex,unsigned char TypeIndex， unsigned char *_Data);说 明：本函数用于读取设备上PSAM卡的ATR数据参 数： CardIndex： 0x01为卡座1， 0x02为卡座2SpeedIndex： 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卡发送数据原 型：int PSAM_SendCMD(unsigned char CardIndex，unsigned char *_Cmd，int Len， unsigned char *_Data)说 明：本函数用于向PSAM卡发送数据参 数： CardIndex：0x01为卡座1， 0x02为卡座2_Cmd:向PSAM卡发送命令数据缓冲区指针Len:命令的长度_Data：PSAM卡返回数据缓存区指针返 回 值：值意义0正确1未知错误-2设置卡座错误-3设备未连接4.4.2 PSAM卡下电原 型：int STDCALL PSAM_PowerOff（unsigned char CardIndex）说 明:本函数用于断开PSAM卡电源，降低功耗参 数： CardIndex:0x01为卡座1， 0x02为卡座2返 回 值:值意义0正确1未知错误-2设置卡座错误-3设备未连接5. 接口使用流程及示例在连接好读卡机具以后,首先需要调用函数InitComm打开相应端口。打开端口成功以后，即可以循环的认证并读取卡中信息。5.1. 二代证示例示 例:#include “sdtapi。h”int main（)int ret;int iPort=1; ret=InitComm（iPort);if （ ret )ret= Authenticate ();if （ret)char Msg200;ret= ReadBaseMsg （Msg， 0 )；if (ret 0 )/显示文字及图片信息char Msg1200;int num;ret= ReadNewAppMsg （Msg1, &num )；if （ret 0 ）/显示追加地址信息ret= CloseComm（);return ret;5.2. TypeA卡示例示 例：#include “sdtapi.h” int main() int ret; int dev; dev=dc_init（1，9600); unsigned int spc=0; if （dev0） unsigned long sn=0； ret=dc_request(dev，0，&spc）； if （ret=0) ret=dc_anticoll（dev,0，sn）; unsigned char size; if (ret=0) ret=dc_select(dev,sn，size）； unsigned char pw6=0xff,0xff,0xff,0xff,0xff,0xff； if (ret=0） ret=dc_authentication_passaddr(dev,0x60,1,pw); unsigned char wr16=0x01,0x02，0x01,0x02，0x01，0x02,0x01,0x02,0x01，0x02，0x01,0x02，0x01,0x02，0x15，0x16; if (ret=0） ret=dc_write（dev,1,wr)； unsigned char da16=0； if （ret=0) ret=dc_read(dev,1，da)； ret=dc_BeepLED（dev,false，true，100）； Sleep（100); ret=dc_BeepLED（dev，true,true，100）; ret=dc_exit(dev）;