|
新中新身份证阅读器二代证SDK开发包开发说明
二代证SDK开发包开发说明
一、系统的基本要求
a) Windows 98，Windows 2000 Pro,Windows 2000 Server,WinXP，Windows Vista，Windows7
b) 至少32兆内存（32M RAM or Larger）
c) 至少10兆空闲硬盘空间（10M Free Hard Disk Space or Larger）
d) 至少一个空闲普通串口或USB口（视用户需求而定）。
二、SDK函数说明
（一）端口类API：
Syn_SetMaxRFByte 设置射频适配器最大通信字节数
int Syn_SetMaxRFByte (
int iPort,
unsigned char ucByte,
int bIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。串口0001至0016，USB1001至1016
ucByte
[in] 无符号字符，24-255，表示射频适配器最大通信字节数。
iIfOpen
[in] 整数，非0表示在API函数内部包含了打开端口和关闭端口函数，0表示在API函数内部不包含了打开端口和关闭端口函数
返回值：
0 成功
其他 失败（具体含义参见返回码表）
Syn_GetCOMBaud 查看串口当前波特率(该函数只用于SAM采用RS232串口的情形，如果采用USB接口则不支持该API)。
int Syn_GetCOMBaud (
int iPort,
unsigned int * puiBaudRate
);
参数说明：
iPort
[in] 整数，表示端口号。此处端口号必须为1-16，表示串口
puiBaudRate
[out] 无符号整数指针，指向普通串口当前波特率, 默认情况下为115200。
返回值：
0 成功
0X01 端口打开失败/端口号不合法
0X05 无法获得该SAM的波特率，该SAM串口不可用。
Syn_GetCOMBaudEx 查看串口当前波特率(该函数只用于SAM采用RS232串口的情形，如果采用USB接口则不支持该API)。
int Syn_GetCOMBaudEx (
int iPort,
);
参数说明：
iPort
[in] 整数，表示端口号。此处端口号必须为1-16，表示串口
返回值：
0 失败 其他为读卡器当前波特率
Syn_SetCOMBaud 设置SAM的串口的波特率(该函数只用于SAM采用RS232串口的情形，如果采用USB接口则不支持该API)，设置成功后，在该SAM和主机注册表中都记录设置后的波特率，保证在SAM重新启动和该套API被重新调用时采用设置后的波特率。该函数调用成功后，需要延时5毫秒，然后才能继续与SAM通信。
int Syn_SetCOMBaud (
int iPort,
unsigned int uiCurrBaud,
unsigned int uiSetBaud
);
参数说明：
iPort
[in] 整数，表示端口号。此处端口号必须为1-16，表示串口。
uiCurrBaud
[in] 无符号整数，调用该API前已设置的业务终端与SAM通信的波特率(SAM出厂时默认,业务终端与SAM通信的波特率为115200).业务终端以该波特率与SAM通信,发出设置SAM新波特率的命令.。uiCurrBaud只能为下列数值之一：115200，57600，38400，19200，9600.如果uiCurrBaud数值不是这些值之一，函数返回0X21;如果已设置的波特率与uiCurrBaud不一致, 则函数返回0X02,表示不能设置,调用API不成功。
uiSetBaud
[in] 无符号整数，将要设置的SAM与业务终端通信波特率。uiSetBaud只能取下列值之一:：115200，57600，38400，19200，9600，如果输入uiSetBaud参数不是这些数值之一,，函数返回0X21,设置不成功,保持原来的波特率不变。
返回值：
0 成功
0X01 端口打开失败/端口号不合法。
0X02 超时，设置不成功。
0X21 uiCurrBaud 、uiSetBaud输入参数数值错误。
Syn_OpenPort 打开端口
int Syn_OpenPort(
int iPort
);
参数说明：
iPort
[in] 整数，表示端口号。1-16（十进制）为串口，1001-1016（十进制）为USB口，USB的端口设置参看“USB设备配置使用手册”。
返回值：
0 打开端口成功
0X01 打开端口失败/端口号不合法
Syn_ClosePort 关闭端口
int Syn_ClosePort (
int iPort
);
参数说明：
iPort
[in] 整数，表示端口号。
返回值：
0 关闭端口成功。
0x01 端口号不合法
（二）SAM类API：
Syn_ResetSAM对SAM复位
int Syn_ResetSAM (
int iPort,
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。根据SAM使用的接口不同(分为普通串口SAM和USB口SAM)，分别使用不同的端口号（目前串口和USB都只支持16个，即串口0001-0016和USB1001-1016）：
普通串口SAM
0001 – 0016(十进制)
例如：
0001：串口1(COM1)
0002：串口2(COM2)
USB口SAM
1001 – 1016(十进制)
例如：
1001：USB1
1002：USB2
iIfOpen
[in] 整数，0表示不在该函数内部打开和关闭串口，此时确保之前调用了Syn_OpenPort来打开端口，并且在不需要与端口通信时，调用Syn_ClosePort关闭端口；非0表示在API函数内部包含了打开端口和关闭端口函数，之前不需要调用Syn_OpenPort，也不用再调用Syn_ClosePort。
返回值：
0 成功
其他 失败（具体含义参见返回码表）
Syn_GetSAMStatus 对SAM进行状态检测。
int Syn_GetSAMStatus (
int iPort,
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。参见Syn_ResetSAM。
iIfOpen
[in] 整数，参见Syn_ResetSAM。
返回值：
0 SAM正常
0x60 自检失败，不能接收命令
其他 命令失败（具体含义参见返回码表）
Syn_GetSAMID 读取SAM的编号。
int Syn_GetSAMID (
int iPort,
unsigned char * pucSAMID,
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。参见Syn_ResetSAM。
pucSAMID
[out] 无符号字符串指针，指向读到的SAM编号， 16字节。
返回值：
0 成功
其他 失败（具体含义参见返回码表）
Syn_GetSAMIDToStr 读取SAM的编号。
int Syn_GetSAMIDToStr (
int iPort,
char * pcSAMID，
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。参见Syn_ResetSAM。
pcSAMID
[out] 字符串指针，指向读到的SAM编号。
iIfOpen
[in] 整数，参见Syn_ResetSAM。
返回值：
0 成功
其他 失败（具体含义参见返回码表）
Syn_FindReader 自动寻找读卡器。
int Syn_FindReader ();
返回值：
0 未找到
其他 1～16串口 1001～1016USB
（三）身份证卡类API：
Syn_StartFindIDCard 开始找卡。
int Syn_StartFindIDCard (
int iPort ,
unsigned char * pucIIN,
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。参见Syn_ResetSAM。
pucIIN
[out] 无符号字符指针，指向读到的IIN。
iIfOpen
[in] 整数，参见Syn_ResetSAM。
返回值：
0 找卡成功
0x80 找卡失败
Syn_SelectIDCard 选卡。
int Syn_ SelectIDCard (
int iPort ,
unsigned char * pucSN,
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。参见Syn_ResetSAM。
pucSN
[out] 无符号字符指针，指向读到的SN。
iIfOpen
[in] 整数，参见Syn_ResetSAM。
返回值：
0 选卡成功
0x81 选卡失败
Syn_ReadBaseMsg 读取ID卡内基本信息区域信息。
int Syn_ReadBaseMsg (
int iPort，
unsigned char *pucCHMsg，
unsigned int * puiCHMsgLen，
unsigned char *pucPHMsg，
unsigned int * puiPHMsgLen,
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。参见Syn_ResetSAM。
pucCHMsg
[out] 无符号字符指针，指向读到的文字信息。
puiCHMsgLen
[out] 无符号整型数指针，指向读到的文字信息长度。
pucPHMsg
[out] 无符号字符指针，指向读到的照片信息。
puiPHMsgLen
[out] 无符号整型数指针，指向读到的照片信息长度。
iIfOpen
[in] 整数，参见Syn_ResetSAM。
返回值：
0 读基本信息成功
其他 读基本信息失败（具体含义参见返回码表）
Syn_ReadIINSNDN 读取ID卡内IIN,SN和DN。
int Syn_ReadIINSNDN (
int iPort，
unsigned char *pucIINSNDN,
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。参见Syn_ResetSAM。
pucIINSNDN
[out] 无符号字符指针，指向读到的IIN,SN和DN,长度为固定28字节。
iIfOpen
[in] 整数，参见Syn_ResetSAM。
返回值：
0 读IIN,SN和DN成功
其他 读IIN,SN和DN失败（具体含义参见返回码表）
Syn_ReadBaseMsgToFile 与Syn_ ReadBaseMsg函数类似，读取ID卡内基本信息区域信息，并将读到的基本信息写进输入参数所指定的文件中。
int Syn_ ReadBaseMsgToFile (
int iPortID,
char * pcCHMsgFileName,
unsigned int * puiCHMsgFileLen,
char * pcPHMsgFileName,
unsigned int * puiPHMsgFileLen,
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。参见Syn_ResetSAM。
pcCHMsgFileName
[in] 读取到的ID卡内文字信息,需要写入文件，此为由用户指定的文件名。
puiCHMsgFileLen
[out] 存储文字信息的文件的长度。
pcCHMsgFileName
[in] 读取到的ID卡内照片信息,需要写入文件，此为由用户指定的文件名。
puiCHMsgFileLen
[out] 存储照片信息的文件的长度。
iIfOpen
[in] 整数，参见Syn_ResetSAM。
返回值：
0 读基本信息成功
其他 读基本信息失败（具体含义参见返回码表）
Syn_ReadIINSNDNToASCII 读取ID卡内IIN,SN和DN，并把16进制转化成ASCII形式。
int Syn_ReadIINSNDNToASCII (
int iPort，
unsigned char *pucIINSNDN,
int iIfOpen
);
参数说明：
iPort
[in] 整数，表示端口号。参见Syn_ResetSAM。
pucIINSNDN
[out] 无符号字符指针，指向读到的IIN,SN和DN,长度为固定56字节。
iIfOpen
[in] 整数，参见Syn_ResetSAM。
返回值：
0 读SN和DN成功
其他 读SN和DN失败（具体含义参见返回码表）
举例说明：
如读取到的IIN,SN和DN十六进制是{0x12, 0x9a…}，把每个字节拆分成两个ASCII形式的数，转化成后则为{0x31,0x32,0x39,0x61…}。
Syn_GetBmp本函数用于将wlt文件解码成bmp文件。
int Syn_GetBmp(
char * Wlt_File,
int intf
)；
参数说明：
Wlt_File
[in] 字符指针。wlt文件名
intf
[in] 阅读设备通讯接口类型（1—RS-232C，2—USB）
返回值：
值
意义
1
相片解码解码正确
0
调用sdtapi.dll错误
-1
相片解码错误
-2
wlt文件后缀错误
-3
wlt文件打开错误
-4
wlt文件格式错误
-5
软件未授权
-6
设备连接错误
（四）其他设置类API
Syn_SetPhotoPath 本函数用于设置照片文件存储的路径
int Syn_SetPhotoPath(
int iOption
char * cPhotopath
);
参数说明：
iOption
[in] 整形，0=C:根目录， 1=当前路径 ，2=指定路径
cPhotoPath
[in] 字符指针。路径名
返回值：
0 成功
-1 不成功
Syn_SetPhotoType 本函数用于设置照片文件存储的格式
int Syn_SetPhotoType(
int iType
);
参数说明：
iType
[in] 整形。1=bmp ， 2=jpeg ，3=base64
返回值：
0 成功
-1 不成功
Syn_SetPhotoName 本函数用于设置照片文件的文件名
int Syn_SetPhotoName(
int iType
);
参数说明：
iType
[in] 整形。0=tmp ， 1=姓名 ，2=身份证号 ，3=姓名_身份证号
返回值：
0 成功
-1 不成功
Syn_SetSexType 本函数用于设置返回性别的格式
int Syn_SetSexType(
int iType
);
参数说明：
iType
[in] 整形。0=卡内存储的数据， 1=解释之后的数据
返回值：
0 成功
-1 不成功
Syn_SetNationType 本函数用于设置返回民族的格式
int Syn_SetNationType(
int iType
);
参数说明：
iType
[in] 整形。0=卡内存储的数据 ， 1=解释之后的数据 ，2=解释之后+“族”
返回值：
0 成功
-1 不成功
Syn_SetBornType 本函数用于设置返回出生日期的格式
int Syn_SetBornType(
int iType
);
参数说明：
iType
[in] 整形。 0=YYYYMMDD,1=YYYY年MM月DD日,2=YYYY.MM.DD,
3=YYYY-MM-DD,4=YYYY/MM/DD
返回值：
0 成功
-1 不成功
Syn_SetUserLifeBType 本函数用于设置返回有效期开始日期的格式
int Syn_SetUserLifeBType(
int iType
);
参数说明：
iType
[in] 整形。 0=YYYYMMDD,1=YYYY年MM月DD日,2=YYYY.MM.DD,
3=YYYY-MM-DD,4=YYYY/MM/DD
返回值：
0 成功
-1 不成功
Syn_SetUserLifeEType 本函数用于设置返回有效期结束日期的格式
int Syn_SetUserLifeEType(
int iType；int iOption
);
参数说明：
iType
[in] 整形。 0=YYYYMMDD,1=YYYY年MM月DD日,2=YYYY.MM.DD,
3=YYYY-MM-DD,4=YYYY/MM/DD
iOption
[in] 整形。 0=长期不转换 1=长期转换为 有效期开始加50年
返回值：
0 成功
-1 不成功
三、OCX接口说明
属性
NameA 该属性返回读取信息的姓名，返回数据类型为BSTR
Sex 该属性返回读取信息的性别，返回数据类型为BSTR
Nation 该属性返回读取信息的民族，返回数据类型为BSTR
Born 该属性返回读取信息的出生日期，返回数据类型为BSTR
Address 该属性返回读取信息的地址，返回数据类型为BSTR
CardNo 该属性返回读取信息的身份证号，返回数据类型为BSTR
Police 该属性返回读取信息的发证机关，返回数据类型为BSTR
UserLifeB 该属性返回读取信息的有效期开始，返回数据类型为BSTR
UserLifeE 该属性返回读取信息的有效期结束，返回数据类型为BSTR
PhotoName; 该属性返回读取信息的照片文件名，返回数据类型为BSTR
Base64Photo 该属性返回读取信息的Base64照片编码，仅在用SetPhotoType方法设置存储文件为Base64格式之后有效返回数据类型为BSTR
方法
SetPhotoPath 本方法用于设置存储照片的路径,参见Syn_SetPhotoPath。
参数说明：
[in] iType 整形
cPath 字符串,BSTR
SetPhotoType 本方法用于设置存储照片的格式，参见Syn_SetPhotoType
SetPhotoName 本方法用于设置存储照片的文件名，参见Syn_SetPhotoName
SetSexType 本方法用于设置返回性别的格式，参见Syn_SetSexType
SetNationType 本方法用于设置返回民族的格式，参见Syn_SetNationType
SetBornType 本方法用于设置返回出生日期的格式，参见Syn_SetBornType
SetUserLifeBType 本方法用于设置返回有效期开始的格式，参见Syn_SetUserLifeBType
SetUserLifeEType 本方法用于设置返回有效期结束的格式，参见Syn_SetUserLifeEType
FindReader 本方法可以自动寻找计算机连接的读卡器，参见Syn_FindReader
GetSAMID 本方法返回读卡器的ID号，返回类型为BSTR，仅在FinderReader返回值大于0才有效
SetReadType 设置读卡的方式，0为手动 1为自动
ReadCardMsg 手动读卡函数，返回0为成功，成功后通过属性得到信息
SetLoopTime 自动读卡方式下循环读卡间隔，至少要大于1000毫秒
参数说明：
[in] iLoopTime 整形
事件
CardIn 该事件在自动读卡方式下读卡成功时出发，State=1有效
参数说明：
[in] State 整形
控件的使用方法：
1) 设置参数的方法可以随时调用，调用一次即有效。
2) 首先要调用FindReader方法，返回值大于0才能进行GetSAMID、SetReadType、ReadCardMsg、SetLoopTime的操作
四、返回值列表
类 别
返回值
(16进制)
意 义
成功信息
90
操作成功
91
没有该项内容
9F
返回找卡成功信息
SAM通信
01
端口打开失败/端口尚未打开/端口号不合法
02
PC接收超时，在规定的时间内未接收到规定长度的数据。
03
PC判断校验和错
04
USB设备未配置
05
该SAM串口不可用，只在Syn_GetCOMBaud时才有可能返回
06
USB设备被禁用
10
SAM判断校验和错
11
SAM接收超时，在规定的时间内未接收到规定长度的数据。
SAM命令错
21
接收业务终端的命令错误，包括命令中的各种数值或逻辑搭配错误
23
越权的操作申请
与ID卡相关
80
找卡不成功
81
选卡不成功
31
卡认证机具失败
32
机具认证卡失败
33
信息验证错误
34
尚未找卡，不能进行对卡的操作
40
无法识别的卡类型
41
读卡操作失败
50
写卡操作失败
61
用户登录失败
SAM状态
60
自检失败，不能接收命令
66
KDC没有下载正式密钥
2010-2-22增补两个函数
Syn_PhotoToStrBase64 照片装换成字符串。
int Syn_PhotoToStrBase64 (
char * cBase64,
int * iLen
);
参数说明：
cBase64
[out] 字符串，返回照片转化为base64格式的字符串
iLen
[out] 整形，返回字符串的长度
返回值：
0 成功
其他 失败
Syn_ StrBase64ToPhoto字符串转化为照片（仅jpeg格式）。
int Syn_ StrBase64ToPhoto (
char * cBase64,
int * iLen
char *cPhotoName
);
参数说明：
cBase64
[in] 字符串，要进行转化的Base64字符串，长度不能超过4096
iLen
[in] 整形，字符串的长度
cPhotoName
[out] 字符串，转换之后照片的文件名
返回值：
0 成功
其他 失败 | 
