PIBIO_ENGINE_EXPORT_ENGINE_DATA_FN funzione di callback (winbio_adapter.h)

Articolo
03/13/2024

Chiamato da Windows Biometric Framework per recuperare una copia del set di funzionalità o del modello elaborato più di recente dal motore formattato come struttura di WINBIO_BIR standard.

Sintassi

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

Parametri

[in, out] Pipeline

Puntatore a una struttura WINBIO_PIPELINE associata all'unità biometrica che esegue l'operazione.

[in] Flags

Valore che specifica le proprietà della struttura WINBIO_BIR restituita dal motore. Può trattarsi di un OR bit per bit dei flag di livello di sicurezza ed elaborazione seguenti:

WINBIO_DATA_FLAG_PRIVACY

I dati sono crittografati.

WINBIO_DATA_FLAG_INTEGRITY I dati sono firmati digitalmente o protetti da un codice mac (Message Authentication Code).
WINBIO_DATA_FLAG_SIGNED Se questo flag e il flag WINBIO_DATA_FLAG_INTEGRITY sono impostati, i dati vengono firmati. Se questo flag non è impostato, ma viene impostato il flag WINBIO_DATA_FLAG_INTEGRITY , viene calcolato un MAC.
WINBIO_DATA_FLAG_RAW I dati sono nel formato con cui è stato acquisito.
WINBIO_DATA_FLAG_INTERMEDIATE I dati non sono elaborati ma non sono stati completamente elaborati.
WINBIO_DATA_FLAG_PROCESSED I dati sono stati elaborati.

[out] SampleBuffer

Indirizzo di una variabile che riceve un puntatore a una struttura WINBIO_BIR che contiene il set di funzionalità o il modello.

[out] SampleSize

Puntatore a una variabile che contiene le dimensioni, in byte, della struttura WINBIO_BIR restituita nel parametro SampleBuffer .

Valore restituito

Se la funzione ha esito positivo, restituisce S_OK. Se la funzione ha esito negativo, deve restituire uno dei valori HRESULT seguenti per indicare l'errore.

Codice restituito	Descrizione
E_INVALIDARG	L'adattatore del motore non supporta la combinazione di flag specificati dal parametro Flags .
E_OUTOFMEMORY	Memoria insufficiente per creare la struttura WINBIO_BIR .
E_POINTER	Un parametro puntatore obbligatorio è NULL.
WINBIO_E_INVALID_DEVICE_STATE	La pipeline non contiene il tipo di dati richiesto dal parametro Flags .
E_NOTIMPL	Non è attualmente implementato.

Commenti

È necessario allocare il buffer da restituire nel parametro SampleBuffer dall'heap del processo usando la funzione HeapAlloc . Dopo aver creato il buffer, diventa la proprietà di Windows Biometric Framework. Poiché framework dealloca questa memoria al termine dell'uso, l'implementazione di questa funzione non deve tentare di deallocare il buffer o salvare un puntatore. Non salvando il puntatore, si impedisce ad altre parti dell'adattatore del motore di tentare di usare il buffer dopo la restituzione di questa funzione.

Esempio

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

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

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

EngineAdapterAcceptSampleData

Funzioni plug-in

Condividi tramite