DONSEE东信智能 - 身份证社保卡读卡智能终端应用服务商

通用序列身份证阅读器SDK二次开发包免费下载

提供第二三代居民身份证阅读器CS客户端二次开发和BS浏览器端二次开发，相关技术支持免费提供。

二代证SDK开发包开发说明，包括C/S端开发和B/S端开发：

居民身份证验证安全控制模块接口

API 使用手册

目录

1.前言1

2.系统要求1

3.API 列表1

4.API 详细说明2

4.1端口类 API2

4.1.1SDT_GetCOMBaud2

4.1.2SDT_SetCOMBaud2

4.1.3SDT_OpenPort3

4.1.4SDT_ClosePort3

4.2SAM 类 API4

4.2.1SDT_ResetSAM4

4.2.2SDT_SetMaxRFByte4

4.2.3SDT_GetSAMStatus5

4.2.4SDT_GetSAMID5

4.2.5SDT_GetSAMIDToStr6

4.3身份证卡类 API6

4.3.1SDT_StartFindIDCard6

4.3.2SDT_SelectIDCard7

4.3.3SDT_ReadBaseMsg7

4.3.4SDT_ReadBaseMsgToFile8

4.3.5SDT_ReadBaseFPMsg9

4.3.6SDT_ReadBaseFPMsgToFile10

4.3.7SDT_ReadNewAppMsg11

5.API 调用说明12

5.1调用顺序12

5.2C 语言示例程序12

6.函数返回码表15

1.前言

本手册是居民身份证验证安全控制模块（以下有时以 SAM_A 指代）接口 API 的使用说明，适用于版本号为 2.0.2.0 的 API 动态库（sdtapi.dll）。

2.系统要求

使用本动态库的 PC 机，必须满足下列条件：

Windows 98，Windows 2000 Pro,Windows 2000 Server,WindowsXP；

至少一个空闲普通串口或 USB 口。

3.API 列表

API 分为三类，在下表中列出。

序号函数名功能描述调用层

级号

端口类API

1.SDT_GetCOMBaud查看 SAM_A 串口当前波特率1

2.SDT_SetCOMBaud设置业务终端与 SAM_A 串口的波特率1

3.SDT_OpenPort打开串口/USB 口1

4.SDT_ClosePort关闭串口/USB 口2

SAM类API

5.SDT_ResetSAM对 SAM_A 复位1

6.SDT_SetMaxRFByte设置射频适配器一帧通信数据的最大字

节数1

7.SDT_GetSAMStatus对 SAM_A 进行状态检测1

8.SDT_GetSAMID读取 SAM_A 的编号，输出为十六进制数

值1

9.SDT_GetSAMIDToStr读取 SAM_A 的编号，输出为字符串1

身份证卡类API

10.SDT_StartFindIDCard寻找居民身份证1

11.SDT_SelectIDCard选取居民身份证2

12.SDT_ReadBaseMsg读取居民身份证机读文字信息和相片信

息相片3

13.SDT_ReadBaseMsgToFile读取居民身份证机读文字信息和相片信

息，并将其存入用户指定文件3

14.SDT_ReadBaseFPMsg读取居民身份证机读文字信息、相片信

息和指纹信息3

15.SDT_ReadBaseFPMsgToFile读取居民身份证机读文字信息、相片信

息和指纹信息，并将其存入用户指定文件3

16.SDT_ReadNewAppMsg读取追加地址信息3

4.API 详细说明

4.1端口类 API

4.1.1SDT_GetCOMBaud

查看 SAM_A 串口当前波特率(该函数只用于 SAM_A 采用串口的情形，如果采用 USB 接口则不支持该 API)。

intSDT_GetCOMBaud (

intiPort,

unsigned int *puiBaudRate

);

参数说明：

iPort

[in] 整数，表示端口号。此处端口号必须为 1～16，表示串口。

puiBaudRate

[out] 无符号整数指针，指向普通串口当前波特率, 默认情况下为 115200bps。

返回值：

0x90成功。

0x01端口打开失败/端口号不合法。

0x05无法获得该 SAM_A 的波特率，该 SAM_A 串口不可用。

注：[in]表示该参数为输入参数，[out]表示该参数为输出参数，下同。

4.1.2SDT_SetCOMBaud

设置业务终端及 SAM_A 的串口的波特率(该函数只用于 SAM_A 采用串口的情形，如果采用 USB 接口则不支持本函数)。

intSDT_SetCOMBaud (

intiPort,

unsigned intuiCurrBaud,

unsigned intuiSetBaud

);

参数说明：

iPort

[in] 整数，表示端口号。此处端口号必须为 1～16，表示串口。

uiCurrBaud

[in] 无符号整数，调用该 API 前已设置的业务终端与 SAM_A 通信的波特率

(SAM_A 出厂时默认值为 115200bps)。业务终端以当前使用的波特率与 SAM_A

C/S客户端开发：

1. DLL文件夹为编译之后的SDK开发包、所有的支持库、说明文档、Lib文件和.H头文件

测试程序文件夹下为

