PIBIO_ENGINE_EXPORT_ENGINE_DATA_FN fonction de rappel (winbio_adapter.h)

Article
03/03/2024

Appelé par l’infrastructure biométrique Windows pour récupérer une copie de l’ensemble de fonctionnalités ou du modèle le plus récemment traité à partir du moteur mis en forme en tant que structure de WINBIO_BIR standard.

Syntaxe

PIBIO_ENGINE_EXPORT_ENGINE_DATA_FN PibioEngineExportEngineDataFn;

HRESULT PibioEngineExportEngineDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      WINBIO_BIR_DATA_FLAGS Flags,
  [out]     PWINBIO_BIR *SampleBuffer,
  [out]     PSIZE_T SampleSize
)
{...}

Paramètres

[in, out] Pipeline

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

[in] Flags

Valeur qui spécifie les propriétés de la structure WINBIO_BIR retournée par le moteur. Il peut s’agir d’un OR au niveau du bit des indicateurs de niveau de sécurité et de traitement suivants :

WINBIO_DATA_FLAG_PRIVACY

Les données sont chiffrées.

WINBIO_DATA_FLAG_INTEGRITY Les données sont signées numériquement ou protégées par un code d’authentification de message (MAC).
WINBIO_DATA_FLAG_SIGNED Si cet indicateur et l’indicateur WINBIO_DATA_FLAG_INTEGRITY sont définis, les données sont signées. Si cet indicateur n’est pas défini, mais que l’indicateur WINBIO_DATA_FLAG_INTEGRITY est défini, un MAC est calculé.
WINBIO_DATA_FLAG_RAW Les données sont dans le format avec lequel elles ont été capturées.
WINBIO_DATA_FLAG_INTERMEDIATE Les données ne sont pas brutes, mais n’ont pas été complètement traitées.
WINBIO_DATA_FLAG_PROCESSED Les données ont été traitées.

[out] SampleBuffer

Adresse d’une variable qui reçoit un pointeur vers une structure WINBIO_BIR qui contient l’ensemble de fonctionnalités ou le modèle.

[out] SampleSize

Pointeur vers une variable qui contient la taille, en octets, de la structure WINBIO_BIR retournée dans le paramètre SampleBuffer .

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_INVALIDARG	L’adaptateur moteur ne prend pas en charge la combinaison d’indicateurs spécifiée par le paramètre Flags .
E_OUTOFMEMORY	La mémoire disponible est insuffisante pour créer la structure WINBIO_BIR .
E_POINTER	Un paramètre de pointeur obligatoire est NULL.
WINBIO_E_INVALID_DEVICE_STATE	Le pipeline ne contient pas le type de données requis par le paramètre Flags .
E_NOTIMPL	Cette méthode n'est pas implémentée à l'heure actuelle.

Remarques

Vous devez allouer la mémoire tampon à retourner dans le paramètre SampleBuffer à partir du tas de processus à l’aide de la fonction HeapAlloc . Une fois la mémoire tampon créée, elle devient la propriété de l’infrastructure biométrique Windows. Étant donné que l’infrastructure libère cette mémoire quand elle a fini de l’utiliser, votre implémentation de cette fonction ne doit pas tenter de libérer la mémoire tampon ou d’enregistrer un pointeur vers celle-ci. En n’enregistrant pas le pointeur, vous empêchez d’autres parties de l’adaptateur moteur d’essayer d’utiliser la mémoire tampon après le retour de cette fonction.

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.

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterExportEngineData
//
// Purpose:
//      Retrieves a copy of the most recently processed feature set or template.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Flags           - Security and processing level flags
//      SampleBuffer    - Contains the feature set or template
//      SampleSize      - Size, in bytes, of the structure returned in the 
//                        SampleBuffer parameter.
//
static HRESULT
WINAPI
EngineAdapterExportEngineData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in WINBIO_BIR_DATA_FLAGS Flags,
    __out PWINBIO_BIR *SampleBuffer,
    __out PSIZE_T SampleSize
    )
{
    HRESULT hr = S_OK;
    PWINBIO_BIR birAddress = NULL;
    SIZE_T birSize = 0;

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

    // Retrieve the context from the pipeline.
    PWINBIO_ENGINE_CONTEXT context = 
           (PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

    // At least one processing level flag must be set. Your adapter can also
    // place additional restrictions on supported export formats.
    if (Flags & (WINBIO_DATA_FLAG_RAW | 
                 WINBIO_DATA_FLAG_INTERMEDIATE | 
                 WINBIO_DATA_FLAG_PROCESSED) == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // You must implement the _CreateBirFromAdapterData function to extract
    // data from the engine context and create a new WINBIO_BIR structure. The
    // function passes ownership of the new biometric information record (BIR)
    // to the EngineAdapterExportEngineData routine which then passes the BIR
    // to the caller.
    hr = _CreateBirFromAdapterData( context, Flags, &birAddress, &birSize);
    if (SUCCEEDED(hr))
    {
        *SampleBuffer = birAddress;
        *SampleSize = birSize;
    }

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

EngineAdapterAcceptSampleData

Fonctions de plug-in

Partager via