FS562开发手册.doc

证件扫描、识别、读卡SDK开发手册目录第一章 SDK简介21.1SDK运行环境21.2SDK主要功能描述21.3调用约束21.4SDK文件清单：21.5SDK使用流程简述3第二章 设备的安装和使用42.1设备的安装42.2设备的使用4第三章 接口调用63.1接口参数中用到结构的定义：63.2接口函数返回值列表103.3扫描、识别、读卡接口说明：113.3调用流程简图：163.4 示例程序简介17第一章 SDK简介1.1 SDK运行环境本SDK可在以下操作系统中调用：Microsoft Windows Nt4.0、Microsoft Windows98、Microsoft Windows2000、Microsoft WindowsXP。使用本SDK要求计算机不得低于以下配置：PIII800 Mhz(CPU)、128M（内存）。1.2 SDK主要功能描述本SDK主要实现了以下几项功能：1) 驱动设备录入仪进行扫描，得到各种身份证件图像文件（包括一代身份证、二代身份证、护照等）。2) 根据用户的需求对一代身份证、二代身份证、护照、港澳往来大陆的通行证、台胞证图像中的相关字段信息部分进行识别，并将识别结果根据用户的要求保存到一个txt文本中。3) 根据用户的需求可以将一代身份证、二代身份证、护照、港澳往来大陆的通行证、台胞证图像中的证件头像提取出来，保存到指定的图像文件中。4) 驱动设备读卡器读取二代身份证中的居民个人身份信息和头像。1.3 调用约束在调用身份证扫描、识别、读卡SDK前，请确保设备设备已正确安装，并正常连接。这也就是说，本SDK只有在挂接设备设备后才能正常调用，否则将加载失败无法调用。1.4 SDK文件清单：DEMO 文件夹：设备功能演示程序。Driver 文件夹：设备驱动。DLL-Data文件夹：设备扫描、识别、读卡SDK核心文件（Drv_CardAll.dll）。Document文件夹：设备扫描、识别、读卡SDK开发手册。Samples 文件夹： SDK的C+，语言调用例程。LIB-H文件夹：设备扫描、识别、读卡SDK核心链接文件和头文件。1.5 SDK使用流程简述一般说来，使用SDK的大致流程如下：安装设备进行扫描识别或读卡卸载扫描、识别、读卡SDK库加载扫描、识别、读卡SDK库Drv_CardAll.dllDrv_CardAll.dllDrv_CardAll.dll第二章 设备的安装和使用2.1 设备的安装本SDK采用设备加密，故使用SDK核心时必须首先正确连接设备设备，并根据系统提示安装好相应的驱动程序。当把设备FS562插接到PC机的USB口上后，操作系统会提示“发现新的硬件设备”并要求安装该设备的驱动程序，这时请指定设备驱动程序所在路径即可完成设备的安装。2.2 设备的使用（1） 要使用设备的所有功能，需要生成License文件，方法如下：一、运行 注册文件生成器 程序二、将设备使用手册首页上的序列号填写到程序界面，将生成的VerifyPsw.dat放到Drv_CardAll.dll所在目录下即可（2） 设备录入仪的校准： 使用设备时，如果扫描得到的图像质量下降，用户需要校准设备录入仪，以提高扫描图像的质量。如果校准后扫描质量仍不是太好(如有纵向条纹等)，这时可以通过扫描图像工具或SDK中的演示程序再进行重复校准（也可以调用SDK中的校准函数实现）。具体方法如下：如果采用扫描工具进行校准，只需点击twain界面上的校准按钮即可（如下图）；如果采用演示程序校准，只需点击演示界面上的“校准录入仪”按键；如果是采用SDK核心的接口来校准，可以参考后面的接口调用流程来实现 。（2）身份证件的扫描：在通过SDK核心扫描、识别各种身份证件图像时，身份证件应该顶住扫描玻璃平板的左上角，这样才能保证扫描得到的图像能够满足后序识别的要求（如下图）。对于一、二代身份证,将身份证件的宽边和扫描玻璃平板的左边贴紧，而护照进行扫描识别时，将护照展开，放置在扫描玻璃平板上。录入仪上的四个按键（其中A和D键功能相同）可以通过SDK核心中的接口来分别定义和控制，具体使用方法见后面接口说明部分。第三章 接口调用本章我们将扫描、识别、读卡等接口进行阐述。由于实际所使用到的编程语言很多，我们不可能一一涉及到。我们在此只将C+语言对接口如何进行调用进行讲解。其它语言如何进行调用，用户可参照接口调用例程。3.1接口参数中用到结构的定义：(1)身份证件全部识别结果导出结构（包括签发日期和有效期）typedef structchar name 40;/姓名char SurnameCH100;/中文姓char nameCH100;/中文名char sex10;/性别char Gender10;/性别（英文）char birthday50;/出生日期char people20;/民族char signdate50;/发证日期char validterm50;/有效期限char address200;/地址char number40;/身份证号码char organs50;/发证机关char SurnameEN100;/英文姓(汉语拼音)char nameEN100;/英文名(汉语拼音)char ENfullname40;/英文姓名char Nationality200;/国籍char id100;/证件号码char Leavetime50;/离开时间char placeCH100;/签发地点中文char placeEN100;/签发地点英文char BirthplaceCH100; /出生地中文 char BirthplaceEN100;/出生地英文char szCodeOne256;/第一行代码识别结果char szCodeTwo256;/第二行代码识别结果char szCodeThree256;/第三行代码识别结果char Permitnumber_number40; /港澳证件号码char Vocational200;/职业char DocumentsCategory100; /证件类别char Other200;IDCARD_ALL; (2)扫描时设置参数的结构体：#define SCAN_R_MODE1#define SCAN_G_MODE2#define SCAN_B_MODE3#define SCAN_GRAY_MODE4#define SCAN_IR_MODE5#defineSCAN_COLOR_MODE6#define SCAN_200_DPI200#define SCAN_300_DPI300#define SCAN_400_DPI400#define SCAN_600_DPI600struct Scan_Para short scan_mode; / SCAN_R_MODE1/ SCAN_G_MODE2/ SCAN_B_MODE3/ SCAN_GRAY_MODE4/ SCAN_IR_MODE5/ SCAN_COLOR_MODE6 short top; / unit pixel, min = 0 max = 600 short left; / unit pixel, min = 0 max = 512 short bottom; / unit pixel, min = 0 max = 600 short right / unit pixel, min = 0 max = 512 short resolution; / in dpi / 推荐：SCAN_300_DPI300 short scan_size; / paper size; 0 : user defined ,1 - 8 short brightness; / 0 short contrast; short gamma; / 10 short highlight; /0 正常亮度/1 亮度增强/2 亮度更强 short shadow; short Rbrightness; short Rcontrast; short Rgamma; short Rhighlight; short Rshadow; short Gbrightness; short Gcontrast; short Ggamma; short Ghighlight; short Gshadow; short Bbrightness; short Bcontrast; short Bgamma; short Bhighlight; short Bshadow; short halftone_pattern; short delay; / 0 : false, 1 : true, ignore it short compress; / 0 : no compress , 1 : compress short trimedge; / 0 : no trimedge , 1: trimedge short deskew; / 0 : no deskew , 1: deskew short scanpage; / 0 : single page 1: multiple page short autoscan; / 0 : use manual scan, 1 : use auto scan short ADF; / 0 : no ADF 1: use ADF short qualityscan; / 0 : speed scan 1:quality scan short BWthreshold; / from 0 to 255 short filter; / 0: none; 1 : despeckle; 2:descreen; 3:sharpen short inversion; / 0 : no inverse image 1: inverse image short colormatch; / 0 : no color match 1 use color match short channel; / 0 : all, 1: R, 2 G, 3 B short papertype; short exposure; short method; / 0: auto mode 1 :manual mode ;注意：Scan_Para中的成员不需要全部赋值，可参考以下基本赋值方法。为了保证赋值准确，请在赋值前将结构体清零。基本赋值方法：Scan _Para.scan_mode = SCAN_IR_MODE;/一代证使用去底纹模式/其它证件使用灰度模式Scan _Para.left = 0;Scan _Para.top = 3;Scan _Para.right = 300;Scan _Para.bottom = 200;Scan _Para.brightness = 0;Scan _Para.contrast = 0;Scan _Para.resolution = SCAN_300_DPI;Scan _Para.gamma = 10;Scan _Para.highlight = 0;Scan _Para.qualityscan = 1;Scan _Para.inversion = 0; 3.2接口函数返回值列表宏 返回值含义对应10进制EXCUTE_SUCCESS 0x0000000000 初始化成功0DLLPATH_ERROR 0x0000000001DLL或OCR库文件路径错误1INITMEM_ERROR 0x0000000002 初始化内存错误2NOT_CONNECTSCANNER 0x0000000003没有连接录入仪3NOT_SETUPFRIVER 0x0000000004没有安装设备驱动4CANNOT_READSAMINFO 0x0000000005不能读取安全模块信息5NOT_MATCHSAMINFO 0x0000000006安全模块信息不匹配6INIT_FAILURE 0x0000000007初始化失败7CANNOT_READDEVICESRL 0x0000000008读取设备串号失败8CANNOT_READVIDPID 0x0000000009读取设备VIDPID失败9NOT_NEEDCALIBRATION 0x000000000A设备不需要校正10ERROR_CALIBRATION 0x000000000B设备校正出错11DEVNOTOK0x000000000C设备不OK12DEVOFFLINE0x000000000D设备断开13DEVRELINKOK0x000000000E设备重连成功14PRESS_KEYN 0x0000000010没有按键16PRESS_KEYA 0x0000000011按了设备A或D键17PRESS_KEYB 0x0000000012按了设备B键18PRESS_KEYC 0x0000000013按了设备C键19START_SCANNER_FAILURE 0x0000000020扫描启动失败32SCANNING_FAILURE0x0000000021扫描过程失败33SAVEFILENAME_ERROR0x0000000022保存图像文件名有错误34GETIMAGEDATA_ERROR0x0000000023得到图像数据错误35ERROR_SAVEFILEEPNAME 0x0000000024保存图像扩展名错误36RECG_FAILURE 0x0000000030识别失败48NO_PHOTOIAMGE 0x0000000031身份证无头像49IS_COPYCARD 0x0000000032是复印件50NOTUSE_RFIDFUNC 0x0000000040无法使用RFID读卡函数64CANNOT_STARTRFID0x0000000041无法启动RFID65READRFID_FAILURE0x0000000042RFID读卡失败66CANNOT_READPHOTO 0x0000000043不能读出头像67CANNOT_SAVEPHOTO 0x0000000044不能保存头像68DEVICE_BUSY0x0000000046设备正在工作703.3扫描、识别、读卡接口说明：（Drv_CardAll.dll和Drv_CardAll.lib 接口介绍）1) 函数：int WINAPI LoadIdcardLibrary()功能：启动录入仪，初始化识别核心，载入识别库；参数：无；返回值：EXCUTE_SUCCESS -加载成功；其它见3.2返回值列表说明：LoadIdcardLibrary函数将装载设备设备驱动，以及OCR识别所需的库文件。因此，以下SDK接口函数必须在成功调用LoadIdcardLibrary函数后才可以正常调用。返回值为EXCUTE_SUCCESS时，可以正常使用设备提供的扫描识别和读卡功能；返回值为CANNOT_READSAMINFO或NOT_MATCHSAMINFO时，只可以正常使用设备提供的扫描识别功能，不能使用读卡功能。2) 函数int WINAPI CalibrateScanner()功能：校准录入仪。参数：无；返回值：见3.2返回值列表3) 函数：void WINAPI FreeIdcardLibrary()；功能：释放扫描识别库；参数：无；返回值：无。4) 函数int WINAPI GetButtonDownType()功能：获取当前是否有录入仪按钮按下事件发生，并得到按钮按下的类型。参数：无；返回值：见3.2返回值列表5) 函数int WINAPI ScanImageByUser (char* pchFilePath1, char* pchFilePath2, Scan_Para& sP1, Scan_Para& sP2, int lCardType, int lContrlType, int lJPEG_QUALITY)功能：用户自定义扫描图像参数：pchFilePath1:为进程扫描得到的图像文件的保存路径及名称(包含扩展名，不能为空)； pchFilePath2：为回程扫描后图像文件的保存路径及名称(包含扩展名，不能为空)；sP1：为进程扫描参数，详见3.1，用户可以自由控制扫描参数，但是当lCardType的值为预设值时，有关图像大小的参数无效。sP2：为回程扫描参数，仅当lContrlType的值为2时有效， 注意回程扫描参数的尺寸和进程设置相同，其他可以不同。lCardType：固化证件类型：1-一代身份证， 2-驾照，3-护照（自动判别国内、国际护照）， 4-二代身份证，5护照签证页及外国人居留许可证，6-台胞证，7-港澳通行证，如果用户对lCardType赋了上述值，则sP1或sP2中设置的扫描区域将实效，而被固定为对应证件的尺寸，用户设置的扫描模式等仍旧有效。lJPEG_QUALITY:JPG图像质量指标，越大越清晰，取值0-100。只对jpg图像有效，质量越高，占用空间越大。我们建议将这个参数设为15，这样能在保证图象质量的情况下（等比显示），最大限度的节省磁盘空间。lContrlType：控制字，对应扫描工作方式0 - 普通方式，去程扫描后，扫描头将自动回程复位1 - 单程方式，去程扫描后，不让扫描头复位,下次扫描时可采用单程方式做回程扫描，节省时间。若使用其它方式。录入仪将先复位再进行扫描。2- 双程方式，去程扫描后，系统自动回程扫描，这样可以得到同一证件的两次扫描图像。返回值：见3.2返回值列表6) 函数void WINAPI FeedBackScanner ()功能：完成录入仪的回程复位。参数：无；返回值：无7) 函数int WINAPI ScanAndRcgCard(char* pchFilePath1, char* pchFilePath2, char* HeadImgFName, CARDRST & rcgCard, Scan_Para& sP1, Scan_Para& sP2, int lCardType, int lScanContrl, int lRcgContrl, int lSaveContrl, int lJPEG_QUALITY )功能：实现对不同证件的扫描并识别参数：pchFilePath1：进程扫描后图像文件的保存路径及名称(包含扩展名，不能为空)； pchFilePath2：为回程扫描后图像文件的保存路径及名称(包含扩展名，不能为空)；HeadImgFName：头像文件的保存路径及名称(包含扩展名)。（当lCardType为5时，不生成头像）。rcgCard：识别结果结构IDCARD_ALL的引用,返回的识别结果信息置于此。sP1：为进程扫描参数。sP2：为回程扫描参数，仅当lScanContrl为2时有效，注意回程扫描参数的尺寸和进程设置相同，其他可以不同。lCardType：证件类型：1-一代身份证， 2-驾照（预留），3-护照（自动判国际护照）， 4-二代身份证，5国际签证页及居留许可证，6-台胞证，7-港澳通行证(照片页)，如果用户对lCardType赋了上述值，则sP1或sP2中设置的扫描区域将失效，而被固定为对应证件的尺寸，用户设置的扫描模式等仍旧有效。只有lCardType赋值为1，3，4，5，6，7时，才有识别结果lScanContrl：扫描控制字，对应扫描工作方式0 - 普通方式，进程扫描后，扫描头自动回程复位1 - 单程方式，进程扫描后，不让扫描头复位,下次扫描可采用回程方式扫描2- 双程方式，进程扫描后，系统自动回程扫描，这样可以得到同一证件的两次扫描图像lRcgContrl：识别控制字，0-不识别； 1-识别lSaveContrl：保存识别结果控制字，0-不保存，1-保存；如果保存，则将识别结果保存到对应的文本文件中。lJPEG_QUALITY：JPG图像质量指标，越大越清晰，取值0-100，我们建议将这个参数设为15，这样能在保证图象质量的情况下（等比显示），最大限度的节省磁盘空间。返回值：见3.2返回值列表8) 函数 int WINAPI RcgCardImage( char* pchFilePath, char* HeadImgFName, CARDRST & rcgCard, int lCardType, int lSaveContrl, int lJPEG_QUALITY)功能：实现对不同证件的图像识别（导入识别）参数：pchFilePath:所要识别身份证图像文件的路径名（绝对路径），文件的扩展名只能是BMP/bmp/jpg/JPGHeadImgFName：照片的保存路径及名称(包含扩展名)。（当lCardType为5时，不生成头像）。rcgCard：识别结果结构IDCARD_ALL的引用,返回的识别结果信息置于此。lCardType：证件类型：1-一代身份证， 2-驾照，3-护照（自动判别国内、国际护照）， 4-二代身份证，5护照签证页及外国人居留许可证，6-台胞证，7-港澳通行证(照片页)，如