2. BCB6文件夹内为C++Builder6的测试源程序

3. C#文件夹内为VS2008-C#的测试源程序

4. Delphi7文件夹为DelPhi7的测试源程序

5. Java测试源程序,JDK1.6,MyEclipse7.0下调试通过(开发者:刘翀)

6. PB9测试源程序

7. VB6文件夹为VB6的测试源程序

8. VC6文件夹为VC++6的测试源程序

以上测试程序开发环境为：

操作系统 Win2003SP2

软件编译环境Borland C++Builder6

VS2008

Borland Delphi7

JDK1.6,MyEclipse7.0

PowerBuilder9

VB6

VC++6

B/S浏览器端开发：

1.CAB文件夹下为OCX控件cab包，可用于二次开发或发行

2.测试程序文件夹为测试OCX控件的源程序，分别提供BCB6、C#

  DelPhi7、Javascript、VB6和VBScricp的测试程序

3.手工安装OCX的方法，把CAB文件夹中的SynCardOCXCAB解压到

  任意文件夹，比方为C:\CAB，点 【开始】-【运行】，输入

  下列命令运行

regsvr32 C:\Cab\SynCardOcx.ocx 

  要卸载输入下列命令运行

regsvr32 -u C:\Cab\SynCardOcx.ocx 

一、系统的基本要求

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 charucByte,

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 intuiCurrBaud,

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超时，设置不成功。

0X21uiCurrBaud 、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,

intiIfOpen

);

参数说明：

iPort

[in] 整数，表示端口号。根据SAM使用的接口不同(分为普通串口SAM和USB口SAM)，分别使用不同的端口号（目前串口和USB都只支持16个，即串口0001-0016和USB1001-1016）：

普通串口SAM0001 – 0016(十进制)例如：

0001：串口1(COM1)

0002：串口2(COM2)

USB口SAM1001 – 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,

intiIfOpen

);

参数说明：

iPort

[in] 整数，表示端口号。参见Syn_ResetSAM。

iIfOpen

[in] 整数，参见Syn_ResetSAM。

返回值：

0SAM正常

0x60自检失败，不能接收命令

其他命令失败（具体含义参见返回码表）

Syn_GetSAMID 读取SAM的编号。

int  Syn_GetSAMID (

int  iPort,

unsigned char *pucSAMID,

intiIfOpen

);

参数说明：

iPort

[in] 整数，表示端口号。参见Syn_ResetSAM。

pucSAMID

[out] 无符号字符串指针，指向读到的SAM编号， 16字节。

返回值：

0成功

其他失败（具体含义参见返回码表）

Syn_GetSAMIDToStr 读取SAM的编号。

int  Syn_GetSAMIDToStr (

int  iPort,

char *pcSAMID，

intiIfOpen

);

参数说明：

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,

intiIfOpen

);

参数说明：

iPort

[in] 整数，表示端口号。参见Syn_ResetSAM。

pucIIN

[out] 无符号字符指针，指向读到的IIN。

iIfOpen

[in] 整数，参见Syn_ResetSAM。

返回值：

0找卡成功

0x80找卡失败

Syn_SelectIDCard 选卡。

int  Syn_ SelectIDCard (

int  iPort ,

unsigned char *pucSN,

intiIfOpen

);

参数说明：

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,

intiIfOpen

);

参数说明：

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,

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卡内基本信息区域信息，并将读到的基本信息写进输入参数所指定的文件中。

int  Syn_ ReadBaseMsgToFile (

int iPortID,

char * pcCHMsgFileName,

unsigned int *puiCHMsgFileLen,

char * pcPHMsgFileName,

unsigned int  *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形式。

int  Syn_ReadIINSNDNToASCII (

int  iPort，

unsigned char * 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文件。

int Syn_GetBmp(

char * Wlt_File,

int intf

)；

参数说明：

Wlt_File  

[in] 字符指针。wlt文件名

intf      

[in]阅读设备通讯接口类型（1—RS-232C，2—USB）

返回值：

值意义

1相片解码解码正确

0调用sdtapi.dll错误

-1相片解码错误

-2wlt文件后缀错误

-3wlt文件打开错误

-4wlt文件格式错误

-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端口打开失败/端口尚未打开/端口号不合法

02PC接收超时，在规定的时间内未接收到规定长度的数据。

03PC判断校验和错

04USB设备未配置

05该SAM串口不可用，只在Syn_GetCOMBaud时才有可能返回

06USB设备被禁用

10SAM判断校验和错

11SAM接收超时，在规定的时间内未接收到规定长度的数据。

SAM命令错 21接收业务终端的命令错误，包括命令中的各种数值或逻辑搭配错误

23越权的操作申请

与ID卡相关 80找卡不成功

81选卡不成功

31卡认证机具失败

32机具认证卡失败

33信息验证错误

34尚未找卡，不能进行对卡的操作

40无法识别的卡类型

41读卡操作失败

50写卡操作失败

61用户登录失败

SAM状态 60自检失败，不能接收命令

66KDC没有下载正式密钥