PIBIO_ENGINE_EXPORT_ENGINE_DATA_FN Rückruffunktion (winbio_adapter.h)

Artikel
03/03/2024

Wird vom Windows Biometric Framework aufgerufen, um eine Kopie des zuletzt verarbeiteten Featuresatzes oder der zuletzt verarbeiteten Vorlage aus der Engine abzurufen, die als Standard WINBIO_BIR Struktur formatiert ist.

Syntax

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

Parameter

[in, out] Pipeline

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

[in] Flags

Ein Wert, der die Eigenschaften der vom Modul zurückgegebenen WINBIO_BIR Struktur angibt. Dies kann ein bitweiser OR der folgenden Flags für Sicherheits- und Verarbeitungsebene sein:

WINBIO_DATA_FLAG_PRIVACY

Die Daten sind verschlüsselt.

WINBIO_DATA_FLAG_INTEGRITY Die Daten werden digital signiert oder durch einen Nachrichtenauthentifizierungscode (MAC) geschützt.
WINBIO_DATA_FLAG_SIGNED Wenn dieses Flag und das WINBIO_DATA_FLAG_INTEGRITY-Flag festgelegt sind, werden die Daten signiert. Wenn dieses Flag nicht festgelegt ist, aber das WINBIO_DATA_FLAG_INTEGRITY-Flag festgelegt ist, wird ein MAC berechnet.
WINBIO_DATA_FLAG_RAW Die Daten haben das Format, mit dem sie erfasst wurden.
WINBIO_DATA_FLAG_INTERMEDIATE Die Daten sind nicht roh, wurden aber noch nicht vollständig verarbeitet.
WINBIO_DATA_FLAG_PROCESSED Die Daten wurden verarbeitet.

[out] SampleBuffer

Adresse einer Variablen, die einen Zeiger auf eine WINBIO_BIR Struktur empfängt, die den Featuresatz oder die Vorlage enthält.

[out] SampleSize

Zeiger auf eine Variable, die die Größe der WINBIO_BIR Struktur enthält, die im SampleBuffer-Parameter zurückgegeben wird.

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	Der Moduladapter unterstützt nicht die Kombination von Flags, die durch den Flags-Parameter angegeben wird.
E_OUTOFMEMORY	Es ist nicht genügend Arbeitsspeicher verfügbar, um die WINBIO_BIR-Struktur zu erstellen.
E_POINTER	Ein obligatorischer Zeigerparameter ist NULL.
WINBIO_E_INVALID_DEVICE_STATE	Die Pipeline enthält nicht den Datentyp, der für den Flags-Parameter erforderlich ist.
E_NOTIMPL	Diese Methode ist derzeit nicht implementiert.

Hinweise

Sie müssen den Puffer zuordnen, der im SampleBuffer-Parameter aus dem Prozessheap zurückgegeben werden soll, indem Sie die HeapAlloc-Funktion verwenden . Nachdem der Puffer erstellt wurde, wird er zur Eigenschaft des Windows Biometric Framework. Da das Framework die Zuordnung dieses Arbeitsspeichers nach Seiner Verwendung erledigt, darf Ihre Implementierung dieser Funktion nicht versuchen, die Zuordnung des Puffers zu beheben oder einen Zeiger darauf zu speichern. Indem Sie den Zeiger nicht speichern, verhindern Sie, dass andere Teile des Moduladapters versuchen, den Puffer zu verwenden, nachdem diese Funktion zurückgegeben wird.

Beispiele

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

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

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

EngineAdapterAcceptSampleData

Plug-In-Funktionen

Freigeben über