2.3.1 基本接口
2.3.1.1 打开设备 
函数名称	打开设备
函数声明	long OpenDevice(char *PortType, char *PortPara, char *ExtendPara);
功能描述	与设备建立通讯连接，返回设备句柄。
参数说明	序号	参数	输入/输出	类型	含义
	1	PortType	IN	字符串	端口类型（详见参数补充说明）
	2	PortPara	IN	字符串	端口参数（详见参数补充说明）
	3	ExtendPara	IN	字符串	扩展参数（详见参数补充说明）
返回值	大于0表示成功，数值为设备句柄；其他为失败。

参数补充说明：
	PortType	PortPara	ExtendPara
串口	COMn 或 1~1000	波特率（9600、115200）	串口扩展盒参数（1B2541）
USB	USBn 或 1001~2000	VID_PID（261A0011、261A0012）	中断传输为：MI   控制传输为：MC
网口	SKT	IP:端口（192.168.0.1:8080）	
蓝牙	BTH	蓝牙名称（SS728M801）	
自动	AUTO		
注意事项：
1、COMn和USBn中n∈1~1000，即COM1~COM1000(1~1000)和USB1~USB1000(1001~2000)
2、Linux/Android下串口传参为：COM+串口文件路径，例如：COM/dev/ttyS4
3、端口类型为AUTO时，是指各参数通过CommonInterface.ini配置文件获取，用法详见附录C方案二。
神思USB读卡器的VID_PID对照表请参见附录B
2.3.1.2 关闭设备
函数名称	关闭设备
函数声明	long CloseDevice();
功能描述	断开与设备的通讯连接。
参数说明	序号	参数	输入/输出	类型	含义
					
返回值	0表示成功；非0表示失败。
2.3.1.3 设置当前设备（多设备操作）
函数名称	设置当前设备
函数声明	long SetCurrentDevice(long DevHandle);
功能描述	一台PC连接多台读卡器时，通过设备句柄设置接下来要操作的设备。
参数说明	序号	参数	输入/输出	类型	含义
	1	PortHandle	IN	长整型	设备句柄
返回值	0表示成功；非0表示失败。
2.3.1.4 获取当前设备（多设备操作）
函数名称	获取当前设备
函数声明	long GetCurrentDevice();
功能描述	一台PC连接多台读卡器时，获取当前操作的设备句柄。
参数说明	序号	参数	输入/输出	类型	含义
					
返回值	返回当前设备的句柄。
2.3.1.5 获取接口库信息
函数名称	获取接口库信息
函数声明	long GetLibraryInfo(char *Version, char * Description);
功能描述	获取当前已加载的接口库详细信息。
参数说明	序号	参数	输入/输出	类型	含义
	1	Version	OUT	字符串	接口库版本
	2	Description	OUT	字符串	接口库描述
返回值	0表示成功；非0表示失败。
2.3.1.6 获取设备型号
函数名称	获取设备型号
函数声明	long TerminalGetModel(char *TerminalModel);
功能描述	获取读卡器的型号。
参数说明	序号	参数	输入/输出	类型	含义
	1	TerminalModel	OUT	字符串	设备型号
返回值	0表示成功；非0表示失败。
2.3.1.7 设备轮询心跳
函数名称	设备轮询心跳
函数声明	long TerminalHeartBeat();
功能描述	与设备进行握手通讯，用于检测与读卡器是否已建立连接并且通讯正常。
参数说明	序号	参数	输入/输出	类型	含义
					
返回值	0表示成功；非0表示失败。

2.3.1.8 获取接收数据
函数名称	获取接收数据
函数声明	long GetLastRecvData(unsigned char *LastRecvData);
功能描述	获取最后一次通讯收到的数据，一般用于获取读卡器协议层错误信息。
参数说明	序号	参数	输入/输出	类型	含义
	1	LastRecvData	OUT	字节数组	返回最后一次通讯收到的数据
返回值	返回收到的数据长度。

2.3.1.9 获取固件版本
函数名称	获取设备固件版本
函数声明	long TerminalGetFirmVersion(char *FirmVersion, char *HardwareVersion);
功能描述	获取读卡器的固件版本号。
参数说明	序号	参数	输入/输出	类型	含义
	1	FirmVersion	OUT	字符串	设备固件版本号
	2	HardwareVersion	OUT	字符串	设备硬件版本号
返回值	0表示成功；非0表示失败。
2.3.1.10 获取设备序列号
函数名称	获取设备序列号
函数声明	long TerminalGetSn(char *TerminalSn);
功能描述	获取读卡器的固件版本号。
参数说明	序号	参数	输入/输出	类型	含义
	1	TerminalSn	OUT	字符串	设备序列号
返回值	0表示成功；非0表示失败。



2.3.2 二代证接口（二代证/外国人/港澳台）
2.3.2.1 读取二代证
函数名称	读取二代证
函数声明	long IdReadCard(unsigned char CardType, unsigned char InfoEncoding, char *IdCardInfo, 
			long TimeOutMs);
long SdtReadCard(unsigned char CardType, unsigned char InfoEncoding, char *IdCardInfo, 
			long TimeOutMs);（GA467协议）
功能描述	读取第二代居民身份证或外国人永久居留证或港澳台居民居住证
参数说明	序号	参数	输入/输出	类型	含义
	1	CardType	IN	字节	读取卡类型
0x00 ：读取二代证或外国人或港澳台
0x01 ：只读二代证
0x02 ：只读外国人
0x03 ：只读港澳台

以上参数不含指纹信息
以下参数包含指纹信息

