2016年中国联通数字化营业厅一体化高拍仪接口规范

2016年中国联通总部数字化营业厅一体化高拍仪设备接口规范文件状态： 草稿 正式发布 正在修改当前版本：1.0作 者：狄秋燕，朱雯莉，胡迪，孟莉莉制作单位中国联通信息化部完成日期：2016-7-28审 核：目录一、更新历史3二、外设设备接口要求32.1.电子凭证采集功能模块接口要求32.1.1.功能说明42.1.2.动态链接库名称42.1.3.调用过程52.1.4.函数说明63.1.二代身份证阅读及读写卡功能模块网页OCX控件规范103.1.1.控件引入103.1.2.控件方法113.1.3.控件属性133.1.4.软件安装143.1.5.基准测试网页14一、更新历史2016.7.28 V1.0 初次编写二、外设设备接口要求. 电子凭证采集功能模块接口要求电子凭证采集功能模块，对接联通无纸化系统，外设接口类型为Windows DLL,接口调用方式采用stdcall标准调用，每个厂家的每类设备只能提供一个DLL文件。设备命名为设备类型.dll。驱动文件存放地址对于windows系统，为安装操作系统所在盘的WINDOWSsystem32目录下。在打开相关设备时，当输入参数端口号为-1时，驱动文件按照本地配置文件中设备对应的端口号调用相关设备，其它数值按照输入参数调用相应端口设备。各驱动的命名如下：驱动命名列表设备类型描述设备命名电子扫描设备Unicom_Cap.dll设备本地配置文件说明：本地配置文件用来配置驱动日志地址信息。配置信息的windows存放在地址C:DeviceDriverConf.ini中。1.驱动文件日志记录要求：WriteLog（WriteLog值为0：不记录日志；WriteLog值为1，不记录调用接口函数的参数；WriteLog值为2，记录调用接口函数的参数）2.配置文件格式为：Unicom_SignUserIdCardPort=6 （设备端口）WriteLog=1UserIdCardAddress=C: DeviceDriverLog signUnicom_CapUserIdCardPort=7 （设备端口）WriteLog=1MutiIdCardAddress=C: DeviceDriverLog cap3.状态码常量定义状态码（正常状态、运行状态、告警状态）建议用8位数字或字母表示。第1位表示状态类型，1：正常状态 2：运行信息 3：维护告警（级别：黄维护） 4：故障告警（红维修）。第2-6位表示设备类型码。第7-8位表示各部件的状态类型。2.1.1. 功能说明对此接口进行定义、作用、参数、描述等定义电子凭证采集设备相关的打开、关闭、采集（为保证图像质量可选预览模式）、连接状态查询、裁剪旋转等基本操作接口与操作流程与错误码等信息表示方式。2.1.2. 动态链接库名称设备厂家提供的主动态库名称为Unicom_Cap.dll，由设备厂商根据该DLL开发相应OCX插件。OCX插件与动态库之间的调用流程如图所示。设备厂商负责画面质量以及云终端兼容性。 图3-1 OCX插件与动态库之间的调用流程图2.1.3. 调用过程定义此接口所输出的参数、格式、大小等进行说明接口参数、函数格式等详见下一节。各操作过程解释如下：操作名功能定义备注打开设备通过上位机程序为设备分配必要的系统资源关闭设备释放设备所占用的系统资源获得设备信息返回设备PID、VID、唯一ID、厂商名称、设备型号、支持分辨率等信息获得设备状态调用设备自检程序，返回设备可用状态采集影像操作（主摄像头）采集资料影像图片，返回图片存储位置(支持自动裁剪与手动裁剪模式)采集影像操作（辅摄像头）采集客户影像图片，返回图片存储位置预览视频（主摄像头）在指定窗口上显示资料影像(支持自动和手动绘图)预览视频（辅摄像头）在指定窗口上显示客户影像照片旋转旋转照片类型码定义操作指令所返回的各种状态码定义2.1.4. 函数说明. 打开设备打开电子凭证采集设备识读函数函数描述打开设备函数名int_stdcall OpenDevice(int Port,char* retMsg)属性变量名称类型变量含义备 注入口参数Portint端口号USB端口从1000开始。USB1填1001，驱动自己处理Baud 波特率DataBits 数据位StopBits 停止位Parity 奇偶校验自行在驱动里处理出口参数retMsgchar *错误信息执行失败时返回的错误信息，最大60字节返回值int0Success；状态码 Fail附加说明. 关闭设备关闭电子凭证采集设备识读函数函数描述关闭设备函数名int_stdcall CloseDevice(char* retMsg)属性变量名称类型变量含义备 注出口参数retMsgchar *错误信息执行失败时返回的错误信息，最大60字节返回值int0Success；状态码 Fail附加说明. 获得设备信息获取电子凭证采集设备信息函数函数描述获得设备信息函数名typedef structchar pid60; /设备PIDchar uuid60; /唯一编号char vid60; /设备VIDchar56 VendorName厂家名称char32 ProductName设备型号char version60; /DLL版本号char res256; /支持分辨率字符串，如”1920X1080,1366X768,640X480”DeviceInfo;int _stdcall getDeviceInfo(DeviceInfo *info, char* retMsg);属性变量名称类型变量含义备 注入口参数infoDeviceInfo设备信息返回设备信息出口参数retMsgchar*执行结果中文解释最大长度：60返回值retCodeint执行结果状态码0 Success；非0retMsg解释. 获得设备状态获取电子凭证采集设备状态函数函数描述获得设备状态函数名int _stdcall getDeviceStatus(int* code ，char* retMsg);属性变量名称类型变量含义备 注返回值retCodeint执行结果状态码0 Success；非0函数执行失败出口参数codeint*状态code出口参数retMsgchar*执行结果中文解释最大长度：60附加说明主要查看设备是否连接，不处于正在被使用状态，并可正常调用读取函数。附加说明2出口参数对应设备状态：. 预览视频(主摄像头)预览视频（主摄像头）函数函数描述预览视频函数名int _stdcall previewDeviceA(void* displayHandle, int type,int Angle, char* Resolution, char * retMsg)属性变量名称类型变量含义备 注返回值retCodeint执行结果状态码0 Success；非0retMsg解释入口参数displayHandlevoid*视频显示控件句柄Windows控件句柄入口参数typeint证件类型见附件说明，主要用于根据类型提示裁剪区域入口参数Angleint旋转角度主要用于视频预览时旋转只能为0，90，180，270入口参数Resolutiounchar*分辨率主要用于视频预览时的分辨率，为空时自行定义出口参数retMsgchar*执行结果中文解释最大长度：60附加说明主要预览资料影像。附加说明2所有凭证类型代码遵循以下解释：0：未定义（手动裁切）1：二代身份证2: 临时身份证3：户口本4：中国护照5：国际护照6：军官证（士兵证）7：港澳通行证8：港澳居民往来内地通行证9：台湾居民来往大陆通行证10：二代证背面. 预览视频(辅摄像头)预览视频（辅摄像头）函数函数描述预览视频函数名int _stdcall previewDeviceB(void* displayHandle, char * retMsg)属性变量名称类型变量含义备 注返回值retCodeint执行结果状态码0 Success；非0retMsg解释入口参数displayHandlevoid*视频显示控件句柄Windows控件句柄出口参数retMsgchar*执行结果中文解释最大长度：60附加说明主要预览客户影像。附加说明2返回值对应设备状态. 采集影像操作（主摄像头）电子凭证采集设备采集函数函数描述采集影像操作函数名int _stdcall photographA(char* retFileName, char * retMsg)属性变量名称类型变量含义备 注入口参数retFileNamechar *图像保存文件名称（全路径的）最大长度：256出口参数retMsgchar*执行结果中文解释最大长度：60返回值retCodeint执行结果状态码0 Success；非0retMsg解释附加说明所有凭证类型代码遵循以下解释：0：未定义1：二代身份证2: 临时身份证3：户口本4：中国护照5：国际护照6：军官证（士兵证）7：港澳通行证8：港澳居民往来内地通行证9：台湾居民来往大陆通行证10：二代证背面. 采集影像操作（辅摄像头）电子凭证采集设备采集函数函数描述采集影像操作函数名int _stdcall photographB(char* retFileName, int type, char * retMsg)属性变量名称类型变量含义备 注入口参数typeint凭证类型取值见附件说明入口参数retFileNamechar *图像保存文件名称（全路径的）最大长度：128出口参数retMsgchar*执行结果中文解释最大长度：60返回值retCodeint执行结果状态码0 Success；非0retMsg解释附加说明所有证件类型代码遵循以下解释：0：JPG原始图片1：JPG 裁剪图片2：保留. 凭证采集设备类型码定义范例电子凭证采集设备类型码定义范例设备类型状态码描述电子凭证采集设备正常空闲正常，主摄像头可用正常，两（主辅）摄像头可用正常，主摄像头被占用设备故障端口不存在（端口指串口或并口）端口打开失败设备不支持该功能无响应（设备未连接，通讯超时，设备故障）.1. 二代身份证阅网页OCX控件规范二代证阅读功能及读写卡功能对接营业系统，需厂商提供网页OCX控件。3.1.1. 控件引入要求控件使用同一classid，OCX控件名称建议使用IDCardReader.ocx名称取值classid（强制取值）clsid:-7507-44FE-ACE8-2B3483D179B7OCX控件名称（参考取值）IDCardReader.ocx网页中能使用下面代码来访问OCX控件：3.1.2. 控件方法控件要求提供以下方法：方法名称方法说明返回值类型返回值说明ListReaderCard获取读卡器连接状态Int1： 读卡器连接状态正常0：无读卡器连接-1：异常ReadCard读卡BStr0：表示读卡成功；-1:未发现设备-4:设备超时-6:未发现证件网页中能使用下面代码来访问OCX控件的方法，具体的方法示例：1. ListReaderCard 方法Var readerState = CVR_IDCard. ListReaderCard();2. ReadCard方法var strReadResult=CVR_IDCard.ReadCard();if (strReadResult=0)/ 读卡成功else / 读卡失败alert(strReadResult);3.1.3. 控件属性控件要求提供以下属性，全为BSTR类型：属性名称属性说明Name姓名，要求中间无空格Sex性别，取值为“1”（表示“男”）或“0”（表示“女”）Nation民族，汉字即可Born出生日期，要求格式为: yyyyMMdd，长度为8Address地址CardNo居民身份号码，长度18位IssuedAt签发机关EffectedDate起始有效期，要求格式为: yyyyMMdd，长度为8ExpiredDate终止有效期，要求格式为:yyyyMMdd，长度为8Picture照片数据流，要求为JPG数据流进行BASE64编码得到的字符串CardReaderId二代证阅读器中安全模板唯一标识ID，修改为10位数字，不含任何字符，具体数字为公安部统一制式的模块号（此10位编码唯一）。iccidnum获取ICCID号，调用成功ReadICCID后获取要求在调用完控件的ReadCard()方法成功后，通过(如CVR_IDCard.Name)上述属性都得到正确的取值。3.1.4. 软件安装要求厂商提供安装软件，该安装软件具备如下功能：驱动和控件等安装所需文件需打包在一个安装程序中，免驱动的设备需提供控件的安装程序。驱动默认安装目录C:IDCardReader。安装浏览器的OCX控件及相关所依赖的文件，需符合本文档对OCX控件的要求。驱动程序和OCX控件需支持WindowsXP，WIN7（包括32位和64位）。浏览器需支持IE6,IE7,IE8以及360。操作系统浏览器WindowsXPIE6IE7IE8360WIN7（32位和64位）IE8360安装程序启动运行后能实现自动识别操作系统版本和浏览器版本而进行相应的安装，安装过程信息明确，尽量减少人工交互，并自动注册OCX控件。 对于已经安装过时版本控件的系统，要能保证读卡器软件安装后，新控件可以覆盖原控件并生效。3.1.5. 基准测试网页各厂家要保证基于如上操作系统和浏览器在基准测试网页上能测试通过，并保证不弹出安全提示对话框，说明插件符合规范要求。3.2. 读写卡功能模块网页OCX控件规范读写卡功能对接营业系统，需厂商提供网页OCX控件。3.2.1. 控件引入要求控件使用同一classid，OCX控件名称建议使用IDCardWriter.ocx名称取值classid（强制取值）clsid:43E4D4FC-3CD8-459A-AAA1-698C1288DE93OCX控件名称（参考取值）IDCardWriter.ocx网页中能使用下面代码来访问OCX控件：3.2.2. 控件方法控件要求提供以下方法：方法名称方法说明返回值类型返回值说明GetErrMsg获取错误描述BSTR错误描述ListCard获取设备型号BSTR设备型号ConnectCard(LPCTSTR dev)连接设备BSTR成功返回 0 失败返回其他TransmitCard(LPCTSTR cmd, LPCTSTR dev)命令交互BSTR返回写卡器返回的apduDisconnectCard(LPCTSTR dev)断开设备BSTR成功返回空失败返回其它1. GetErrMsg方法var err= IDCardWriter.GetErrMsg();alert(err);2. ListrCard 方法var str = IDCardWriter.ListCard();3. ConnectCard 方法var str = IDC