Freigeben über


PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN Rückruffunktion (winbio_adapter.h)

Wird von der SensorAdapterPushDataToEngine-Funktion aufgerufen, die vom Sensoradapter implementiert wird, um den Engineadapter zu benachrichtigen, eine biometrische Rohprobe zu akzeptieren und einen Featuresatz zu extrahieren. Der Featuresatz kann für den Abgleich oder die Registrierung verwendet werden.

Syntax

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

Parameter

[in, out] Pipeline

Zeiger auf eine WINBIO_PIPELINE Struktur, die der biometrischen Einheit zugeordnet ist, die den Vorgang ausführt.

[in] SampleBuffer

Zeiger auf eine WINBIO_BIR Struktur, die die zu verarbeitende biometrische Stichprobe enthält.

[in] SampleSize

Ein SIZE_T Wert, der die Größe der WINBIO_BIR Struktur enthält, die im SampleBuffer-Parameter zurückgegeben wird.

[in] Purpose

Eine WINBIO_BIR_PURPOSE Bitmaske, die die beabsichtigte Verwendung des Beispiels angibt. Die WINBIO_BIR_PURPOSE-Struktur gibt den Zweck an, für den Erfassungsdaten verwendet werden sollen, und (daher) wie sie optimiert werden sollen. Dies kann ein bitweiser OR der folgenden Werte sein:

  • WINBIO_PURPOSE_VERIFY
  • WINBIO_PURPOSE_IDENTIFY
  • WINBIO_PURPOSE_ENROLL
  • WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
  • WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[out] RejectDetail

Ein Zeiger auf einen WINBIO_REJECT_DETAIL Wert, der zusätzliche Informationen über den Fehler bei der Verarbeitung einer biometrischen Stichprobe empfängt. Wenn der Vorgang erfolgreich war, wird dieser Parameter auf 0 festgelegt. Die folgenden Werte werden für Fingerabdruckbeispiele definiert:

  • 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

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie S_OK zurück. Wenn die Funktion fehlschlägt, muss sie einen der folgenden HRESULT-Werte zurückgeben, um den Fehler anzugeben.

Rückgabecode Beschreibung
E_INVALIDARG
Das Argument SampleSize darf nicht 0 sein. Das Argument Purpose muss ein bitweiser OR der werte sein, die in der Parameterbeschreibung aufgeführt sind.
E_POINTER
Die Argumente Pipeline, SampleBuffer und RejectDetail dürfen nicht NULL sein.
E_OUTOFMEMORY
Der Vorgang konnte aufgrund von unzureichendem Arbeitsspeicher nicht abgeschlossen werden.
WINBIO_E_BAD_CAPTURE
Die Daten konnten nicht zum Erstellen des erforderlichen Featuresatzes verarbeitet werden. Der RejectDetail enthält zusätzliche Informationen zum Fehler.

Hinweise

Der Featuresatz, der durch aufrufen dieser Funktion erstellt wurde, wird in der Pipeline für biometrische Einheiten beibehalten, nachdem die Funktion zurückgegeben wurde. Es ersetzt alle vorherigen Featuresätze.

Die Sensoradapterimplementierung der SensorAdapterPushDataToEngine-Funktion sollte die folgende Wrapperfunktion (definiert in Winbio_adapter.h) verwenden, um EngineAdapterAcceptSampleData aufzurufen:

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

Die WINBIO_BIR Struktur, die im Parameter SampleBuffer übergeben wird, ist die Eigenschaft des Sensoradapters. Da der Sensoradapter die Lebensdauer des WINBIO_BIR -Objekts steuert, darf die EngineAdapterAcceptSampleData-Funktion nicht versuchen, die Struktur zuzuordnen oder einen Zeiger darauf zu speichern. Indem Sie den Zeiger nicht speichern, verhindern Sie, dass andere Teile des Moduladapters versuchen, die WINBIO_BIR-Struktur zu verwenden, nachdem die EngineAdapterAcceptSampleData-Funktion zurückgegeben wird.

Wenn das Offset-Feld des StandardDataBlock-Members der WINBIO_BIR-Struktur größer als 0 ist (was angibt, dass die BIR eine biometrische Stichprobe im Standarddatenformat enthält), muss das Feld BiometricDataFormat des HeaderBlock-Elements wie folgt festgelegt werden:

  • Das Feld Besitzer muss WINBIO_ ANSI_381_FORMAT_OWNER sein.
  • Das Feld Typ muss WINBIO_ANSI_381_FORMAT_TYPE sein.
Dies ist das einzige Standarddatenformat, das vom Windows Biometric Framework unterstützt wird.

Das Windows Biometric Framework geht auch davon aus, dass der HeaderBlock-Member (eine WINBIO_BIR_HEADER-Struktur ) die DataFlags - und Purpose-Werte enthält, die vom Sensoradapter zum Erfassen des Beispiels verwendet werden.

Fingerabdrucksensoren, die Fingerabdruckproben verarbeiten und fehlerhafte Wischvorgänge im Engine-Adapter ablehnen, sollten auch gültige Werte für WINBIO_BIR_PURPOSE verwenden.

Beispiele

Der folgende Pseudocode zeigt eine mögliche Implementierung dieser Funktion. Das Beispiel wird nicht kompiliert. Sie müssen es an Ihren Zweck anpassen.

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

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile winbio_adapter.h (einschließlich Winbio_adapter.h)

Weitere Informationen

EngineAdapterExportEngineData

Plug-In-Funktionen