PWINBIO_CAPTURE_CALLBACK callback function (winbio.h)

Article
10/13/2021

Called by the Windows Biometric Framework to return results from the asynchronous WinBioCaptureSampleWithCallback function. The client application must implement this function.

Important We recommend that, beginning with Windows 8, you no longer use the PWINBIO_CAPTURE_CALLBACK/WinBioCaptureSampleWithCallback combination. Instead, do the following:

Implement a PWINBIO_ASYNC_COMPLETION_CALLBACK function to receive notice when the operation completes.
Call the WinBioAsyncOpenSession function. Pass the address of your callback in the CallbackRoutine parameter. Pass WINBIO_ASYNC_NOTIFY_CALLBACK in the NotificationMethod parameter. Retrieve an asynchronous session handle.
Use the asynchronous session handle to call WinBioCaptureSample. When the operation finishes, the Windows Biometric Framework will allocate and initialize a WINBIO_ASYNC_RESULT structure with the results and invoke your callback with a pointer to the results structure.
Call WinBioFree from your callback implementation to release the WINBIO_ASYNC_RESULT structure after you have finished using it.

Syntax

PWINBIO_CAPTURE_CALLBACK PwinbioCaptureCallback;

void PwinbioCaptureCallback(
  [in, optional] PVOID CaptureCallbackContext,
  [in]           HRESULT OperationStatus,
  [in]           WINBIO_UNIT_ID UnitId,
  [in]           PWINBIO_BIR Sample,
  [in]           SIZE_T SampleSize,
  [in]           WINBIO_REJECT_DETAIL RejectDetail
)
{...}

Parameters

[in, optional] CaptureCallbackContext

Pointer to a buffer defined by the application and passed to the CaptureCallbackContext parameter of the WinBioCaptureSampleWithCallback function. The buffer is not modified by the framework or the biometric unit. Your application can use the data to help it determine what actions to perform or to maintain additional information about the biometric capture.

[in] OperationStatus

Error code returned by the capture operation.

[in] UnitId

Biometric unit ID number.

[in] Sample

Pointer to the sample data.

[in] SampleSize

Size, in bytes, of the sample data pointed to by the Sample parameter.

[in] RejectDetail

Additional information about the failure, if any, to perform the operation. For more information, see Remarks.

Return value

None

Remarks

Currently, the Windows Biometric Framework supports only fingerprint readers. Therefore, if an operation fails and returns additional information in a WINBIO_REJECT_DETAIL constant, it will be one of the following values:

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

Examples

The following code example captures a sample asynchronously by calling WinBioCaptureSampleWithCallback and passing a pointer to a custom callback function, CaptureSampleCallback. Link to the Winbio.lib static library and include the following header files:

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT CaptureSampleWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Raw access
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            WINBIO_DB_DEFAULT,          // Default database
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture a biometric sample asynchronously.
    wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
    hr = WinBioCaptureSampleWithCallback(
            sessionHandle,                  // Open session handle
            WINBIO_NO_PURPOSE_AVAILABLE,    // Intended use of the sample
            WINBIO_DATA_FLAG_RAW,           // Sample format
            CaptureSampleCallback,          // Callback function
            NULL                            // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the capture process if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...");
        Sleep( 7000 );

        wprintf_s(L"\n Calling WinBioCancel\n");
        hr = WinBioCancel( sessionHandle );
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioCancel failed. hr = 0x%x\n", hr);
            goto e_Exit;
        }
    }

    // Wait for the asynchronous capture process to complete 
    // or be canceled.
    hr = WinBioWait( sessionHandle );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
    }

e_Exit:

    if (sessionHandle != NULL)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

    wprintf_s(L"\n Press any key to exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
    __in_opt PVOID CaptureCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in_bcount(SampleSize) PWINBIO_BIR Sample,
    __in SIZE_T SampleSize,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(CaptureCallbackContext);

    wprintf_s(L"\n CaptureSampleCallback executing");
    wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);

    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
         }
        else
        {
            wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
            wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Captured %d bytes.\n", SampleSize);

e_Exit:

    if (Sample != NULL)
    {
        WinBioFree(Sample);
        Sample = NULL;
    }
}

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	winbio.h