0x10 ：读取二代证或外国人或港澳台	  （含指纹）
0x11 ：只读二代证（含指纹）
0x12 ：只读外国人（含指纹）
0x13 ：只读港澳台（含指纹）
	2	InfoEncoding	IN	字节	返回信息的编码方式
0x01 ：GB18030编码（GBK）
0x02 ：UTF16-LE编码
0x03 ：UTF-8编码
	3	IdCardInfo	OUT	字符串	读取到的二代证/外国人/港澳台信息
（至少分配10240字节的内存）
	4	TimeOutMs	IN	长整型	读卡超时时间，单位为毫秒
= 0 ：不等待，无卡立即返回
> 0 ：等待放卡，指定时间内等待放卡
返回值	0表示成功；非0表示失败。

读卡返回信息IdCardInfo格式为以英文冒号分割的信息项，具体如下：
证件类型:中文姓名:英文姓名:性别:性别代码:民族:民族代码:出生日期:住址:身份证号码:签发机关:发卡日期:卡有效期:证件版本号:头像JPG照片base64编码:指纹特征值base64编码
以上信息为二代证、外国人、港澳台信息项的并集，如果当前类型的证件中不存在该项信息，则该项为空，具体证件中包含的信息项如下：
序号	信息项	二代证	外国人	港澳台	自动解析函数
0	证件类型	A	I或Y	J	IdCardGetTypeFlag
1	中文姓名	姓名	中文姓名	姓名	IdCardGetName
2	英文姓名		英文姓名		IdCardGetNameEn
3	性别	性别	性别	性别	IdCardGetGender
4	性别代码	性别代码	性别代码	性别代码	IdCardGetGenderId
5	民族	民族	国籍或所在地区		IdCardGetNation
6	民族代码	民族代码	国籍或所在地区代码	通行证号码	IdCardGetNationId
7	出生日期	出生日期	出生日期	出生日期	IdCardGetBirthDate
8	住址	住址	/永久居留证号码关联项	住址	IdCardGetAddress
9	身份证号码	公民身份号码	永久居留证号码/证件号码	公民身份号码	IdCardGetIdNumber
10	签发机关	签发机关	当次申请受理机关代码	签发机关	IdCardGetSignOrgan
11	发卡日期	有效期
起始日期	证件签发日期	有效期
起始日期	IdCardGetBeginTerm
12	卡有效期	有效期
截止日期	证件终止日期	有效期
截止日期	IdCardGetValidTerm
13	证件版本号		证件版本号/换证次数	签发次数	IdCardGetVersion
14	头像JPG照片base64编码	头像照片base64编码	头像照片base64编码	头像照片base64编码	
15	指纹特征值base64编码	指纹特征值base64编码		指纹特征值base64编码	

各信息项建议通过拆分IdCardInfo字符串得到，不建议使用以下函数获取：
long IdCardGetName(char *Name);
long IdCardGetNameEn(char *NameEn);
long IdCardGetGender(char *Gender);
long IdCardGetGenderId(char *GenderId);
long IdCardGetNation(char *Nation);
long IdCardGetNationId(char *NationId);
long IdCardGetBirthDate(char *BirthDate);
long IdCardGetAddress(char *Address);
long IdCardGetIdNumber(char *IdNumber);
long IdCardGetSignOrgan(char *SignOrgan);
long IdCardGetBeginTerm(char *BeginTerm);
long IdCardGetValidTerm(char *ValidTerm);
long IdCardGetTypeFlag(char *TypeFlag);
long IdCardGetVersion(char *Version);
long IdCardGetFPBuffer(unsigned char *FPBuffer, long *FPBufferLen);//返回1024字节指纹信息（两个手指）
long IdCardGetPhotoFile(char *PhotoFile);//入参PhotoFile为生成头像文件的全路径，支持扩展名wlt/bmp/jpg
long IdCardGetPhotoBuffer(unsigned char WltBmpJpg, unsigned char *PhotoBuffer, long *PhotoBufferLen);
WltBmpJpg入参：0x01 ：wlt格式     0x02 ：bmp格式     0x03 ：jpg格式

//获取二代证原始信息
long IdCardGetRawInfo(unsigned char *CHMsg, long *CHMsgLen, 	//文字信息
unsigned char *PHMsg, long *PHMsgLen, 	//照片信息
unsigned char *FPMsg, long *FPMsgLen); 	//指纹信息

2.3.2.2 读取追加住址
函数名称	读取追加住址
函数声明	long IdReadNewAddress(char *NewAddress);
long SdtReadNewAddress(char *NewAddress); （GA467协议）
功能描述	读取二代证的追加住址信息
参数说明	序号	参数	输入/输出	类型	含义
	1	NewAddress	OUT	字符串	返回读取到的追加住址信息
返回值	0表示成功；非0表示失败。
2.3.2.3 获取SAM模块状态
函数名称	获取SAM模块状态
函数声明	long SamGetStatus();
long SdtSamGetStatus();（GA467协议）
功能描述	获取公安部SAM安全模块状态。
参数说明	序号	参数	输入/输出	类型	含义
					
返回值	0表示成功；非0表示失败。
2.3.2.4 获取SAM模块编号字符串
函数名称	获取SAM模块编号字符串
函数声明	long SamGetIdStr(char *SamIdStr);
long SdtSamGetIdStr(char *SamIdStr); （GA467协议）
功能描述	获取公安部SAM安全模块编号字符串。（内部将编号转换为字符串）
参数说明	序号	参数	输入/输出	类型	含义
	1	SamIdStr	OUT	字符串	SAM模块编号字符串
返回值	0表示成功；非0表示失败。

