PIBIO_ENGINE_ATTACH_FN fonction de rappel (winbio_adapter.h)

Article
08/27/2023

Appelé par l’infrastructure biométrique Windows lorsqu’un adaptateur moteur est ajouté au pipeline de traitement de l’unité biométrique. L’objectif de cette fonction est d’effectuer toute initialisation requise pour les opérations biométriques ultérieures.

Syntaxe

PIBIO_ENGINE_ATTACH_FN PibioEngineAttachFn;

HRESULT PibioEngineAttachFn(
  [in, out] PWINBIO_PIPELINE Pipeline
)
{...}

Paramètres

[in, out] Pipeline

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

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 pour indiquer l’erreur.

Code de retour	Description
E_POINTER	L’argument Pipeline ne peut pas être NULL.
E_OUTOFMEMORY	L’opération n’a pas pu être effectuée en raison d’une mémoire insuffisante.
WINBIO_E_INVALID_DEVICE_STATE	Le membre EngineContext de la structure WINBIO_PIPELINE pointée par l’argument Pipeline n’est pas NULL ou le membre EngineHandle n’est pas défini sur INVALID_HANDLE_VALUE.

Remarques

Cette fonction est appelée avant l’initialisation de l’adaptateur de stockage pour l’unité biométrique. Par conséquent, cette fonction ne doit pas appeler les fonctions référencées par la structure WINBIO_STORAGE_INTERFACE pointée par le membre StorageInterface de l’objet pipeline.

Lorsque vous implémentez cette fonction, vous devez allouer et gérer toutes les ressources requises par l’adaptateur et les attacher au pipeline d’unités biométriques. Pour ce faire, allouez une structure de WINBIO_ENGINE_CONTEXT privée sur le tas, initialisez-le et définissez son adresse dans le membre EngineContext de l’objet pipeline.

En cas d’erreur lors de la création et de l’initialisation des ressources d’adaptateur de moteur utilisées par cette fonction, vous devez effectuer le nettoyage requis avant de retourner.

Si le champ EngineContext n’est pas NULL lorsque cette fonction est appelée, le pipeline n’a pas été correctement initialisé et vous devez retourner WINBIO_E_INVALID_DEVICE_STATE pour informer l’infrastructure biométrique Windows du problème.

De même, si le champ EngineHandle ne contient pas de INVALID_HANDLE_VALUE lorsque cette fonction est appelée, vous devez retourner WINBIO_E_INVALID_DEVICE_STATE.

Exemples

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAttach
//
// Purpose:
//      Performs any initialization required for later biometric operations.
//
// Parameters:
//      Pipeline -  Pointer to a WINBIO_PIPELINE structure associated with 
//                  the biometric unit performing the operation.
//
static HRESULT
WINAPI
EngineAdapterAttach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;

    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_ENGINE_CONTEXT newContext = NULL;

    // Call a custom function (_AdapterAlloc) to allocate memory to hold the 
    // engine adapter context.
    newContext = (PWINBIO_ENGINE_CONTEXT)_AdapterAlloc(sizeof(WINBIO_ENGINE_CONTEXT));
    if (newContext == NULL)
    {
        E_OUTOFMEMORY;
        goto cleanup;
    }

    // Clear the context memory.
    ZeroMemory(newContext, sizeof(WINBIO_ENGINE_CONTEXT));

    // Initialize any required context fields.
    newContext->SomeField = SomeSpecialValue;

    newContext->SomePointerField = _AdapterAlloc(sizeof(SOME_STRUCTURE));
    if (newContext->SomePointerField == NULL)
    {
        E_OUTOFMEMORY;
        goto cleanup;
    }

    // If your adapter supports software-based template hashing, implement the 
    // following custom function to open a SHA1 hash object handle and store 
    // the handle in the adapter context. Use Cryptography Next Generation (CNG) 
    // functions to create the SHA1 hash object.
    hr = _AdapterInitializeCrypto(newContext);
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // If initialization completes successfully, attach the engine context to the 
    // processing pipeline of the biometric unit.
    Pipeline->EngineContext = newContext;
    newContext = NULL;

cleanup:
    if (FAILED(hr))
    {
        // If a new context has been created, release any memory 
        // pointed to by various data members in the context and 
        // then release the context. The following example assumes 
        // that your adapter contains a handle
        // for a hash object and a pointer to another object.
        if (newContext != NULL)
        {
            // Close any open CNG handles and release the hash object memory.
            _AdapterCleanupCrypto(newContext);

            // Release any other object pointed to by the context.
            if (newContext->SomePointerField != NULL)
            {
                _AdapterRelease(newContext->SomePointerField);
            }

            // Release the context
            _AdapterRelease(newContext);
        }
    }
    return hr;

}

Configuration requise


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)