Biovo乙木指静脉采集仪SDKAPI文档标准版v330.docx
《Biovo乙木指静脉采集仪SDKAPI文档标准版v330.docx》由会员分享，可在线阅读，更多相关《Biovo乙木指静脉采集仪SDKAPI文档标准版v330.docx（21页珍藏版）》请在冰豆网上搜索。
Biovo乙木指静脉采集仪SDKAPI文档标准版v330
Biovo®乙木®指静脉采集仪SDK说明文档
修订版
深圳乙木生物识别技术有限公司
2012-5-30
版本号
日期
页数
内容
负责人
1.00
2008-3-20
9
初稿
2.00
2010-7-5
11
3.00
2011-11-21
12
3.30
2012-5-30
14
目录
SDK说明文档1
1基本概述3
2术语说明3
3API使用方法4
4函数说明4
4.1SDK控制类4
4.2静脉识别类5
4.3设备控制类9
5其它12
1基本概述
文件：
静态连接库：
FVIAPI3.lib
动态连接库：
FVIAPI3.dll
头文件：
FVIAPI.h
修定时间:
2012/5/30
API一览：
类别
函数名
说明
SDK控制类
FVI_Init
初始化SDK内部数据
FVI_Start
开启设备监听
FVI_Stop
关闭监听销毁设备对象
静脉识别类
FVI_GetTemplate
获取模板数据
FVI_SetTemplate
设置模板数据
FVI_GetTemplateSize
获取模板大小
FVI_Enroll
用户信息登入
FVI_Verify
对指定用户进行身份验证
FVI_DeleteRecord
删除已登入的记录
FVI_SetIndex
下载索引表
FVI_GetIdentifyLog
获取验证日志
FVI_ClearLog
清除验证日志
FVI_GetLogCount
获取已保存日志数
FVI_RegisterBegin
开启注册
FVI_RegisterEnd
终止注册
FVI_StartICCardReader
开始读IC卡号
设备控制类
FVI_Attach
打开设备
FVI_Check
检查设备
FVI_GetVersion
得到开发工具当前版本
FVI_GetSecurityLevel
获得当前安全等级
FVI_SetSecurityLevel
设置当前安全等级
FVI_SetDeviceIP
设置设备的IP地址
FVI_SetDeviceID
设置设备的设备号
FVI_SetServIP
设置服务器IP地址
FVI_SetWorkMode
开启注册或认证模式
FVI_SetLogSaved
开启或关闭日志功能
备注：
函数使用应当按流程正确使用。
2术语说明
模板：
从拍摄的手指静脉图像中提取特征，特征信息经过一些优化，加密等处理后即称为模板，它相当于生物识别系统中的密钥。
验证：
预先采集用户的生物特征，存储为模板；在需要身份识别的时候，临时获取用户的生物特征，与以前采集的模板比对，根据两个模板的相似度，来确定是否为同一个人。
识别：
与验证类似，但它是在不知道是哪个用户的条件下验证身份，这需要临时获取的用户模板与以前采集的所有用户的模板逐一比对，以此来确定用当前户身份。
自动识别：
设备的工作模式，当设备设置为自动识别模式时，不需要上位机的操作，设备可以主动作出响应，当手指放入设备时，设备可以自动进行识别认证操作。
API使用的常量的定义参见FVIAPI2.h头文件。
3API使用方法
基本流程：
[FVI_Init]
[FVI_Start]
FVI_Attach->
FVI_Check->
FVI_Verify/FVI_Identify/FVI_Enroll/FVI_GetTemplate
NotifyCallBack->
WM_TCP_CONNECT
WM_TCP_DISCONNECT
[FVI_Stop]
4函数说明
4.1SDK控制类
[函数原型]
LONGFVI_Init（void）
[参数说明]
无参数
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
初始化BSP（biometricserviceprovider），加载FVI的SPI
[函数原型]
LONGFVI_Start（FVI_NOTIFYCALLBACKFVINotifyCallback,void*FVINotifyCallbackCtx）
[参数说明]
FVINotifyCallback：
响应设备事件的消息处理函数，其函数形式如下：
LONGFVI_NOTIFYCALLBACK（void*FVINOTIFYCallbackCtx,BioAPI_DEVICE_IDDeviceID,UINTMsgContent,BioAPI_MODULE_EVENTEventType）。
其参数说明如下：
FVINOTIFYCallbackCtx：
调用者指针
DeviceID：
设备号
MsgContent：
消息内容缓存
消息
说明
BioAPI_NOTIFY_AUTO_IDENTIF
4位：
用户ID；2位：
模板号；2位：
结果
其它
暂时未用
EventType：
消息号
宏名
数值
说明
BioAPI_NOTIFY_TCP_CONNECT
0x0D01
新TCP设备连接
BioAPI_NOTIFY_TCP_DISCONNECT
0x0D02
TCP设备断开
BioAPI_NOTIFY_TCP_FAULT
0x0D03
TCP设备故障
BioAPI_NOTIFY_AUTO_IDENTIFY
0x0D07
自动识别
BioAPI_NOTIFY_DEVICE_INSERT
0x0D09
串口设备连接
BioAPI_NOTIFY_DEVICE_REMOVE
0x0D0A
串口设备断开
BioAPI_NOTIFY_INDEX_NUMBER
0x0D0B
返回刷卡获得的卡号
该参数可以为空（NULL），为空时无法返回自动识别的结果。
FVINotifyCallbackCtx：
调用者指针
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
创建设备监听线程，安装设备响应的回调函数
[函数原型]
LONGFVI_Stop（void）
[参数说明]
无参数
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
关闭设备监听线程，同时关闭所有设备连接，此函数与FVI_Start对应，此函数不要在每次操作完成后调用，应该在所有操作完成后调用。
4.2静脉识别类
[函数原型]
LONGFVI_Attach（intdevic）
[参数说明]
devic：
此参数为设备的设备号，设备号存在设备的EPROM里面，在设备连接时，会回传设备号的值
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
关联设备号指定的设备为当前设备，即选中工作设备，当需要对指定设备进行操作时，应先调用此函数，以确定工作设备。
[函数原型]
LONGFVI_Check（void）
[参数说明]
无参数
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
检查当前工作设备是否正常工作，在对设备进行操作前最好先调用此函数来检测设备的连接情况。
[函数原型]
LONGFVI_GetTemplate（LPBYTElpBuffer,DWORDUserID,WORDTemplateID,WORDMilliseconds）
[参数说明]
lpBuffer：
[OUT]指定获取手指静脉特征模板后，模板存储的内存地址
UserID：
设备中的用户ID，指定用户在设备存储空间中的偏移
TemplateID：
指定模板编号此编号取值是0到14
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数获取设备中存储的指定用户的指定模板，模板数据是一串二进制数据，可调用FVI_GetTemplateSize来获取模板的大小然后通过lpBuffer分配相应空间。
此处用户ID是提供给设备存储模板用的偏移，与实际应用中的用户身份编号相对应。
[函数原型]
LONGFVI_SetTemplate（LPBYTElpBuffer,DWORDUserID,WORDTemplateID,WORDMilliseconds）
[参数说明]
lpBuffer：
[IN]指定获取手指静脉特征模板后，模板存储的内存地址
UserID：
设备中的用户ID，指定用户在设备存储空间中的偏移
TemplateID：
指定模板编号此编号取值是0到14
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数FVI_GetTemplate相对就，通过此函数可以设置指定用户的指定模板，即把用户的模板加载到设备存储空间上。
[函数原型]
LONGFVI_GetTemplateSize（void）
[参数说明]
无
[返回值]
返回模板的大小，即占用的字节数
[函数说明]
本函数查询当前版本中，标准模板的大小，以此用来分配上传或下载模板所需要的内存
[函数原型]
LONGFVI_Enroll（DWORDUserID,WORDTemplateID,WORDMilliseconds）
[参数说明]
UserID：
设备中的用户ID，指定用户在设备存储空间中的偏移
TemplateID：
指定模板编号此编号取值是0到14
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出注册请求，设备对放入的手指拍照，生成模板，如果注册时需要把模板存储到上位机，则需要调用此函数后，再调用FVI_GetTemplate来获取模板。
[函数原型]
LONGFVI_Verify（DWORDUserID,WORDTemplateID,WORDMilliseconds）
[参数说明]
UserID：
设备中的用户ID，指定用户在设备存储空间中的偏移
TemplateID：
指定模板编号此编号取值是0到14
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出身份验证的请求，设备接收到指令后立刻采集当前对象的静脉特征，并进行身份验证。
[函数原型]
LONGFVI_DeleteRecord（DWORDUserID,WORDTemplateID,WORDMilliseconds）
[参数说明]
UserID：
设备中的用户ID，指定用户在设备存储空间中的偏移
TemplateID：
指定模板编号此编号取值是0到14
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出请求，用以删除指定用户存储在设备上的模板。
当UserID和TemplateID为-1时，具有通配作用，即当UserID为-1时表示删除所有用户模板，当TemaplateID为-1时，删除指定用户的所有模板。
[函数原型]
LONGFVI_SetIndex（LPBYTElpBuffer,DWORDUserID,WORDMilliseconds）
[参数说明]
lpBuffer：
索引缓冲区
UserID：
指定用户的UID，从0到4999
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备加载索引信息，索引信息包含用户的基本信息如姓名，编号等，其中编号可以用来检索用户进行1：
1验证。
[函数原型]
LONGLONGFVI_GetIdentifyLog（LPBYTElpBuffer,DWORDLogID,WORDMilliseconds）
[参数说明]
lpBuffer：
存放日志缓冲区
LogID：
日志编号
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出取认证日志的请求，日志中保存有索引号，时间，认证结果及现场模板等信息。
日志结构如下（共1024字节）
段名
LogID
INDEX
TID
Time
Result
Resved
Template
长度
（字节）
4
18
2
4
2
98
896
[函数原型]
LONGFVI_RegisterBegin（LPBYTElpBuffer,intlen,WORDMilliseconds）
[参数说明]
lpBuffer：
[IN]开始注册时，传入需要LCD显示的信息
len：
[IN]要显示信息的长度
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出请求，指示开始注册，每个人注册前要调用此函数。
[函数原型]
LONGFVI_RegisterEnd（WORDMilliseconds）
[参数说明]
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出请求，指示中止注册，每个人注册完毕后要调用此函数。
[函数原型]
LONGFVI_StartICCardReader（WORDMilliseconds）
[参数说明]
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出请求，指示允许开始刷卡，开启允许刷卡功能后，通过回调函数获取卡号。
[函数原型]
LONGFVI_GetLogCount（DWORD*lpData,WORDMilliseconds）
[参数说明]
lpData：
[OUT]保存已存入的日志条数
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出请求，查询已存入的日志条数。
[函数原型]
LONGFVI_ClearLog（WORDMilliseconds）
[参数说明]
Milliseconds：
指定操作的超时时间
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出请求，用以清除设备上保存的所有日志。
4.3设备控制类
[函数原型]
LONGFVI_GetVersion（DWORD*lpVersion）
[参数说明]
lpVersion：
存放返回的设备版本号
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
本函数向设备发出请求，用以获取设备的版本号。
[函数原型]
LONGFVI_GetSecurityLevel（DWORD*lpSecLevel）
[参数说明]
pSecLevel：
指向DWORD数据类型变量的指针，用于接收安全等级的值。
该值得意义可以参考SetSecurityLevel的说明
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
取得当前认证用的安全等级。
[函数原型]
LONGFVI_SetSecurityLevel（DWORDdwLevel）
[参数说明]
dwLevel：
要设置安全等级的值。
该值可以是下表中的一个。
值
说明
FVIAPI_HIGH_LEVEL
高精度认证，值为3
FVIAPI_MIDDLE_HIGH_LEVEL
中高精度认证，值为2
FVIAPI_MIDDLE_LEVEL
标准精度认证，值为1
FVIAPI_LOW_LEVEL
低精度认证，值为0
为dwLevel设置上表以外的其它值会使函数失败
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
设置设备当前认证用的安全等级。
安全等级越高，拒真率会相应升高，而误认率也会相应降低。
若未执行此函数，安全等级会使用默认值FVIAPI_MIDDLE_LEVEL。
[函数原型]
LONGFVI_SetDeviceIP（constDWORDDeviceIPAddr）
[参数说明]
DeviceIPAddr：
指定IP地址
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
让设备的IP地址。
[函数原型]
LONGFVI_SetDeviceID（constWORDwDevID）
[参数说明]
DeviceIPAddr：
指定ID地址
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
让设备的IP地址。
[函数原型]
LONGFVI_SetServIP（constDWORDDeviceIPAddr）
[参数说明]
DeviceIPAddr：
指定IP地址
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
向设备发送消息，指定上位机的IP地址。
[函数原型]
LONGFVI_SetWorkMode（constDWORDWorkMode）
[参数说明]
WorkMode:
0表示处于认证模式，1表示非认证模式
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
设备工作在两种状态模式下：
自动识别模式和非自动识别模式，当上位机需要向设备发送指令时，需要设置设备为非自动识别模式状态。
[函数原型]
LONGFVI_SetLogSaved（constDWORDLogSave）
[参数说明]
LogSave:
0不保存认证日志，1表示保存认证日志
[返回值]
如果函数执行成功，返回值为SDK_ERROR_SUCCESS。
返回其它值表示失败。
[函数说明]
认证的记录可以保存在设备的FLASH上，掉电后不会消失，通过此函数可以设置是否保存日志。
5其它
自动识别返回的结果：
typedefstruct
{
DWORDuid;
WORDtid;
WORDrel;
DWORDlogid;
}IDENTIFY_RESULT;
列名
用户id
模板id
验证结果
验证日志id
索引
大小（字节）
4
2
2
4
57
非零时的错误码列表
宏定义
数值
说明
SDK_ERROR_SUCCESS
0
函数返回成功
SDK_ERROR_ACCESS_DENY
1000
拒绝访问
SDK_ERROR_CAPTURE_FALSE
1001
摄影失败
SDK_ERROR_SETUP_DEVICE
1002
设置设备失败
SDK_ERROR_DEVICE_IO_INCORRECT
1003
设备IO操作不正确
SDK_ERROR_CALIBRATION_LIGHT
1004
校准亮度失败
SDK_ERROR_CALIBRATION_CAMERA
1005
调准亮度失败
SDK_ERROR_CALIBRATION_CAPTURE_AREA
1006
调整摄影区域失败
SDK_ERROR_MANAGE_CAMERA_LED
1007
控制LED失败
SDK_ERROR_GET_IMAGE
1008
获取图像失败
SDK_ERROR_GET_DEVICE_HANDLE
1009
获取设备句柄失败
SDK_ERROR_INVALID_ARG_1
1010
传入参数1非法
SDK_ERROR_INVALID_ARG_2
1011
传入参数2非法
SDK_ERROR_INVALID_ARG_3
1012
传入参数3非法
SDK_ERROR_INVALID_ARG_4
1013
传入参数4非法
SDK_ERROR_INVALID_ARG_5
1014
传入参数5非法
SDK_ERROR_GET_CAPTURE_IMAGE
1015
获取摄影图像失败
SDK_ERROR_CALL_GET_BIOMETRIC
1016
获取设备对象失败
SDK_ERROR_INVALID_DATA
1017
传入数据非法
SDK_ERROR_OPEN_DEVICE_FAIL
1018
打开设备失败
SDK_ERROR_INVALID_PTR
1019
无效指针
SDK_ERROR_INTERNAL
1020
内部错误
SDK_ERROR_INVALID_CAPTURETIME
1021
非法的拍摄时间
SDK_ERROR_INVALID_SECURITYLEVEL
1022
非法的安全等级
SDK_ERROR_INVALID_LED_COLOR
1023
非法的LED灯颜色
SDK_ERROR_NOT_CAPTURING
1024
设备不在摄影状态中
SDK_ERROR_USER_ALREADY_EXIST
1025
用户已存在
SDK_ERROR_USER_NOT_FOUND
1026
没找到用户
SDK_ERROR_CAPTURE_TIMEOUT
1027
拍摄超时
SDK_ERROR_RECORD_ALREADY_EXIST
1029
模板记录已存在
SDK_ERROR_RECORD_NOT_FOUND
1030
模板记录未找到
SDK_ERROR_WRONG_USERINFO
1031
错误的用户信息
SDK_ERROR_BIR_NOT_FULLY_PROCESSE
升级会员 