PIBIO_SENSOR_ATTACH_FN fonction de rappel (winbio_adapter.h)

Article
03/03/2024

Appelé par l’infrastructure biométrique Windows lorsqu’un adaptateur de capteur 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_SENSOR_ATTACH_FN PibioSensorAttachFn;

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

Paramètres

[in, out] Pipeline

Pointeur vers la structure WINBIO_PIPELINE associée à l’unité biométrique effectuant 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 SensorContext de la structure WINBIO_PIPELINE pointée par l’argument Pipeline n’est pas NULL.

Remarques

Cette fonction est appelée avant l’initialisation du moteur et des adaptateurs de stockage pour l’unité biométrique. Par conséquent, cette fonction ne doit appeler aucune fonction référencée par le WINBIO_ENGINE_INTERFACE ou la structure WINBIO_STORAGE_INTERFACE pointée par les membres EngineInterface et StorageInterface de l’objet pipeline.

Étant donné que le membre SensorHandle de la structure WINBIO_PIPELINE contiendra un handle valide avant l’appel de cette méthode, votre implémentation de SensorAdapterAttach peut utiliser le handle pour accéder au périphérique de capteur si nécessaire.

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_SENSOR_CONTEXT privée sur le tas, initialisez-la et définissez son adresse dans le membre SensorContext 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 tout nettoyage requis avant de revenir.

Si le champ SensorContext n’a pas la valeur NULL lorsque cette fonction est appelée, le pipeline n’a pas été correctement réinitialisé par un appel antérieur à SensorAdapterDetach et vous devez retourner WINBIO_E_INVALID_DEVICE_STATE pour informer l’infrastructure biométrique Windows du problème.

Exemples

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterAttach
//
// 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
SensorAdapterAttach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;
    PWINBIO_SENSOR_CONTEXT newContext = NULL;

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

    // Validate the current sensor state.
    if (Pipeline->SensorContext != NULL)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Use a custom function (_AdapterAlloc) to allocate memory for the 
    // sensor adapter context.
    newContext = (PWINBIO_SENSOR_CONTEXT)_AdapterAlloc(sizeof(WINBIO_SENSOR_CONTEXT));
    if (newContext == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }

    // Create a manual reset event to monitor overlapped I/O.
    newContext->Overlapped.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
    if (newContext->Overlapped.hEvent == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }

    // Initialize any required context fields. This example assumes that your
    // sensor context points to a capture buffer and an attributes buffer.
    newContext->CaptureBuffer = NULL;
    newContext->CaptureBufferSize = 0;

    newContext->AttributesBuffer = NULL;
    newContext->AttributesBufferSize = sizeof (WINBIO_SENSOR_ATTRIBUTES);

    // Transfer ownership of the new sensor context structure to the 
    // pipeline.
    Pipeline->SensorContext = newContext;
    newContext = NULL;

cleanup:

    if (FAILED(hr) && newContext != NULL)
    {
        CloseHandle( newContext->Overlapped.hEvent;
        _AdapterRelease( newContext );
        newContext = NULL;
    }
    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)