PIBIO_ENGINE_IDENTIFY_FEATURE_SET_FN función de devolución de llamada (winbio_adapter.h)
Llamado por Windows Biometric Framework para compilar una plantilla a partir del conjunto de características actual y buscar una plantilla coincidente en la base de datos. Si se puede encontrar una coincidencia, el adaptador del motor debe rellenar los parámetros Identity, SubFactor, PayloadBlob con la información adecuada de la plantilla almacenada.
Sintaxis
PIBIO_ENGINE_IDENTIFY_FEATURE_SET_FN PibioEngineIdentifyFeatureSetFn;
HRESULT PibioEngineIdentifyFeatureSetFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[out] PWINBIO_IDENTITY Identity,
[out] PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
[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.
[out] Identity
Puntero a una estructura de WINBIO_IDENTITY que contiene el GUID o el SID de la plantilla recuperada de la base de datos. Este valor solo se devuelve si se encuentra una coincidencia.
[out] SubFactor
Valor de WINBIO_BIOMETRIC_SUBTYPE que recibe el subfactor asociado a la plantilla de la base de datos. Para obtener información más detallada, consulte la sección Comentarios. Este valor solo se devuelve si se encuentra una coincidencia.
[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 una variable que recibe el tamaño, en bytes, del búfer especificado por el parámetro PayloadBlob . Si no hay datos de carga, establezca este valor en cero.
[out] HashValue
Dirección de una variable que recibe un puntero al valor hash generado para la plantilla. Si el adaptador del motor no admite la generación de hash, establezca este valor en NULL.
[out] HashSize
Puntero a una variable que recibe el tamaño, en bytes, del búfer 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 una variable 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 valores siguientes 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 para indicar que la última actualización se realizó correctamente y no se requiere ningún conjunto de características adicional para completar la plantilla. 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 |
|---|---|
|
El parámetro Pipeline es NULL. |
|
El conjunto de características no cumplió los requisitos internos del adaptador del motor para una operación de identificación. El parámetro RejectDetail especifica más información sobre el error. |
|
El conjunto de características de la canalización no corresponde a ninguna identidad de la base de datos. |
Comentarios
El algoritmo usado para generar el hash de plantilla es el que seleccionó la llamada más reciente, en esta canalización, a EngineAdapterSetHashAlgorithm.
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.
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterIdentifyFeatureSet
//
// Purpose:
// Build a template from the current feature set and locate a matching
// template in the database.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation
// Identity - The GUID or SID of the template recovered from the
// database
// SubFactor - Sub-factor associated with the template in the
// database
// PayloadBlob - Payload data saved with the template
// PayloadBlobSize - Size, in bytes, of the buffer specified by the
// PayloadBlob parameter.
// HashValue - Hash value for the template
// HashSize - Size, in bytes, of the buffer specified by the
// HashValue parameter.
// RejectDetail - Receives additional information if a capture
// failure prevents the engine from performing a matching
// operation.
//
static HRESULT
WINAPI
EngineAdapterIdentifyFeatureSet(
__inout PWINBIO_PIPELINE Pipeline,
__out PWINBIO_IDENTITY Identity,
__out PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
__out PUCHAR *PayloadBlob,
__out PSIZE_T PayloadBlobSize,
__out PUCHAR *HashValue,
__out PSIZE_T HashSize,
__out PWINBIO_REJECT_DETAIL RejectDetail
)
{
HRESULT hr = S_OK;
SIZE_T recordCount = 0;
SIZE_T index = 0;
WINBIO_STORAGE_RECORD thisRecord;
BOOLEAN match = FALSE;
DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(Identity) ||
!ARGUMENT_PRESENT(SubFactor) ||
!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.
ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
Identity->Type = WINBIO_ID_TYPE_NULL;
*SubFactor = WINBIO_SUBTYPE_NO_INFORMATION;
*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;
}
// If your adapter supports index vectors to place templates into buckets,
// call a custom function (_AdapterCreateIndexVector) to create an index
// vector from the template data in the feature set. In this example, the
// engine adapter context attached to the pipeline contains a FeatureSet
// member.
hr = _AdapterCreateIndexVector(
context,
context->FeatureSet,
context->FeatureSetSize,
indexVector,
NUMBER_OF_TEMPLATE_BINS,
RejectDetail
);
if (FAILED(hr))
{
goto cleanup;
}
// Retrieve the records in the index vector. If your adapter does not support
// index vectors (the vector length is zero), calling the WbioStorageQueryByContent
// function will retrieve all records.
// WbioStorageQueryByContent is a wrapper function in the Winbio_adapter.h
// header file.
hr = WbioStorageQueryByContent(
Pipeline,
WINBIO_SUBTYPE_ANY,
indexVector,
NUMBER_OF_TEMPLATE_BINS
);
if (FAILED(hr))
{
goto cleanup;
}
// Determine the size of the result set. WbioStorageGetRecordCount is a wrapper
// function in the Winbio_adapter.h header file.
hr = WbioStorageGetRecordCount( Pipeline, &recordCount);
if (FAILED(hr))
{
goto cleanup;
}
// Point the result set cursor at the first record. WbioStorageFirstRecord
// is a wrapper function in the Winbio_adapter.h header file.
hr = WbioStorageFirstRecord( Pipeline );
if (FAILED(hr))
{
goto cleanup;
}
// Iterate through all records in the result set and determine which record
// matches the current feature set. WbioStorageGetCurrentRecord is a wrapper
// function in the Winbio_adapter.h header file.
for (index = 0; index < recordCount; ++index)
{
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 storage.
// 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) && hr != WINBIO_E_NO_MATCH)
{
goto cleanup;
}
if (match)
{
break;
}
hr = WbioStorageNextRecord( Pipeline );
if (FAILED(hr))
{
if (hr == WINBIO_E_DATABASE_NO_MORE_RECORDS)
{
hr = S_OK;
break;
}
else
{
goto cleanup;
}
}
}
if (match)
{
// 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;
}
// Return information about the matching template to the caller.
CopyMemory( Identity, thisRecord.Identity, sizeof(WINBIO_IDENTITY));
*SubFactor = thisRecord.SubFactor;
*PayloadBlob = thisRecord.PayloadBlob;
*PayloadBlobSize = thisRecord.PayloadBlobSize;
*HashValue = &context->HashBuffer;
*HashSize = context->HashSize;
}
else
{
hr = WINBIO_E_UNKNOWN_ID;
}
cleanup:
if (hr == WINBIO_E_DATABASE_NO_RESULTS)
{
hr = WINBIO_E_UNKNOWN_ID;
}
return hr;
}
Requisitos
| 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) |