新中新二代证SDK开发包开发说明.docx
《新中新二代证SDK开发包开发说明.docx》由会员分享，可在线阅读，更多相关《新中新二代证SDK开发包开发说明.docx（20页珍藏版）》请在冰点文库上搜索。
新中新二代证SDK开发包开发说明
（新中新）二代证SDK开发包开发说明
一、系统的基本要求
a）Windows98，Windows2000Pro,Windows2000Server,WinXP，WindowsVista，Windows7
b）至少32兆内存（32MRAMorLarger）
c）至少10兆空闲硬盘空间（10MFreeHardDiskSpaceorLarger）
d）至少一个空闲普通串口或USB口（视用户需求而定）。
二、SDK函数说明
（一）端口类API：
Syn_SetMaxRFByte设置射频适配器最大通信字节数
intSyn_SetMaxRFByte（
intiPort,
unsignedcharucByte,
intbIfOpen
）;
参数说明：
iPort
[in]整数，表示端口号。
串口0001至0016，USB1001至1016
ucByte
[in]无符号字符，24-255，表示射频适配器最大通信字节数。
iIfOpen
[in]整数，非0表示在API函数内部包含了打开端口和关闭端口函数，0表示在API函数内部不包含了打开端口和关闭端口函数
返回值：
0成功
其他失败（具体含义参见返回码表）
Syn_GetCOMBaud查看串口当前波特率（该函数只用于SAM采用RS232串口的情形，如果采用USB接口则不支持该API）。
intSyn_GetCOMBaud（
intiPort,
unsignedint*puiBaudRate
）;
参数说明：
iPort
[in]整数，表示端口号。
此处端口号必须为1-16，表示串口
puiBaudRate
[out]无符号整数指针，指向普通串口当前波特率,默认情况下为115200。
返回值：
0成功
0X01端口打开失败/端口号不合法
0X05无法获得该SAM的波特率，该SAM串口不可用。
Syn_GetCOMBaudEx查看串口当前波特率（该函数只用于SAM采用RS232串口的情形，如果采用USB接口则不支持该API）。
intSyn_GetCOMBaudEx（
intiPort,
）;
参数说明：
iPort
[in]整数，表示端口号。
此处端口号必须为1-16，表示串口
返回值：
0失败其他为读卡器当前波特率
Syn_SetCOMBaud设置SAM的串口的波特率（该函数只用于SAM采用RS232串口的情形，如果采用USB接口则不支持该API），设置成功后，在该SAM和主机注册表中都记录设置后的波特率，保证在SAM重新启动和该套API被重新调用时采用设置后的波特率。
该函数调用成功后，需要延时5毫秒，然后才能继续与SAM通信。
intSyn_SetCOMBaud（
intiPort,
unsignedintuiCurrBaud,
unsignedintuiSetBaud
）;
参数说明：
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超时，设置不成功。
0X21uiCurrBaud、uiSetBaud输入参数数值错误。
Syn_OpenPort打开端口
intSyn_OpenPort（
intiPort
）;
参数说明：
iPort
[in]整数，表示端口号。
1-16（十进制）为串口，1001-1016（十进制）为USB口，USB的端口设置参看“USB设备配置使用手册”。
返回值：
0打开端口成功
0X01打开端口失败/端口号不合法
Syn_ClosePort关闭端口
intSyn_ClosePort（
intiPort
）;
参数说明：
iPort
[in]整数，表示端口号。
返回值：
0关闭端口成功。
0x01端口号不合法
（二）SAM类API：
Syn_ResetSAM对SAM复位
intSyn_ResetSAM（
intiPort,
intiIfOpen
）;
参数说明：
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进行状态检测。
intSyn_GetSAMStatus（
intiPort,
intiIfOpen
）;
参数说明：
iPort
[in]整数，表示端口号。
参见Syn_ResetSAM。
iIfOpen
[in]整数，参见Syn_ResetSAM。
返回值：
0SAM正常
0x60自检失败，不能接收命令
其他命令失败（具体含义参见返回码表）
Syn_GetSAMID读取SAM的编号。
intSyn_GetSAMID（
intiPort,
unsignedchar*pucSAMID,
intiIfOpen
）;
参数说明：
iPort
[in]整数，表示端口号。
参见Syn_ResetSAM。
pucSAMID
[out]无符号字符串指针，指向读到的SAM编号，16字节。
返回值：
0成功
其他失败（具体含义参见返回码表）
Syn_GetSAMIDToStr读取SAM的编号。
intSyn_GetSAMIDToStr（
intiPort,
char*pcSAMID，
intiIfOpen
）;
参数说明：
iPort
[in]整数，表示端口号。
参见Syn_ResetSAM。
pcSAMID
[out]字符串指针，指向读到的SAM编号。
iIfOpen
[in]整数，参见Syn_ResetSAM。
返回值：
0成功
其他失败（具体含义参见返回码表）
Syn_FindReader自动寻找读卡器。
intSyn_FindReader（）;
返回值：
0未找到
其他1～16串口1001～1016USB
（三）身份证卡类API：
Syn_StartFindIDCard开始找卡。
intSyn_StartFindIDCard（
intiPort,
unsignedchar*pucIIN,
intiIfOpen
）;
参数说明：
iPort
[in]整数，表示端口号。
参见Syn_ResetSAM。
pucIIN
[out]无符号字符指针，指向读到的IIN。
iIfOpen
[in]整数，参见Syn_ResetSAM。
返回值：
0找卡成功
0x80找卡失败
Syn_SelectIDCard选卡。
intSyn_SelectIDCard（
intiPort,
unsignedchar*pucSN,
intiIfOpen
）;
参数说明：
iPort
[in]整数，表示端口号。
参见Syn_ResetSAM。
pucSN
[out]无符号字符指针，指向读到的SN。
iIfOpen
[in]整数，参见Syn_ResetSAM。
返回值：
0选卡成功
0x81选卡失败
Syn_ReadBaseMsg读取ID卡内基本信息区域信息。
intSyn_ReadBaseMsg（
intiPort，
unsignedchar*pucCHMsg，
unsignedint*puiCHMsgLen，
unsignedchar*pucPHMsg，
unsignedint*puiPHMsgLen,
intiIfOpen
）;
参数说明：
iPort
[in]整数，表示端口号。
参见Syn_ResetSAM。
pucCHMsg
[out]无符号字符指针，指向读到的文字信息。
puiCHMsgLen
[out]无符号整型数指针，指向读到的文字信息长度。
pucPHMsg
[out]无符号字符指针，指向读到的照片信息。
puiPHMsgLen
[out]无符号整型数指针，指向读到的照片信息长度。
iIfOpen
[in]整数，参见Syn_ResetSAM。
返回值：
0读基本信息成功
其他读基本信息失败（具体含义参见返回码表）
Syn_ReadIINSNDN读取ID卡内IIN,SN和DN。
intSyn_ReadIINSNDN（
intiPort，
unsignedchar*pucIINSNDN,
intiIfOpen
）;
参数说明：
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卡内基本信息区域信息，并将读到的基本信息写进输入参数所指定的文件中。
intSyn_ReadBaseMsgToFile（
intiPortID,
char*pcCHMsgFileName,
unsignedint*puiCHMsgFileLen,
char*pcPHMsgFileName,
unsignedint*puiPHMsgFileLen,
intiIfOpen
）;
参数说明：
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形式。
intSyn_ReadIINSNDNToASCII（
intiPort，
unsignedchar*pucIINSNDN,
intiIfOpen
）;
参数说明：
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文件。
intSyn_GetBmp（
char*Wlt_File,
intintf
）；
参数说明：
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本函数用于设置照片文件存储的路径
intSyn_SetPhotoPath（
intiOption
char*cPhotopath
）;
参数说明：
iOption
[in]整形，0=C:
根目录，1=当前路径，2=指定路径
cPhotoPath
[in]字符指针。
路径名
返回值：
0成功
-1不成功
Syn_SetPhotoType本函数用于设置照片文件存储的格式
intSyn_SetPhotoType（
intiType
）;
参数说明：
iType
[in]整形。
1=bmp，2=jpeg，3=base64
返回值：
0成功
-1不成功
Syn_SetPhotoName本函数用于设置照片文件的文件名
intSyn_SetPhotoName（
intiType
）;
参数说明：
iType
[in]整形。
0=tmp，1=姓名，2=身份证号，3=姓名_身份证号
返回值：
0成功
-1不成功
Syn_SetSexType本函数用于设置返回性别的格式
intSyn_SetSexType（
intiType
）;
参数说明：
iType
[in]整形。
0=卡内存储的数据，1=解释之后的数据
返回值：
0成功
-1不成功
Syn_SetNationType本函数用于设置返回民族的格式
intSyn_SetNationType（
intiType
）;
参数说明：
iType
[in]整形。
0=卡内存储的数据，1=解释之后的数据，2=解释之后+“族”
返回值：
0成功
-1不成功
Syn_SetBornType本函数用于设置返回出生日期的格式
intSyn_SetBornType（
intiType
）;
参数说明：
iType
[in]整形。
0=YYYYMMDD,1=YYYY年MM月DD日,2=YYYY.MM.DD,
3=YYYY-MM-DD,4=YYYY/MM/DD
返回值：
0成功
-1不成功
Syn_SetUserLifeBType本函数用于设置返回有效期开始日期的格式
intSyn_SetUserLifeBType（
intiType
）;
参数说明：
iType
[in]整形。
0=YYYYMMDD,1=YYYY年MM月DD日,2=YYYY.MM.DD,
3=YYYY-MM-DD,4=YYYY/MM/DD
返回值：
0成功
-1不成功
Syn_SetUserLifeEType本函数用于设置返回有效期结束日期的格式
intSyn_SetUserLifeEType（
intiType；intiOption
）;
参数说明：
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没有下载正式密钥
升级会员 