PIBIO_ENGINE_GET_ENROLLMENT_HASH_FN Rückruffunktion (winbio_adapter.h)

Artikel
08/27/2023

Wird vom Windows Biometric Framework aufgerufen, um den Hash der abgeschlossenen Registrierungsvorlage in der Pipeline abzurufen.

Syntax

PIBIO_ENGINE_GET_ENROLLMENT_HASH_FN PibioEngineGetEnrollmentHashFn;

HRESULT PibioEngineGetEnrollmentHashFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [out]     PUCHAR *HashValue,
  [out]     PSIZE_T HashSize
)
{...}

Parameter

[in, out] Pipeline

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

[out] HashValue

Adresse der Variablen, die einen Zeiger auf ein Bytearray empfängt, das den Hash der Vorlage enthält.

[out] HashSize

Ein Zeiger auf eine Variable, die die Größe des Hashs in Bytes empfängt, auf den der HashValue-Parameter verweist.

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.

Rückgabecode	Beschreibung
E_POINTER	Ein obligatorischer Zeigerparameter ist NULL.
E_NOTIMPL	Der Engine-Adapter unterstützt keine Vorlagenhashgenerierung.
WINBIO_E_INVALID_DEVICE_STATE	Die Pipeline enthält keine abgeschlossene Registrierungsvorlage.

Hinweise

Die von dieser Funktion als Hash versehene Vorlage muss die abgeschlossene Registrierungsvorlage sein, die in der Datenbank gespeichert wird, wenn EngineAdapterCommitEnrollment aufgerufen wird. Sie dürfen keinen Hash für eines der zwischengespeicherten Stichproben erstellen.

Der Algorithmus, der zum Generieren des Vorlagenhashs verwendet wird, ist der Algorithmus, der beim letzten Aufruf von EngineAdapterSetHashAlgorithm in dieser Pipeline ausgewählt wurde.

Der Speicher, der den Hash enthält, wird vom Engine-Adapter verwaltet, nachdem die EngineAdapterGetEnrollmentHash-Funktion erfolgreich zurückgegeben wurde. Der Moduladapter muss die Pufferadresse gültig lassen, bis das Framework eine der folgenden Funktionen aufruft:

Der Engine-Adapter muss auch einen separaten Hashpuffer für jede Pipeline verwalten.

Beispiele

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterGetEnrollmentHash
//
// Purpose:
//      Retrieves the hash of the completed enrollment template in the pipeline.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      HashValue       - Contains the hash of the template
//      HashSize        - Size, in bytes, of the hash pointed to by the 
//                        HashValue parameter
//
static HRESULT
WINAPI
EngineAdapterGetEnrollmentHash(
    __inout PWINBIO_PIPELINE Pipeline,
    __out PUCHAR *HashValue,
    __out PSIZE_T HashSize
    )
{
    ////////////////////////////////////////////////////////////////////////////
    // Return E_NOTIMPL here if your adapter does not support template hashing.
    ////////////////////////////////////////////////////////////////////////////

    HRESULT hr = S_OK;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(HashValue) ||
        !ARGUMENT_PRESENT(HashSize))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_ENGINE_CONTEXT context = 
           (PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

    // Return if an enrollment is not in progress. This example assumes that 
    // an enrollment object is part of your engine context structure.
    if (context->Enrollment.InProgress != TRUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Initialize the hash.
    *HashValue = NULL;
    *HashSize = 0;

    // If your engine adapter supports template hashing, call a custom function
    // (_AdapterGenerateHashForTemplate) to calculate the hash of the new
    // enrollment template. The hash value should be saved in the adapter
    // context.
    hr = _AdapterGenerateHashForTemplate(
                context,
                context->Enrollment.Template, 
                context->Enrollment.TemplateSize,
                context->HashBuffer,
                &context->HashSize
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Return the hash to the caller.
    *HashValue = context->HashBuffer;
    *HashSize = context->HashSize;

cleanup:

    return hr;
}

Anforderungen


Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbio_adapter.h (Winbio_adapter.h einschließen)

Weitere Informationen

Plug-In-Funktionen

Freigeben über