PIBIO_ENGINE_COMMIT_ENROLLMENT_FN funzione di callback (winbio_adapter.h)

Articolo
03/13/2024

Chiamato da Windows Biometric Framework per finalizzare l'oggetto di registrazione, convertirlo in un modello e salvare il modello nel database.

Sintassi

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

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 il GUID o IL SID del modello da archiviare nel database.

[in] SubFactor

Valore WINBIO_BIOMETRIC_SUBTYPE che specifica il sotto-fattore associato al modello da archiviare nel database.

[in, optional] PayloadBlob

Puntatore facoltativo a una matrice di byte che contengono una firma di verifica generata da Windows Biometric Framework.

[in] PayloadBlobSize

Dimensione, in byte, della matrice di caratteri a cui punta il parametro PayloadBlob . Questo valore deve essere zero se il parametro PayloadBlob è NULL.

Valore restituito

Se la funzione ha esito positivo, restituisce S_OK. Se la funzione ha esito negativo, deve restituire uno dei valori HRESULT seguenti o qualsiasi valore restituito dall'adattatore di archiviazione.

Codice restituito	Descrizione
E_POINTER	Un argomento puntatore obbligatorio è NULL.
E_INVALIDARG	Il valore specificato dal parametro Identity o dal parametro SubFactor non è valido.
WINBIO_E_DUPLICATE_ENROLLMENT	Il modello specificato dai parametri Identity e SubFactor è già salvato nel database.
WINBIO_E_INVALID_DEVICE_STATE	Alla pipeline non è associato alcun modello.

Commenti

Se questa funzione ha esito positivo, deve scaricare il modello di registrazione dalla pipeline. Il risultato di questa azione deve essere equivalente alla chiamata a EngineAdapterClearContext.

Se questa funzione ha esito negativo, non deve modificare lo stato del contesto del motore. In particolare, se è presente un modello completato collegato alla pipeline, dovrebbe essere possibile chiamare nuovamente questa funzione (dopo aver risolto eventuali errori) per eseguire il commit del modello nel database.

Gli adattatori del motore che supportano l'autenticazione di preavvio devono eseguire il commit della registrazione non solo nell'adattatore di archiviazione collegato alla pipeline, ma anche nell'area di archiviazione di preavvio. I dettagli su come eseguire questa operazione vengono lasciati al fornitore.

Importante

Non tentare di convalidare il valore fornito per il parametro SubFactor . Il servizio Windows Biometrics convaliderà il valore fornito prima di passarlo all'implementazione. Se il valore è WINBIO_SUBTYPE_NO_INFORMATION o WINBIO_SUBTYPE_ANY, convalidare la posizione appropriata.

Esempio

Lo pseudocodice seguente mostra una possibile implementazione di questa funzione. L'esempio non viene compilato. Devi adattarla al tuo scopo.

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

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)

Vedi anche

EngineAdapterClearContext

Funzioni plug-in

Condividi tramite