PIBIO_ENGINE_VERIFY_FEATURE_SET_FN funzione di callback (winbio_adapter.h)
Chiamato da Windows Biometric Framework per confrontare il modello nel set di funzionalità corrente con un modello specifico nel database. Se i modelli sono equivalenti, l'adapter del motore deve impostare il valore booleano a cui punta il parametro Match su TRUE, restituire il modello corrispondente nel parametro PayloadBlob e restituire un hash del modello nel parametro HashValue .
Sintassi
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
)
{...}
Parametri
[in, out] Pipeline
Puntatore a una struttura WINBIO_PIPELINE associata all'unità biometrica che esegue l'operazione.
[in] Identity
Puntatore a una struttura WINBIO_IDENTITY che contiene un GUID o UN SID che corrisponde a quello del modello recuperato dal database.
[in] SubFactor
Valore WINBIO_BIOMETRIC_SUBTYPE previsto corrispondente a quello del modello recuperato dal database. Per altre informazioni, vedere le sezione Osservazioni.
[out] Match
Puntatore a un valore booleano che specifica se i parametri Identity e SubFactor corrispondono a quelli del modello ripristinati dal database. TRUE specifica che questi valori corrispondono.
[out] PayloadBlob
Indirizzo di una variabile che riceve un puntatore ai dati del payload salvati con il modello. Se non sono presenti dati del payload, impostare questo valore su NULL.
[out] PayloadBlobSize
Puntatore a un valore che riceve le dimensioni, in byte, del buffer specificato nel parametro PayloadBlob . Se non sono presenti dati di payload archiviati con il modello, impostare questo valore su zero.
[out] HashValue
Indirizzo di una variabile che riceve un puntatore all'hash del modello. Se l'adattatore del motore non supporta la generazione di hash, impostare questo valore su NULL.
[out] HashSize
Puntatore a un valore contenente le dimensioni, in byte, dell'hash specificato dal parametro HashValue . Se l'adattatore del motore non supporta la generazione hash, impostare questo valore su zero.
[out] RejectDetail
Puntatore a un valore WINBIO_REJECT_DETAIL che riceve informazioni aggiuntive se un errore di acquisizione impedisce al motore di eseguire un'operazione di corrispondenza. Se l'acquisizione più recente ha avuto esito positivo, impostare questo parametro su zero. I valori seguenti sono definiti per l'acquisizione delle impronte digitali
- 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
Valore restituito
Se la funzione ha esito positivo, restituisce S_OK. Se la funzione ha esito negativo, deve restituire uno dei valori HRESULT seguenti per indicare l'errore.
| Codice restituito | Descrizione |
|---|---|
|
Un parametro del puntatore obbligatorio è NULL. |
|
Il valore specificato nel parametro SubFactor non è corretto. |
|
Il set di funzionalità non soddisfa i requisiti interni dell'adattatore del motore per un'operazione di verifica. Ulteriori informazioni sull'errore vengono specificate dal parametro RejectDetail . |
|
La funzionalità impostata nella pipeline corrisponde a una archiviata nel database, ma non corrisponde alla combinazione di valori passati nei parametri Identity e SubFactor . |
Commenti
Il parametro SubFactor specifica il sotto-fattore associato al modello biometrico. Windows Biometric Framework supporta solo l'acquisizione delle impronte digitali e può usare le costanti seguenti per rappresentare le informazioni sul sottotipo.
- 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
Non tentare di convalidare il valore fornito per il parametro SubFactor . Il servizio Windows Biometrics convalida il valore fornito prima di passarlo all'implementazione. Se il valore è WINBIO_SUBTYPE_NO_INFORMATION o WINBIO_SUBTYPE_ANY, convalidare se appropriato.
Il valore hash restituito da questa funzione, se presente, è l'hash del modello di registrazione trovato nel database, non il modello corrispondente collegato alla pipeline.
I buffer PayloadBlob e HashValue sono di proprietà e gestiti dall'adattatore del motore dopo che la funzione EngineAdapterIdentifyFeatureSet restituisce correttamente. L'adattatore del motore deve mantenere l'indirizzo del buffer valido, per questa pipeline, fino alla chiamata successiva a EngineAdapterClearContext.
Esempio
Lo pseudocode seguente mostra una possibile implementazione di questa funzione. L'esempio non viene compilato. Devi adattarla per adattarti al tuo scopo.
//////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 7 [solo app desktop] |
| Server minimo supportato | Windows Server 2008 R2 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winbio_adapter.h (includere Winbio_adapter.h) |