PIBIO_ENGINE_ATTACH_FN Rückruffunktion (winbio_adapter.h)

Artikel
08/27/2023

Wird vom Windows Biometric Framework aufgerufen, wenn der Verarbeitungspipeline der biometrischen Einheit ein Moduladapter hinzugefügt wird. Der Zweck dieser Funktion besteht darin, jede Initialisierung durchzuführen, die für spätere biometrische Vorgänge erforderlich ist.

Syntax

PIBIO_ENGINE_ATTACH_FN PibioEngineAttachFn;

HRESULT PibioEngineAttachFn(
  [in, out] PWINBIO_PIPELINE Pipeline
)
{...}

Parameter

[in, out] Pipeline

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

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_POINTER	Das Pipelineargument darf nicht NULL sein.
E_OUTOFMEMORY	Der Vorgang konnte aufgrund von unzureichendem Arbeitsspeicher nicht abgeschlossen werden.
WINBIO_E_INVALID_DEVICE_STATE	Das EngineContext-Element der WINBIO_PIPELINE Struktur, auf die das Pipelineargument verweist, ist nicht NULL , oder das EngineHandle-Element ist nicht auf INVALID_HANDLE_VALUE festgelegt.

Hinweise

Diese Funktion wird aufgerufen, bevor der Speicheradapter für die biometrische Einheit initialisiert wurde. Daher darf diese Funktion keine Funktionen aufrufen, auf die von der WINBIO_STORAGE_INTERFACE-Struktur verwiesen wird, auf die das StorageInterface-Element des Pipelineobjekts verweist.

Wenn Sie diese Funktion implementieren, müssen Sie alle vom Adapter benötigten Ressourcen zuordnen und verwalten und diese an die Pipeline für biometrische Einheiten anfügen. Ordnen Sie hierzu eine private WINBIO_ENGINE_CONTEXT-Struktur auf dem Heap zu, initialisieren Sie sie, und legen Sie ihre Adresse im EngineContext-Member des Pipelineobjekts fest.

Wenn beim Erstellen und Initialisieren der von dieser Funktion verwendeten Moduladapterressourcen ein Fehler auftritt, müssen Sie vor der Rückgabe alle erforderlichen Bereinigungen durchführen.

Wenn das Feld EngineContext beim Aufruf dieser Funktion nicht NULL ist, wurde die Pipeline nicht ordnungsgemäß initialisiert, und Sie müssen WINBIO_E_INVALID_DEVICE_STATE zurückgeben, um das Windows Biometric Framework über das Problem zu benachrichtigen.

Wenn das EngineHandle-Feld beim Aufruf dieser Funktion keine INVALID_HANDLE_VALUE enthält, müssen Sie WINBIO_E_INVALID_DEVICE_STATE zurückgeben.

Beispiele

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAttach
//
// Purpose:
//      Performs any initialization required for later biometric operations.
//
// Parameters:
//      Pipeline -  Pointer to a WINBIO_PIPELINE structure associated with 
//                  the biometric unit performing the operation.
//
static HRESULT
WINAPI
EngineAdapterAttach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;

    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_ENGINE_CONTEXT newContext = NULL;

    // Call a custom function (_AdapterAlloc) to allocate memory to hold the 
    // engine adapter context.
    newContext = (PWINBIO_ENGINE_CONTEXT)_AdapterAlloc(sizeof(WINBIO_ENGINE_CONTEXT));
    if (newContext == NULL)
    {
        E_OUTOFMEMORY;
        goto cleanup;
    }

    // Clear the context memory.
    ZeroMemory(newContext, sizeof(WINBIO_ENGINE_CONTEXT));

    // Initialize any required context fields.
    newContext->SomeField = SomeSpecialValue;

    newContext->SomePointerField = _AdapterAlloc(sizeof(SOME_STRUCTURE));
    if (newContext->SomePointerField == NULL)
    {
        E_OUTOFMEMORY;
        goto cleanup;
    }

    // If your adapter supports software-based template hashing, implement the 
    // following custom function to open a SHA1 hash object handle and store 
    // the handle in the adapter context. Use Cryptography Next Generation (CNG) 
    // functions to create the SHA1 hash object.
    hr = _AdapterInitializeCrypto(newContext);
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // If initialization completes successfully, attach the engine context to the 
    // processing pipeline of the biometric unit.
    Pipeline->EngineContext = newContext;
    newContext = NULL;

cleanup:
    if (FAILED(hr))
    {
        // If a new context has been created, release any memory 
        // pointed to by various data members in the context and 
        // then release the context. The following example assumes 
        // that your adapter contains a handle
        // for a hash object and a pointer to another object.
        if (newContext != NULL)
        {
            // Close any open CNG handles and release the hash object memory.
            _AdapterCleanupCrypto(newContext);

            // Release any other object pointed to by the context.
            if (newContext->SomePointerField != NULL)
            {
                _AdapterRelease(newContext->SomePointerField);
            }

            // Release the context
            _AdapterRelease(newContext);
        }
    }
    return hr;

}

Anforderungen


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)