PIBIO_ENGINE_COMMIT_ENROLLMENT_FN fonction de rappel (winbio_adapter.h)

Article
03/06/2024

Appelé par l’infrastructure biométrique Windows pour finaliser l’objet d’inscription, le convertir en modèle et enregistrer le modèle dans la base de données.

Syntaxe

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

Paramètres

[in, out] Pipeline

Pointeur vers une structure WINBIO_PIPELINE associée à l’unité biométrique qui effectue l’opération.

[in] Identity

Pointeur vers une structure WINBIO_IDENTITY qui contient le GUID ou le SID du modèle à stocker dans la base de données.

[in] SubFactor

Valeur WINBIO_BIOMETRIC_SUBTYPE qui spécifie le sous-facteur associé au modèle à stocker dans la base de données.

[in, optional] PayloadBlob

Pointeur facultatif vers un tableau d’octets contenant une signature de vérification générée par l’infrastructure biométrique Windows.

[in] PayloadBlobSize

Taille, en octets, du tableau de caractères pointé vers le paramètre PayloadBlob . Cette valeur doit être égale à zéro si le paramètre PayloadBlob a la valeur NULL.

Valeur retournée

Si la fonction réussit, elle retourne S_OK. Si la fonction échoue, elle doit retourner l’une des valeurs HRESULT suivantes ou toute valeur retournée par l’adaptateur de stockage.

Code de retour	Description
E_POINTER	Un argument de pointeur obligatoire est NULL.
E_INVALIDARG	La valeur spécifiée par le paramètre Identity ou le paramètre SubFactor n’est pas valide.
WINBIO_E_DUPLICATE_ENROLLMENT	Le modèle spécifié par les paramètres Identity et SubFactor est déjà enregistré dans la base de données.
WINBIO_E_INVALID_DEVICE_STATE	Aucun modèle n’est attaché au pipeline.

Remarques

Si cette fonction réussit, elle doit vider le modèle d’inscription du pipeline. Le résultat de cette action doit être équivalent à l’appel de EngineAdapterClearContext.

Si cette fonction échoue, elle ne doit pas modifier l’état du contexte du moteur. En particulier, si un modèle terminé est attaché au pipeline, il doit être possible d’appeler à nouveau cette fonction (une fois que les raisons de l’échec ont été résolus) pour valider le modèle dans la base de données.

Les adaptateurs moteur qui prennent en charge l’authentification avant le démarrage doivent valider l’inscription non seulement sur l’adaptateur de stockage attaché au pipeline, mais également sur la zone de stockage de prédémarreur. Les détails de la façon dont cela doit être effectué sont laissés au fournisseur.

Important

N’essayez pas de valider la valeur fournie pour le paramètre SubFactor . Le service de biométrie Windows valide la valeur fournie avant de la transmettre à votre implémentation. Si la valeur est WINBIO_SUBTYPE_NO_INFORMATION ou WINBIO_SUBTYPE_ANY, validez le cas échéant.

Exemples

Le pseudocode suivant montre une implémentation possible de cette fonction. L’exemple ne se compile pas. Vous devez l’adapter à votre objectif.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbio_adapter.h (include Winbio_adapter.h)

Voir aussi

EngineAdapterClearContext

Fonctions de plug-in

Partager via