PWINBIO_ENROLL_CAPTURE_CALLBACK callback function (winbio.h)
The PWINBIO_ENROLL_CAPTURE_CALLBACK function is called by the Windows Biometric Framework to return results from the asynchronous WinBioEnrollCaptureWithCallback function. The client application must implement this function.
Important We recommend that, beginning with Windows 8, you no longer use the PWINBIO_ENROLL_CAPTURE_CALLBACK/WinBioEnrollCaptureWithCallback 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 WinBioEnrollCapture. 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_ENROLL_CAPTURE_CALLBACK PwinbioEnrollCaptureCallback;
void PwinbioEnrollCaptureCallback(
[in, optional] PVOID EnrollCallbackContext,
[in] HRESULT OperationStatus,
[in] WINBIO_REJECT_DETAIL RejectDetail
)
{...}
Parameters
[in, optional] EnrollCallbackContext
Pointer to a buffer defined by the application and passed to the EnrollCallback parameter of the WinBioEnrollCaptureWithCallback 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] 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 enrolls a fingerprint asynchronously by calling WinBioEnrollCaptureWithCallback and passing a pointer to a custom callback function, EnrollCaptureCallback. Link to the Winbio.lib static library.
//------------------------------------------------------------------------
// EnrollSystemPoolWithCallback.cpp : console application entry point.
//
#include <windows.h>
#include <stdio.h>
#include <conio.h>
#include <winbio.h>
//------------------------------------------------------------------------
// Forward declarations.
//
HRESULT EnrollSysPoolWithCallback(
BOOL bCancel,
BOOL bDiscard,
WINBIO_BIOMETRIC_SUBTYPE subFactor);
VOID CALLBACK EnrollCaptureCallback(
__in_opt PVOID EnrollCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_REJECT_DETAIL RejectDetail);
typedef struct _ENROLL_CALLBACK_CONTEXT {
WINBIO_SESSION_HANDLE SessionHandle;
WINBIO_UNIT_ID UnitId;
WINBIO_BIOMETRIC_SUBTYPE SubFactor;
} ENROLL_CALLBACK_CONTEXT, *PENROLL_CALLBACK_CONTEXT;
//------------------------------------------------------------------------
int wmain()
{
HRESULT hr = S_OK;
hr = EnrollSysPoolWithCallback(
FALSE,
FALSE,
WINBIO_ANSI_381_POS_RH_INDEX_FINGER);
return 0;
}
//------------------------------------------------------------------------
// The following function enrolls a user's fingerprint in the system pool.
// The function calls WinBioEnrollCaptureWithCallback and waits for the
// asynchronous enrollment process to be completed or canceled.
//
HRESULT EnrollSysPoolWithCallback(
BOOL bCancel,
BOOL bDiscard,
WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
// Declare variables
HRESULT hr = S_OK;
WINBIO_IDENTITY identity = {0};
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
BOOLEAN isNewTemplate = TRUE;
ENROLL_CALLBACK_CONTEXT callbackContext = {0};
// Connect to the system pool.
hr = WinBioOpenSession(
WINBIO_TYPE_FINGERPRINT, // Service provider
WINBIO_POOL_SYSTEM, // Pool type
WINBIO_FLAG_DEFAULT, // Configuration and access
NULL, // Array of biometric unit IDs
0, // Count of biometric unit IDs
NULL, // Database ID
&sessionHandle // [out] Session handle
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnumBiometricUnits failed. ");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
// Locate the sensor.
wprintf_s(L"\n Swipe your finger to locate the sensor...\n");
hr = WinBioLocateSensor( sessionHandle, &unitId);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Begin the enrollment sequence.
hr = WinBioEnrollBegin(
sessionHandle, // Handle to open biometric session
subFactor, // Finger to create template for
unitId // Biometric unit ID
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnrollBegin failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Set up the custom callback context structure.
callbackContext.SessionHandle = sessionHandle;
callbackContext.UnitId = unitId;
callbackContext.SubFactor = subFactor;
// Call WinBioEnrollCaptureWithCallback. This is an asynchronous
// method that returns immediately.
hr = WinBioEnrollCaptureWithCallback(
sessionHandle, // Handle to open biometric session
EnrollCaptureCallback, // Callback function
&callbackContext // Pointer to the custom context
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnrollCaptureWithCallback failed. ");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Swipe the sensor with the appropriate finger...\n");
// Cancel the enrollment if the bCancel flag is set.
if (bCancel)
{
wprintf_s(L"\n Starting CANCEL timer...\n");
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 enrollment process to complete
// or be canceled.
hr = WinBioWait( sessionHandle );
if (FAILED(hr))
{
wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
}
// Discard the enrollment if the bDiscard flag is set.
// Commit the enrollment if the flag is not set.
if (bDiscard)
{
wprintf_s(L"\n Discarding enrollment...\n");
hr = WinBioEnrollDiscard( sessionHandle );
if (FAILED(hr))
{
wprintf_s(L"\n WinBioLocateSensor failed. ");
wprintf_s(L"hr = 0x%x\n", hr);
}
goto e_Exit;
}
else
{
wprintf_s(L"\n Committing enrollment...\n");
hr = WinBioEnrollCommit(
sessionHandle, // Handle to open biometric session
&identity, // WINBIO_IDENTITY object for the user
&isNewTemplate); // Is this a new template
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnrollCommit failed. hr = 0x%x\n", hr);
goto e_Exit;
}
}
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 the Windows Biometric
// Framework WinBioEnrollCaptureWithCallback() function.
//
VOID CALLBACK EnrollCaptureCallback(
__in_opt PVOID EnrollCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_REJECT_DETAIL RejectDetail
)
{
// Declare variables.
HRESULT hr = S_OK;
static SIZE_T swipeCount = 1;
PENROLL_CALLBACK_CONTEXT callbackContext =
(PENROLL_CALLBACK_CONTEXT)EnrollCallbackContext;
wprintf_s(L"\n EnrollCaptureCallback executing\n");
wprintf_s(L"\n Sample %d captured", swipeCount++);
// The capture was not acceptable or the enrollment operation
// failed.
if (FAILED(OperationStatus))
{
if (OperationStatus == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
wprintf_s(L"\n Swipe your finger to capture another sample.\n");
// Try again.
hr = WinBioEnrollCaptureWithCallback(
callbackContext->SessionHandle, // Open session handle
EnrollCaptureCallback, // Callback function
EnrollCallbackContext // Callback context
);
if (FAILED(hr))
{
wprintf_s(L"WinBioEnrollCaptureWithCallback failed.");
wprintf_s(L"hr = 0x%x\n", hr);
}
}
else
{
wprintf_s(L"EnrollCaptureCallback failed.");
wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus);
}
goto e_Exit;
}
// The enrollment operation requires more fingerprint swipes.
// This is normal and depends on your hardware. Typically, at least
// three swipes are required.
if (OperationStatus == WINBIO_I_MORE_DATA)
{
wprintf_s(L"\n More data required.");
wprintf_s(L"\n Swipe your finger on the sensor again.");
hr = WinBioEnrollCaptureWithCallback(
callbackContext->SessionHandle,
EnrollCaptureCallback,
EnrollCallbackContext
);
if (FAILED(hr))
{
wprintf_s(L"WinBioEnrollCaptureWithCallback failed. ");
wprintf_s(L"hr = 0x%x\n", hr);
}
goto e_Exit;
}
wprintf_s(L"\n Template completed\n");
e_Exit:
return;
}
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 |