PIBIO_SENSOR_DETACH_FN Rückruffunktion (winbio_adapter.h)

Artikel
03/06/2024

Wird vom Windows Biometric Framework aufgerufen, unmittelbar bevor ein Sensoradapter aus der Verarbeitungspipeline der biometrischen Einheit entfernt wird. Der Zweck dieser Funktion besteht darin, adapterspezifische Ressourcen freizugeben, die an die Pipeline angefügt sind.

Syntax

PIBIO_SENSOR_DETACH_FN PibioSensorDetachFn;

HRESULT PibioSensorDetachFn(
  [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, wird S_OK zurückgegeben. Wenn die Funktion fehlschlägt, muss sie einen der folgenden HRESULT-Werte zurückgeben, um den Fehler anzugeben.

Rückgabecode	Beschreibung
E_POINTER	Der Pipelineparameter darf nicht NULL sein.
WINBIO_E_INVALID_DEVICE_STATE	Das SensorContext-Feld der WINBIO_PIPELINE-Struktur darf nicht NULL sein.

Hinweise

Um Speicherverluste zu verhindern, muss Ihre Implementierung der SensorAdapterDetach-Funktion die private WINBIO_SENSOR_CONTEXT Struktur freigeben, auf die der SensorContext-Member der Pipeline sowie alle anderen Ressourcen verweist, die an den Sensorkontext angefügt sind.

Wenn das Feld SensorContext im Pipelineobjekt null ist , wenn diese Funktion aufgerufen wird, 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.

Bevor S_OK zurückgegeben wird, muss diese Funktion das SensorContext-Feld der WINBIO_PIPELINE-Struktur auf NULL festlegen.

Da diese Funktion aufgerufen wird, nachdem die Speicher- und Engine-Adapter aus der Pipeline entfernt wurden, darf Ihre Implementierung dieser Funktion keine Funktionen aufrufen, auf die die WINBIO_ENGINE_INTERFACE oder WINBIO_STORAGE_INTERFACE Strukturen verweisen, auf die die Member EngineInterface und StorageInterface des Pipelineobjekts verweisen.

Da der SensorHandle-Member der WINBIO_PIPELINE-Struktur auch nach dem Aufrufen von SensorAdapterDetach ein gültiges Handle enthält, können Sie das Handle bei Bedarf verwenden, um auf das Sensorgerät zuzugreifen. Diese Funktion sollte den Sensorhandle nicht schließen. Das Windows-Biometrieframework tut dies nach der Rückgabe von SensorAdapterDetach .

Beispiele

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterDetach
//
// Purpose:
//      Cancels all pending sensor operations.
//      
// Parameters:
//      Pipeline -  Pointer to a WINBIO_PIPELINE structure associated with 
//                  the biometric unit.
//
static HRESULT
WINAPI
SensorAdapterDetach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    PWINBIO_SENSOR_CONTEXT sensorContext = NULL;

    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline))
    {
        hr = E_POINTER;
        goto cleanup;
    }
 
    // Validate the current state of the sensor.
    if (Pipeline->SensorContext == NULL)
    {
        return WINBIO_E_INVALID_DEVICE_STATE;
    }

    // Cancel any pending I/O to the device.
    SensorAdapterCancel(Pipeline);

    // Take ownership of the sensor context from the pipeline.
    sensorContext = (PWINBIO_SENSOR_CONTEXT)Pipeline->SensorContext;
    Pipeline->SensorContext = NULL;

    // Release any structures that remain attached to the context block. 
    // The following example assumes that your sensor adapter context 
    // contains pointers to a capture buffer and an attributes buffer.
    if (sensorContext->CaptureBuffer != NULL)
    {
        // Zero the capture buffer.
        SecureZeroMemory(
            sensorContext->CaptureBuffer,
            sensorContext->CaptureBufferSize);

        // Release the capture buffer.
        _AdapterRelease(sensorContext->CaptureBuffer);
        sensorContext->CaptureBuffer = NULL;
        sensorContext->CaptureBufferSize = 0;
    }

    if (sensorContext->AttributesBuffer != NULL)
    {
        // Zero the attributes buffer.
        SecureZeroMemory(
            sensorContext->AttributesBuffer,
            sensorContext->AttributesBufferSize);

        // Release the attributes buffer.
        _AdapterRelease(sensorContext->AttributesBuffer);
        sensorContext->AttributesBuffer = NULL;
        sensorContext->AttributesBufferSize = 0;
    }

    // Close the overlapped I/O event handle.
    CloseHandle(sensorContext->Overlapped.hEvent);

    // Release the context structure.
    _AdapterRelease(sensorContext);
    sensorContext = NULL;
   
    return S_OK;
}

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 (Winbio_adapter.h einschließen)

Weitere Informationen

Plug-In-Funktionen

SensorAdapterAttach

WINBIO_PIPELINE

Freigeben über