PIBIO_ENGINE_VERIFY_FEATURE_SET_FN función de devolución de llamada (winbio_adapter.h)
Llamado por Windows Biometric Framework para comparar la plantilla del conjunto de características actual con una plantilla específica de la base de datos. Si las plantillas son equivalentes, el adaptador del motor debe establecer el valor booleano al que apunta el parámetro Match en TRUE, devolver la plantilla coincidente en el parámetro PayloadBlob y devolver un hash de la plantilla en el parámetro HashValue .
Sintaxis
PIBIO_ENGINE_VERIFY_FEATURE_SET_FN PibioEngineVerifyFeatureSetFn;
HRESULT PibioEngineVerifyFeatureSetFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[in] PWINBIO_IDENTITY Identity,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[out] PBOOLEAN Match,
[out] PUCHAR *PayloadBlob,
[out] PSIZE_T PayloadBlobSize,
[out] PUCHAR *HashValue,
[out] PSIZE_T HashSize,
[out] PWINBIO_REJECT_DETAIL RejectDetail
)
{...}
Parámetros
[in, out] Pipeline
Puntero a una estructura de WINBIO_PIPELINE asociada a la unidad biométrica que realiza la operación.
[in] Identity
Puntero a una estructura de WINBIO_IDENTITY que contiene un GUID o SID que se espera que coincida con el de la plantilla recuperada de la base de datos.
[in] SubFactor
Valor de WINBIO_BIOMETRIC_SUBTYPE que se espera que coincida con el de la plantilla recuperada de la base de datos. Para obtener información más detallada, consulte la sección Comentarios.
[out] Match
Puntero a un valor booleano que especifica si los parámetros Identity y SubFactor coinciden con los de la plantilla recuperada de la base de datos. TRUE especifica que estos valores coinciden.
[out] PayloadBlob
Dirección de una variable que recibe un puntero a los datos de carga guardados con la plantilla. Si no hay datos de carga, establezca este valor en NULL.
[out] PayloadBlobSize
Puntero a un valor que recibe el tamaño, en bytes, del búfer especificado en el parámetro PayloadBlob . Si no hay datos de carga almacenados con la plantilla, establezca este valor en cero.
[out] HashValue
Dirección de una variable que recibe un puntero al hash de la plantilla. Si el adaptador del motor no admite la generación de hash, establezca este valor en NULL.
[out] HashSize
Puntero a un valor que contiene el tamaño, en bytes, del hash especificado por el parámetro HashValue . Si el adaptador del motor no admite la generación de hash, establezca este valor en cero.
[out] RejectDetail
Puntero a un valor de WINBIO_REJECT_DETAIL que recibe información adicional si un error de captura impide que el motor realice una operación coincidente. Si la captura más reciente se realizó correctamente, establezca este parámetro en cero. Los siguientes valores se definen para la captura de huellas digitales.
- WINBIO_FP_TOO_HIGH
- WINBIO_FP_TOO_LOW
- WINBIO_FP_TOO_LEFT
- WINBIO_FP_TOO_RIGHT
- WINBIO_FP_TOO_FAST
- WINBIO_FP_TOO_SLOW
- WINBIO_FP_POOR_QUALITY
- WINBIO_FP_TOO_SKEWED
- WINBIO_FP_TOO_SHORT
- WINBIO_FP_MERGE_FAILURE
Valor devuelto
Si la función se ejecuta correctamente, devuelve S_OK. Si se produce un error en la función, debe devolver uno de los siguientes valores HRESULT para indicar el error.
| Código devuelto | Descripción |
|---|---|
|
Un parámetro de puntero obligatorio es NULL. |
|
El valor especificado en el parámetro SubFactor no es correcto. |
|
El conjunto de características no cumplió los requisitos internos del adaptador del motor para una operación de comprobación. El parámetro RejectDetail especifica más información sobre el error. |
|
El conjunto de características de la canalización coincide con uno almacenado en la base de datos, pero no corresponde a la combinación de valores pasados en los parámetros Identity y SubFactor . |
Comentarios
El parámetro SubFactor especifica el subfactor asociado a la plantilla biométrica. Windows Biometric Framework solo admite la captura de huellas digitales y puede usar las siguientes constantes para representar información de subtipo.
- WINBIO_ANSI_381_POS_RH_THUMB
- WINBIO_ANSI_381_POS_RH_INDEX_FINGER
- WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_RH_RING_FINGER
- WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
- WINBIO_ANSI_381_POS_LH_THUMB
- WINBIO_ANSI_381_POS_LH_INDEX_FINGER
- WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_LH_RING_FINGER
- WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
- WINBIO_SUBTYPE_ANY
No intente validar el valor proporcionado para el parámetro SubFactor . El servicio biométrico de Windows validará el valor proporcionado antes de pasarlo a la implementación. Si el valor es WINBIO_SUBTYPE_NO_INFORMATION o WINBIO_SUBTYPE_ANY, valide cuando corresponda.
El valor hash devuelto por esta función, si existe, es el hash de la plantilla de inscripción que se encuentra en la base de datos, no la plantilla coincidente asociada a la canalización.
Los búferes PayloadBlob y HashValue son propiedad y los administra el adaptador del motor después de que la función EngineAdapterIdentifyFeatureSet se devuelva correctamente. El adaptador del motor debe mantener válida la dirección del búfer, para esta canalización, hasta la siguiente llamada a EngineAdapterClearContext.
Ejemplos
El siguiente pseudocódigo muestra una posible implementación de esta función. El ejemplo no se compila. Debes adaptarlo para que se adapte a tu propósito.
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterVerifyFeatureSet
//
// Purpose:
// Compares the template in the current feature set with a specific
// template in the database.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation
// Identity - GUID or SID that is expected to match that of the
// template recovered from the database
// SubFactor - A WINBIO_BIOMETRIC_SUBTYPE value that is expected
// to match that of the template recovered from the
// database
// Match - A Boolean value that specifies whether the Identity
// and SubFactor parameters match those of the template
// recovered from the database
// PayloadBlob - Payload data saved with the template
// PayloadBlobSize - Size, in bytes, of the buffer specified in the
// PayloadBlob parameter
// HashValue - Hash of the template
// HashSize - Size, in bytes, of the hash specified by the
// HashValue parameter
// RejectDetail - Receives additional information if a capture failure
// prevents the engine from performing a matching operation
//
static HRESULT
WINAPI
EngineAdapterVerifyFeatureSet(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_IDENTITY Identity,
__in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
__out PBOOLEAN Match,
__out PUCHAR *PayloadBlob,
__out PSIZE_T PayloadBlobSize,
__out PUCHAR *HashValue,
__out PSIZE_T HashSize,
__out PWINBIO_REJECT_DETAIL RejectDetail
)
{
HRESULT hr = S_OK;
WINBIO_STORAGE_RECORD thisRecord;
BOOLEAN match = FALSE;
WINBIO_REJECT_DETAIL rejectDetail = 0;
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(Identity) ||
!ARGUMENT_PRESENT(Match) ||
!ARGUMENT_PRESENT(PayloadBlob) ||
!ARGUMENT_PRESENT(PayloadBlobSize) ||
!ARGUMENT_PRESENT(HashValue) ||
!ARGUMENT_PRESENT(HashSize) ||
!ARGUMENT_PRESENT(RejectDetail))
{
hr = E_POINTER;
goto cleanup;
}
// Retrieve the context from the pipeline.
PWINBIO_ENGINE_CONTEXT context =
(PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;
// Initialize the return values.
*Match = FALSE;
*PayloadBlob = NULL;
*PayloadBlobSize = 0;
*HashValue = NULL;
*HashSize = 0;
*RejectDetail = 0;
// The biometric unit cannot perform verification or identification
// operations while it is performing an enrollment sequence.
if (context->Enrollment.InProgress == TRUE)
{
hr = WINBIO_E_ENROLLMENT_IN_PROGRESS;
goto cleanup;
}
// Query the storage adapter to determine whether the Identity and
// SubFactor combination specified on input are in the database. If
// they are not, there can be no match. WbioStorageQueryBySubject
// is a wrapper function defined in the Winbio_adapter.h header file.
hr = WbioStorageQueryBySubject( Pipeline, Identity, SubFactor);
if (FAILED(hr))
{
if (hr == WINBIO_E_DATABASE_NO_RESULTS)
{
hr = WINBIO_E_NO_MATCH;
}
goto cleanup;
}
// Position the cursor on the first record in the database.
// WbioStorageFirstRecord is a wrapper function defined in the
// Winbio_adapter.h header file.
hr = WbioStorageFirstRecord( Pipeline );
if (FAILED(hr))
{
goto cleanup;
}
// Retrieve the current template record for the Identity and SubFactor
// combination specified on input.
hr = WbioStorageGetCurrentRecord( Pipeline, &thisRecord );
if (FAILED(hr))
{
goto cleanup;
}
// Call a custom function (_AdapterCompareTemplateToCurrentFeatureSet)
// to compare the feature set attached to the pipeline with the template
// retrieved from the database.
// If the template and feature set do not match, return WINBIO_E_NO_MATCH
// and set the Match parameter to FALSE.
// If your custom function cannot process the feature set, return
// WINBIO_E_BAD_CAPTURE and set extended error information in the
// RejectDetail parameter.
hr = _AdapterCompareTemplateToCurrentFeatureSet(
context,
context->FeatureSet,
context->FeatureSetSize,
thisRecord.TemplateBlob,
thisRecord.TemplateBlobSize,
&match,
RejectDetail
);
if (FAILED(hr))
{
goto cleanup;
}
// If there is a match and if your engine adapter supports template
// hashing, call a custom function (_AdapterGenerateHashForTemplate)
// to calculate the hash. Save the hash value in the context area of
// the engine adapter.
// Skip this step if your adapter does not support template hashing.
hr = _AdapterGenerateHashForTemplate(
context,
thisRecord.TemplateBlob,
thisRecord.TemplateBlobSize,
context->HashBuffer,
&context->HashSize
);
if (FAILED(hr))
{
goto cleanup;
}
// Set the return values.
*Match = TRUE;
*PayloadBlob = thisRecord.PayloadBlob;
*PayloadBlobSize = thisRecord.PayloadBlobSize;
*HashValue = &context->HashBuffer;
*HashSize = context->HashSize;
cleanup:
if (hr == WINBIO_E_DATABASE_NO_RESULTS)
{
hr = WINBIO_E_NO_MATCH;
}
return hr;
}
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 7 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 R2 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | winbio_adapter.h (incluya Winbio_adapter.h) |