WinBioCaptureSampleWithCallback function

Captures a biometric sample asynchronously and returns the raw or processed data in a biometric information record (BIR). The function returns immediately to the caller, captures the sample on a separate thread, and calls into an application-defined callback function to update operation status.


We recommend that, beginning with Windows 8, you no longer use this function to start an asynchronous operation. 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.


HRESULT WINAPI WinBioCaptureSampleWithCallback(
  _In_     WINBIO_SESSION_HANDLE    SessionHandle,
  _In_     WINBIO_BIR_PURPOSE       Purpose,
  _In_     WINBIO_BIR_DATA_FLAGS    Flags,
  _In_     PWINBIO_CAPTURE_CALLBACK CaptureCallback,
  _In_opt_ PVOID                    CaptureCallbackContext


SessionHandle [in]

A WINBIO_SESSION_HANDLE value that identifies an open biometric session.

Purpose [in]

A WINBIO_BIR_PURPOSE bitmask that specifies the intended use of the sample. This can be a bitwise OR of the following values:

Flags [in]

A value that specifies the type of processing to be applied to the captured sample. This can be a bitwise OR of the following security and processing level flags:

WINBIO_DATA_FLAG_PRIVACY (Encrypt the sample.)
WINBIO_DATA_FLAG_INTEGRITY (Sign the sample or protect it by using a message authentication code (MAC).)
WINBIO_DATA_FLAG_SIGNED (If this flag and the WINBIO_DATA_FLAG_INTEGRITY flag are set, sign the sample. If this flag is not set but the WINBIO_DATA_FLAG_INTEGRITY flag is set, compute a MAC.)
WINBIO_DATA_FLAG_RAW (Return the sample exactly as it was captured by the sensor.)
WINBIO_DATA_FLAG_INTERMEDIATE (Return the sample after it has been cleaned and filtered.)
WINBIO_DATA_FLAG_PROCESSED (Return the sample after it is ready to be used for the purpose specified by the Purpose parameter.)
CaptureCallback [in]

Address of a callback function that will be called by the WinBioCaptureSampleWithCallback function when the capture operation succeeds or fails. You must create the callback.

CaptureCallbackContext [in, optional]

Address of an application-defined data structure that is passed to the callback function in its CaptureCallbackContext parameter. This structure can contain any data that the custom callback function is designed to handle.

Return value

If the function succeeds, it returns S_OK. If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

Return codeDescription

The caller does not have permission to capture raw samples, or the session was not opened by using the WINBIO_FLAG_RAW flag.


The session handle is not valid.


The biometric unit does not support the requested operation.


The UnitId, Sample, SampleSize, and RejectDetail pointers cannot be NULL.


The operation could not be completed because the biometric unit is currently being used for an enrollment transaction (system pool only).



The WinBioCaptureSampleWithCallback function captures samples asynchronously. To call this function successfully, the session handle must have been opened by specifying WINBIO_FLAG_RAW. Only the Administrators and Local System accounts have the necessary privileges.

Valid combinations of the Purpose and Flags parameters depend on the capabilities of the biometric unit being used. Consult the vendor sensor documentation to determine what combinations are supported and how they affect the captured data.

Callers are responsible for releasing the WINBIO_BIR structure returned by the Sample parameter.

The callback routine must have the following signature:

VOID CALLBACK CaptureCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,


The following code example captures a sample asynchronously by calling WinBioCaptureSampleWithCallback and passing a pointer to a custom callback function. The callback function, CaptureSampleCallback, is also shown. 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;

    // 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);


    if (sessionHandle != NULL)
        sessionHandle = NULL;

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

    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

    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);
            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);


    if (Sample != NULL)
        Sample = NULL;


Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]


Winbio.h (include Winbio.h)





See also