PIBIO_SENSOR_FINISH_CAPTURE_FN Rückruffunktion (winbio_adapter.h)

Artikel
08/27/2023

Wird vom Windows Biometric Framework aufgerufen, um auf den Abschluss eines Erfassungsvorgangs zu warten, der von der SensorAdapterStartCapture-Funktion initiiert wird.

Syntax

PIBIO_SENSOR_FINISH_CAPTURE_FN PibioSensorFinishCaptureFn;

HRESULT PibioSensorFinishCaptureFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [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.

[out] RejectDetail

Zeiger auf einen WINBIO_REJECT_DETAIL Wert, der zusätzliche Informationen über den Fehler beim Erfassen einer biometrischen Stichprobe empfängt. Wenn der Vorgang erfolgreich war, wird dieser Parameter auf 0 (null) 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, wird S_OK zurückgegeben. Wenn die Funktion fehlschlägt, wird ein HRESULT-Wert zurückgegeben, der den Fehler angibt. Die folgenden Werte werden vom Windows Biometric Framework erkannt.

Rückgabecode	Beschreibung
WINBIO_E_BAD_CAPTURE	Das Beispiel konnte nicht erfasst werden. Wenn Sie diesen Fehlercode zurückgeben, müssen Sie auch einen Wert im RejectDetail-Parameter angeben, der die Art des Problems angibt.
WINBIO_E_CAPTURE_CANCELED	Der Sensortreiber hat ERROR_CANCELLED oder ERROR_OPERATION_ABORTED zurückgegeben.
WINBIO_E_DEVICE_FAILURE	Es ist ein Gerätefehler aufgetreten.
WINBIO_E_INVALID_DEVICE_STATE	Das SensorContext-Element der WINBIO_PIPELINE-Struktur , auf die das Argument Pipeline verweist, ist NULL , oder das SensorHandle-Element ist auf INVALID_HANDLE_VALUE festgelegt.

Hinweise

Das Windows Biometric Framework ruft diese Funktion auf, nachdem sensorAdapterStartCapture erfolgreich oder SensorAdapterCancel aufgerufen wurde. Diese Funktion wird nicht aufgerufen, wenn der Aufruf von SensorAdapterStartCapture fehlschlägt.

Wenn ihre Implementierung dieser Funktion zurückgibt, sollten die Daten in der Pipeline für nachfolgende Aufrufe von Funktionen wie SensorAdapterPushDataToEngine oder SensorAdapterExportSensorData bereit sein.

Dies ist eine blockierende Funktion, die erst zurückgegeben werden sollte, nachdem der Sensor-E/A-Vorgang erfolgreich war, fehlgeschlagen oder abgebrochen wurde. In der Regel erstellen Sie diesen Funktionsblock, indem Sie die OVERLAPPED-Struktur im Kontext des Sensoradapters an die GetOverlappedResult-Funktion übergeben. Das hEvent-Handle in der OVERLAPPED-Struktur muss signalisiert werden, wenn SensorAdapterFinishCapture zurückgegeben wird. Die GetOverlappedResult-Funktion legt diesen Handle automatisch fest, wenn das Ende eines Sensor-E/A-Vorgangs erkannt wird. Wenn Ihr Adapter einen anderen Mechanismus verwendet, um die E/A-Vervollständigung zu erkennen, müssen Sie das Ereignis selbst signalisieren.

Beispiele

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterFinishCapture
//
// Purpose:
//      Waits for the completion of a capture operation initiated by the 
//      SensorAdapterStartCapture function.
//      
// Parameters:
//      Pipeline     -  Pointer to a WINBIO_PIPELINE structure associated with 
//                      the biometric unit.
//      RejectDetail -  Pointer to a WINBIO_REJECT_DETAIL value that receives 
//                      additional information about the failure to capture a 
//                      biometric sample.
//
static HRESULT
WINAPI
SensorAdapterFinishCapture(
    __inout PWINBIO_PIPELINE Pipeline,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    WINBIO_SENSOR_STATUS sensorStatus = WINBIO_SENSOR_FAILURE;
    WINBIO_CAPTURE_PARAMETERS captureParameters = {0};
    BOOL result = TRUE;
    DWORD bytesReturned = 0;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(RejectDetail))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_SENSOR_CONTEXT sensorContext = 
             (PWINBIO_SENSOR_CONTEXT)Pipeline->SensorContext;

    // Verify the state of the pipeline.
    if (sensorContext == NULL || 
        Pipeline->SensorHandle == INVALID_HANDLE_VALUE)
    {
        return WINBIO_E_INVALID_DEVICE_STATE;
    }

    // Initialize the RejectDetail argument.
    *RejectDetail = 0;

    // Wait for I/O completion. This sample assumes that the I/O operation was 
    // started using the code example shown in the SensorAdapterStartCapture
    // documentation.
    SetLastError(ERROR_SUCCESS);

    result = GetOverlappedResult(
                Pipeline->SensorHandle,
                &sensorContext->Overlapped,
                &bytesReturned,
                TRUE
                );
    if (!result)
    {
        // There was an I/O error.
        return _AdapterGetHresultFromWin32(GetLastError());
    }

    if (bytesReturned == sizeof (DWORD))
    {
        // The buffer is not large enough.  This can happen if a device needs a 
        // bigger buffer depending on the purpose. Allocate a larger buffer and 
        // force the caller to reissue their I/O request.
        DWORD allocationSize = sensorContext->CaptureBuffer->PayloadSize;

        // Allocate at least the minimum buffer size needed to retrieve the 
        // payload structure.
        if (allocationSize < sizeof(WINBIO_CAPTURE_DATA))
        {
            allocationSize = sizeof(WINBIO_CAPTURE_DATA);
        }

        // Free the old buffer and allocate a new one.
        _AdapterRelease(sensorContext->CaptureBuffer);
        sensorContext->CaptureBuffer = NULL;

        sensorContext->CaptureBuffer = 
            (PWINBIO_CAPTURE_DATA)_AdapterAlloc(allocationSize);
        if (sensorContext->CaptureBuffer == NULL)
        {
            sensorContext->CaptureBufferSize = 0;
            return E_OUTOFMEMORY;
        }
        sensorContext->CaptureBufferSize = allocationSize;
        return WINBIO_E_BAD_CAPTURE;
    }

    // Normalize the status value before sending it back to the biometric service.
    if (sensorContext->CaptureBuffer != NULL &&
        sensorContext->CaptureBufferSize >= sizeof (WINBIO_CAPTURE_DATA))
    {
        switch (sensorContext->CaptureBuffer->SensorStatus)
        {
            case WINBIO_SENSOR_ACCEPT:
                // The capture was acceptable.
                break;

            case WINBIO_SENSOR_REJECT:
                // The capture was not acceptable. Overwrite the WinBioHresult value
                // in case it has not been properly set.
                sensorContext->CaptureBuffer->WinBioHresult = WINBIO_E_BAD_CAPTURE;
                break;

            case WINBIO_SENSOR_BUSY:
                // The device is busy. Reset the WinBioHresult value in case it 
                // has not been properly set.
                sensorContext->CaptureBuffer->WinBioHresult = WINBIO_E_DEVICE_BUSY;
                break;

            case WINBIO_SENSOR_READY:
            case WINBIO_SENSOR_NOT_CALIBRATED:
            case WINBIO_SENSOR_FAILURE:
            default:
                // There has been a device failure. Reset the WinBioHresult value
                // in case it has not been properly set.
                sensorContext->CaptureBuffer->WinBioHresult = WINBIO_E_INVALID_DEVICE_STATE;
                break;
        }

        *RejectDetail = sensorContext->CaptureBuffer->RejectDetail;
        hr = sensorContext->CaptureBuffer->WinBioHresult;
    }
    else
    {
        // The buffer is not large enough or the buffer pointer is NULL.
        hr = WINBIO_E_INVALID_DEVICE_STATE;
    }
    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 (Winbio_adapter.h einschließen)