PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN funzione di callback (winbio_adapter.h)

Chiamata dalla funzione SensorAdapterPushDataToEngine implementata dall'adattatore del sensore per notificare all'adattatore motore di accettare un campione biometrico non elaborato ed estrarre un set di funzionalità. Il set di funzionalità può essere usato per la corrispondenza o la registrazione.

Sintassi

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN PibioEngineAcceptSampleDataFn;

HRESULT PibioEngineAcceptSampleDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_BIR SampleBuffer,
  [in]      SIZE_T SampleSize,
  [in]      WINBIO_BIR_PURPOSE Purpose,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

Parametri

[in, out] Pipeline

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

[in] SampleBuffer

Puntatore a una struttura WINBIO_BIR che contiene l'esempio biometrico da elaborare.

[in] SampleSize

Valore SIZE_T contenente le dimensioni della struttura WINBIO_BIR restituita nel parametro SampleBuffer .

[in] Purpose

Maschera WINBIO_BIR_PURPOSE bit che specifica l'uso previsto dell'esempio. La struttura WINBIO_BIR_PURPOSE specifica lo scopo per cui acquisire i dati da usare e , di conseguenza, come deve essere ottimizzato. Questo può essere un OR bit per bit dei valori seguenti:

• WINBIO_PURPOSE_VERIFY
• WINBIO_PURPOSE_IDENTIFY
• WINBIO_PURPOSE_ENROLL
• WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
• WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[out] RejectDetail

Puntatore a un valore WINBIO_REJECT_DETAIL che riceve informazioni aggiuntive sull'errore di elaborare un campione biometrico. Se l'operazione ha avuto esito positivo, questo parametro è impostato su zero. I valori seguenti sono definiti per gli esempi di impronta digitale:

• WINBIO_FP_TOO_HIGH
• WINBIO_FP_TOO_LOW
• WINBIO_FP_TOO_LEFT
• WINBIO_FP_TOO_RIGHT
• WINBIO_FP_TOO_FAST
• WINBIO_FP_TOO_SLOW
• WINBIO_FP_POOR_QUALITY
• WINBIO_FP_TOO_SKEWED
• WINBIO_FP_TOO_SHORT
• WINBIO_FP_MERGE_FAILURE

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.

Commenti

Il set di funzionalità creato chiamando questa funzione viene mantenuto nella pipeline dell'unità biometrica dopo che la funzione restituisce. Sostituisce qualsiasi set di funzionalità precedente.

L'implementazione dell'adattatore del sensore della funzione SensorAdapterPushDataToEngine deve usare la funzione wrapper seguente (definita in Winbio_adapter.h) per chiamare EngineAdapterAcceptSampleData:

HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);

La struttura WINBIO_BIR passata nel parametro SampleBuffer è la proprietà dell'adattatore del sensore. Poiché l'adattatore del sensore controlla la durata dell'oggetto WINBIO_BIR , la funzione EngineAdapterAcceptSampleData non deve tentare di deallocare la struttura o salvare un puntatore. Non salvando il puntatore, si impedisce ad altre parti dell'adattatore del motore di tentare di usare la struttura WINBIO_BIR dopo che la funzione EngineAdapterAcceptSampleData restituisce.

Se il campo Offset del membro StandardDataBlock della struttura di WINBIO_BIR è maggiore di zero (indicante che il bir contiene un campione biometrico nel formato dati standard), il campo BiometricDataFormat del membro HeaderBlock deve essere impostato come segue:

• Il campo Proprietario deve essere WINBIO_ ANSI_381_FORMAT_OWNER.
• Il campo Type deve essere WINBIO_ANSI_381_FORMAT_TYPE.

Windows Biometric Framework presuppone inoltre che il membro HeaderBlock (una struttura WINBIO_BIR_HEADER ) contenga i valori DataFlags e Purpose usati dall'adattatore del sensore per acquisire l'esempio.

I sensori di impronta digitale elaborano esempi di impronta digitale e rifiutano i scorrimenti non validi nell'adattatore motore devono usare anche valori validi per WINBIO_BIR_PURPOSE.

Esempio

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAcceptSampleData
//
// Purpose:
//      Notifies the engine adapter to accept a raw biometric sample and 
//      extract a feature set.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation. 
//      SampleBuffer    - Contains the biometric sample to be processed.
//      SampleSize      - Size of the structure returned in the SampleBuffer 
//                        parameter.
//      Purpose         - Specifies the intended use of the sample.
//      RejectDetail    - Receives additional information about the failure, 
//                        if any, to process a biometric sample.
//
static HRESULT
WINAPI
EngineAdapterAcceptSampleData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_BIR SampleBuffer,
    __in SIZE_T SampleSize,
    __in WINBIO_BIR_PURPOSE Purpose,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    PUCHAR featureSet = NULL;

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

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

    // Verify that input arguments are valid.
    if (SampleSize == 0 ||
        Purpose == WINBIO_NO_PURPOSE_AVAILABLE)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Release any feature set currently attached to the pipeline before
    // creating a new feature set.
    if (context->FeatureSet != NULL)
    {
        _AdapterRelease(context->FeatureSet);
        context->FeatureSet = NULL;
        context->FeatureSetSize = 0;
    }

    // An actual engine adapter would here process the contents of the sample 
    // buffer, generate a feature set suitable for the purpose(s) specified 
    // by the Purpose parameter, and attach the feature set to the pipeline. 
    // The following trivial example, however, creates a feature set simply
    // by making an exact copy of the raw sample.
    // If the sample data cannot be processed, return an HRESULT error code
    // of WINBIO_E_BAD_CAPTURE and set extended error information in the 
    // RejectDetail parameter.
    featureSet = (PUCHAR)_AdapterAlloc(SampleSize);
    if (featureSet == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }
    RtlCopyMemory(featureSet, SampleBuffer, SampleSize);
    context->FeatureSet = featureSet;
    featureSet = NULL;
    context->FeatureSetSize = SampleSize;

cleanup:

    if (FAILED(hr))
    {
        if (featureSet != NULL)
        {
            _AdapterRelease(featureSet);
        }
    }

    return hr;
}

Requisiti

Vedi anche

EngineAdapterExportEngineData

Funzioni plug-in