Fonction WinBioEnrollCaptureWithCallback (winbio.h)
Capture de manière asynchrone un exemple biométrique et l’ajoute à un modèle. La fonction retourne immédiatement à l’appelant, effectue l’inscription sur un thread distinct et appelle une fonction de rappel définie par l’application pour mettre à jour l’opération status.
Nous vous recommandons de ne plus utiliser cette fonction à partir de Windows 8 pour démarrer une opération asynchrone. Au lieu de cela, procédez comme suit :
- Implémentez une fonction PWINBIO_ASYNC_COMPLETION_CALLBACK pour recevoir une notification à la fin de l’opération.
- Appelez la fonction WinBioAsyncOpenSession . Transmettez l’adresse de votre rappel dans le paramètre CallbackRoutine . Passez WINBIO_ASYNC_NOTIFY_CALLBACK dans le paramètre NotificationMethod . Récupérer un handle de session asynchrone.
- Utilisez le handle de session asynchrone pour appeler WinBioEnrollCapture. Une fois l’opération terminée, l’infrastructure biométrique Windows alloue et initialise une structure WINBIO_ASYNC_RESULT avec les résultats et appelle votre rappel avec un pointeur vers la structure des résultats.
- Appelez WinBioFree à partir de votre implémentation de rappel pour libérer la structure WINBIO_ASYNC_RESULT une fois que vous avez terminé de l’utiliser.
Syntaxe
HRESULT WinBioEnrollCaptureWithCallback(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] PWINBIO_ENROLL_CAPTURE_CALLBACK EnrollCallback,
[in, optional] PVOID EnrollCallbackContext
);
Paramètres
[in] SessionHandle
Valeur WINBIO_SESSION_HANDLE qui identifie une session biométrique ouverte.
[in] EnrollCallback
Adresse d’une fonction de rappel qui sera appelée par la fonction WinBioEnrollCaptureWithCallback lorsque l’opération de capture réussit ou échoue. Vous devez créer le rappel.
[in, optional] EnrollCallbackContext
Pointeur vers une structure facultative définie par l’application qui est passée au paramètre EnrollCallbackContext de la fonction de rappel. Cette structure peut contenir toutes les données que la fonction de rappel personnalisée est conçue pour gérer.
Valeur retournée
Si la fonction réussit, elle retourne S_OK. Si la fonction échoue, elle retourne une valeur HRESULT qui indique l’erreur. Les valeurs possibles sont notamment celles figurant dans le tableau suivant. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.
| Code de retour | Description |
|---|---|
|
Le compte appelant n’est pas autorisé à effectuer l’inscription. |
|
Le handle de session n’est pas valide. |
|
Le pointeur spécifié par le paramètre EnrollCallback ne peut pas être NULL. |
Remarques
Si le paramètre SessionHandle fait référence au pool de capteurs système, la fonction de rappel n’est pas appelée tant que l’application n’aura pas acquis le focus de fenêtre et que l’utilisateur n’aura pas fourni un échantillon biométrique. La façon dont vous obtenez le focus dépend du type d’application que vous écrivez. Par exemple, si vous créez une application GUI, vous pouvez implémenter un gestionnaire de messages qui capture un WM_ACTIVATE, un WM_SETFOCUS ou un autre message approprié. Si vous écrivez une application CUI, appelez GetConsoleWindow pour récupérer un handle dans la fenêtre de console et passez ce handle à la fonction SetForegroundWindow pour forcer la fenêtre de console au premier plan et lui affecter le focus. Si votre application s’exécute dans un processus détaché et n’a pas de fenêtre ou s’il s’agit d’un service Windows, utilisez WinBioAcquireFocus et WinBioReleaseFocus pour contrôler manuellement le focus.
Exemples
L’exemple de code suivant inscrit une empreinte digitale de manière asynchrone en appelant WinBioEnrollCaptureWithCallback et en passant un pointeur vers une fonction de rappel personnalisée. La fonction de rappel, EnrollCaptureCallback, est également affichée. Lien vers la bibliothèque statique Winbio.lib.
//------------------------------------------------------------------------
// 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;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 7 [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 R2 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winbio.h (inclure Winbio.h) |
| Bibliothèque | Winbio.lib |
| DLL | Winbio.dll |