PIBIO_ENGINE_COMMIT_ENROLLMENT_FN Rückruffunktion (winbio_adapter.h)

  • Artikel

Wird vom Windows Biometric Framework aufgerufen, um das Registrierungsobjekt abzuschließen, es in eine Vorlage zu konvertieren und die Vorlage in der Datenbank zu speichern.

Syntax

PIBIO_ENGINE_COMMIT_ENROLLMENT_FN PibioEngineCommitEnrollmentFn;

HRESULT PibioEngineCommitEnrollmentFn(
  [in, out]      PWINBIO_PIPELINE Pipeline,
  [in]           PWINBIO_IDENTITY Identity,
  [in]           WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [in, optional] PUCHAR PayloadBlob,
  [in]           SIZE_T PayloadBlobSize
)
{...}

Parameter

[in, out] Pipeline

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

[in] Identity

Zeiger auf eine WINBIO_IDENTITY Struktur, die die GUID oder SID der Vorlage enthält, die in der Datenbank gespeichert werden soll.

[in] SubFactor

Ein WINBIO_BIOMETRIC_SUBTYPE Wert, der den Teilfaktor angibt, der der Vorlage zugeordnet ist, die in der Datenbank gespeichert werden soll.

[in, optional] PayloadBlob

Ein optionaler Zeiger auf ein Bytearray, das eine vom Windows Biometric Framework generierte Überprüfungssignatur enthält.

[in] PayloadBlobSize

Die Größe des Zeichenarrays in Bytes, auf das der PayloadBlob-Parameter verweist. Dieser Wert muss null sein, wenn der PayloadBlob-ParameterNULL ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird S_OK zurückgegeben. Wenn die Funktion fehlschlägt, muss sie einen der folgenden HRESULT-Werte oder einen vom Speicheradapter zurückgegebenen Wert zurückgeben.

Rückgabecode Beschreibung
E_POINTER
 Ein obligatorisches Zeigerargument ist NULL.
E_INVALIDARG
 Der durch den Identity-Parameter oder den SubFactor-Parameter angegebene Wert ist ungültig.
WINBIO_E_DUPLICATE_ENROLLMENT
 Die durch die Parameter Identity und SubFactor angegebene Vorlage ist bereits in der Datenbank gespeichert.
WINBIO_E_INVALID_DEVICE_STATE
 An die Pipeline ist keine Vorlage angefügt.

Hinweise

Wenn diese Funktion erfolgreich ist, sollte die Registrierungsvorlage aus der Pipeline geleert werden. Das Ergebnis dieser Aktion sollte dem Aufrufen von EngineAdapterClearContext entsprechen.

Wenn diese Funktion fehlschlägt, sollte sie den Status des Engine-Kontexts nicht ändern. Insbesondere wenn eine abgeschlossene Vorlage an die Pipeline angefügt ist, sollte es möglich sein, diese Funktion erneut aufzurufen (nachdem die Fehlerursachen behoben wurden), um die Vorlage in die Datenbank zu committen.

Moduladapter, die die Vorabstartauthentifizierung unterstützen, müssen die Registrierung nicht nur an den Speicheradapter committen, der an die Pipeline angefügt ist, sondern auch in den Vorabstartspeicherbereich. Die Details dazu, wie dies erreicht werden soll, bleiben dem Anbieter überlassen.

Wichtig  

Versuchen Sie nicht, den für den SubFactor-Parameter angegebenen Wert zu überprüfen. Der Windows-Biometriedienst überprüft den angegebenen Wert, bevor er an Ihre Implementierung übergeben wird. Wenn der Wert WINBIO_SUBTYPE_NO_INFORMATION oder WINBIO_SUBTYPE_ANY ist, überprüfen Sie ggf..

 

Beispiele

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterCommitEnrollment
//
// Purpose:
//      Finalizes the enrollment object, converts it to a template, and saves 
//      the template in the database.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Identity        - GUID or SID of the template to be stored in the 
//                        database
//      SubFactor       - Sub-factor associated with the template to be stored
//                        in the database
//      PayloadBlob     - Optional pointer to an array of bytes that contain a 
//                        verification signature generated by the Windows Biometric
//                        Framework
//      PayloadBlobSize - Size, in bytes, of the character array pointed to by 
//                        the PayloadBlob parameter
//

static HRESULT
WINAPI
EngineAdapterCommitEnrollment(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in PUCHAR PayloadBlob,
    __in SIZE_T PayloadBlobSize
    )
{
    HRESULT hr = S_OK;
    DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_STORAGE_RECORD newTemplate = {0};

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

    if (ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }
    
    if (!ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize > 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // TODO: Verify that the SubFactor and Identity arguments are valid.

    // Retrieve the context from the pipeline.
    PWINIBIO_ENGINE_CONTEXT context = 
        (PWINIBIO_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;
    }

    // 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 enrollment object.
    hr = _AdapterCreateIndexVector(
                context, 
                context->Enrollment.Template, 
                context->Enrollment.TemplateSize,
                indexVector, 
                NUMBER_OF_TEMPLATE_BINS, 
                &rejectDetail
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    newTemplate.Identity = Identity;
    newTemplate.SubFactor = SubFactor;
    newTemplate.IndexVector = indexVector;
    newTemplate.IndexElementCount = NUMBER_OF_TEMPLATE_BINS;
    newTemplate.TemplateBlob = context->Enrollment.Template;
    newTemplate.TemplateBlobSize = context->Enrollment.TemplateSize;
    newTemplate.PayloadBlob = PayloadBlob;
    newTemplate.PayloadBlobSize = PayloadBlobSize;

    hr = WbioStorageAddRecord(
                Pipeline,
                &newTemplate
                );

    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Call a custom function (_AdapterDestroyEnrollmentTemplate) to release
    // any resources held by the enrollment object.
    _AdapterDestroyEnrollmentTemplate(
        context,
        &context->Enrollment
        );

    // Specify that the enrollment process has been completed.
    context->Enrollment.InProgress = FALSE;

cleanup:

    return hr;
}

Anforderungen

Anforderung Wert
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

EngineAdapterClearContext

Plug-In-Funktionen