PIBIO_ENGINE_VERIFY_FEATURE_SET_FN Rückruffunktion (winbio_adapter.h)

Wird vom Windows Biometrischen Framework aufgerufen, um die Vorlage im aktuellen Featuresatz mit einer bestimmten Vorlage in der Datenbank zu vergleichen. Wenn die Vorlagen gleichwertig sind, muss der Moduladapter den booleschen Wert festlegen, auf den der Parameter "Match " verweist, die übereinstimmende Vorlage im PayloadBlob-Parameter zurückgeben und einen Hash der Vorlage im HashValue-Parameter zurückgeben.

Syntax

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
)
{...}

Die Parameter

[in, out] Pipeline

Zeigen Sie auf eine WINBIO_PIPELINE Struktur, die der biometrischen Einheit zugeordnet ist, die den Vorgang ausführt.

[in] Identity

Zeigen Sie auf eine WINBIO_IDENTITY-Struktur , die eine GUID oder SID enthält, die mit der der Vorlage übereinstimmt, die aus der Datenbank wiederhergestellt wurde.

[in] SubFactor

Ein WINBIO_BIOMETRIC_SUBTYPE Wert, der mit dem wert der Vorlage übereinstimmt, die aus der Datenbank wiederhergestellt wurde. Weitere Informationen finden Sie im Abschnitt "Hinweise".

[out] Match

Zeigen Sie auf einen booleschen Wert, der angibt, ob die Parameter "Identity " und "SubFactor " mit denen der Vorlage übereinstimmen, die aus der Datenbank wiederhergestellt wurde. TRUE gibt an, dass diese Werte übereinstimmen.

[out] PayloadBlob

Adresse einer Variablen, die einen Zeiger auf die Nutzlastdaten empfängt, die mit der Vorlage gespeichert sind. Wenn keine Nutzlastdaten vorhanden sind, legen Sie diesen Wert auf NULL fest.

[out] PayloadBlobSize

Zeigen Sie auf einen Wert, der die Größe des im PayloadBlob-Parameter angegebenen Puffers in Bytes empfängt. Wenn keine Nutzlastdaten mit der Vorlage gespeichert sind, legen Sie diesen Wert auf Null fest.

[out] HashValue

Adresse einer Variablen, die einen Zeiger auf den Hash der Vorlage empfängt. Wenn der Moduladapter die Hashgenerierung nicht unterstützt, legen Sie diesen Wert auf NULL fest.

[out] HashSize

Zeigen Sie auf einen Wert, der die Größe des vom HashValue-Parameter angegebenen Hashs in Bytes enthält. Wenn der Moduladapter die Hashgenerierung nicht unterstützt, legen Sie diesen Wert auf Null fest.

[out] RejectDetail

Zeiger auf einen WINBIO_REJECT_DETAIL Wert, der zusätzliche Informationen empfängt, wenn ein Erfassungsfehler verhindert, dass das Modul einen Abgleichsvorgang ausführt. Wenn die neueste Erfassung erfolgreich war, legen Sie diesen Parameter auf Null fest. Die folgenden Werte sind für die Fingerabdruckerfassung definiert.

• 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

Rückgabewert

Wenn die Funktion erfolgreich ist, wird S_OK zurückgegeben. Wenn die Funktion fehlschlägt, muss sie einen der folgenden HRESULT-Werte zurückgeben, um den Fehler anzugeben.

Bemerkungen

Der Parameter SubFactor gibt den Teilfaktor an, der der biometrischen Vorlage zugeordnet ist. Das Windows Biometrie-Framework unterstützt nur die Fingerabdruckerfassung und kann die folgenden Konstanten verwenden, um Untertypinformationen darzustellen.

• 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

Der von dieser Funktion zurückgegebene Hashwert ist ggf. der Hash der Registrierungsvorlage, die in der Datenbank gefunden wurde, nicht die der Pipeline zugeordnete übereinstimmende Vorlage.

Die PayloadBlob - und HashValue-Puffer sind eigentum und werden vom Moduladapter verwaltet, nachdem die EngineAdapterIdentifyFeatureSet-Funktion erfolgreich zurückgegeben wurde. Der Moduladapter muss die Pufferadresse für diese Pipeline bis zum nächsten Aufruf von EngineAdapterClearContext gültig halten.

Examples

Der folgende Pseudocode zeigt eine mögliche Implementierung dieser Funktion. Das Beispiel wird nicht kompiliert. Sie müssen sie an Ihren Zweck anpassen.

//////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}

Anforderungen

Siehe auch

EngineAdapterIdentifyFeatureSet

Plug-In-Funktionen