PIBIO_SENSOR_ATTACH_FN Rückruffunktion (winbio_adapter.h)

Artikel
03/06/2024

Wird vom Windows Biometric Framework aufgerufen, wenn der Verarbeitungspipeline der biometrischen Einheit ein Sensoradapter 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_SENSOR_ATTACH_FN PibioSensorAttachFn;

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

Parameter

[in, out] Pipeline

Zeiger auf die 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 SensorContext-Element der WINBIO_PIPELINE Struktur, auf die das Pipelineargument verweist, ist nicht NULL.

Hinweise

Diese Funktion wird aufgerufen, bevor die Engine und die Speicheradapter für die biometrische Einheit initialisiert wurden. Daher darf diese Funktion keine Funktionen aufrufen, auf die vom WINBIO_ENGINE_INTERFACE oder der WINBIO_STORAGE_INTERFACE Struktur verwiesen wird, auf die vom EngineInterface - und StorageInterface-Element des Pipelineobjekts verwiesen wird.

Da das SensorHandle-Element der WINBIO_PIPELINE-Struktur einen gültigen Handle enthält, bevor diese Methode aufgerufen wird, kann Ihre Implementierung von SensorAdapterAttach den Handle verwenden, um bei Bedarf auf das Sensorgerät zuzugreifen.

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_SENSOR_CONTEXT-Struktur auf dem Heap zu, initialisieren Sie sie, und legen Sie ihre Adresse im SensorContext-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 SensorContext beim Aufruf dieser Funktion nicht NULL ist, wurde die Pipeline durch einen vorherigen Aufruf von SensorAdapterDetach nicht ordnungsgemäß zurückgesetzt, und Sie müssen WINBIO_E_INVALID_DEVICE_STATE zurückgeben, um das Windows Biometric Framework über das Problem zu benachrichtigen.

Beispiele

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterAttach
//
// 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
SensorAdapterAttach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;
    PWINBIO_SENSOR_CONTEXT newContext = NULL;

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

    // Validate the current sensor state.
    if (Pipeline->SensorContext != NULL)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Use a custom function (_AdapterAlloc) to allocate memory for the 
    // sensor adapter context.
    newContext = (PWINBIO_SENSOR_CONTEXT)_AdapterAlloc(sizeof(WINBIO_SENSOR_CONTEXT));
    if (newContext == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }

    // Create a manual reset event to monitor overlapped I/O.
    newContext->Overlapped.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
    if (newContext->Overlapped.hEvent == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }

    // Initialize any required context fields. This example assumes that your
    // sensor context points to a capture buffer and an attributes buffer.
    newContext->CaptureBuffer = NULL;
    newContext->CaptureBufferSize = 0;

    newContext->AttributesBuffer = NULL;
    newContext->AttributesBufferSize = sizeof (WINBIO_SENSOR_ATTRIBUTES);

    // Transfer ownership of the new sensor context structure to the 
    // pipeline.
    Pipeline->SensorContext = newContext;
    newContext = NULL;

cleanup:

    if (FAILED(hr) && newContext != NULL)
    {
        CloseHandle( newContext->Overlapped.hEvent;
        _AdapterRelease( newContext );
        newContext = NULL;
    }
    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)