Fonction WinBioCaptureSampleWithCallback (winbio.h)
Capture un échantillon biométrique de manière asynchrone et retourne les données brutes ou traitées dans un enregistrement d’informations biométriques (BIR). La fonction retourne immédiatement à l’appelant, capture l’exemple 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, à compter de Windows 8, de ne plus utiliser cette fonction 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 WinBioCaptureSample. 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 WinBioCaptureSampleWithCallback(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_BIR_PURPOSE Purpose,
[in] WINBIO_BIR_DATA_FLAGS Flags,
[in] PWINBIO_CAPTURE_CALLBACK CaptureCallback,
[in, optional] PVOID CaptureCallbackContext
);
Paramètres
[in] SessionHandle
Valeur WINBIO_SESSION_HANDLE qui identifie une session biométrique ouverte.
[in] Purpose
Masque de bits WINBIO_BIR_PURPOSE qui spécifie l’utilisation prévue de l’exemple. Il peut s’agir d’un OR au niveau du bit des valeurs suivantes :
- WINBIO_PURPOSE_VERIFY
- WINBIO_PURPOSE_IDENTIFY
- WINBIO_PURPOSE_ENROLL
- WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
- WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION
[in] Flags
Valeur qui spécifie le type de traitement à appliquer à l’exemple capturé. Il peut s’agir d’un OR au niveau du bit des indicateurs de niveau de sécurité et de traitement suivants :
- WINBIO_DATA_FLAG_PRIVACY
Chiffrez l’exemple.
- WINBIO_DATA_FLAG_INTEGRITY
Signez l’exemple ou protégez-le à l’aide d’un code d’authentification de message (MAC).
- WINBIO_DATA_FLAG_SIGNED
Si cet indicateur et le WINBIO_DATA_FLAG_INTEGRITYflag sont définis, signez l’exemple. Si cet indicateur n’est pas défini, mais que l’indicateur WINBIO_DATA_FLAG_INTEGRITY est défini, calculez un MAC.
- WINBIO_DATA_FLAG_RAW
Retourne l’exemple exactement tel qu’il a été capturé par le capteur.
- WINBIO_DATA_FLAG_INTERMEDIATE
Retourne l’exemple une fois qu’il a été nettoyé et filtré.
- WINBIO_DATA_FLAG_PROCESSED
Retourne l’exemple une fois qu’il est prêt à être utilisé pour l’objectif spécifié par le paramètre Purpose .
[in] CaptureCallback
Adresse d’une fonction de rappel qui sera appelée par la fonction WinBioCaptureSampleWithCallback lorsque l’opération de capture réussit ou échoue. Vous devez créer le rappel.
[in, optional] CaptureCallbackContext
Adresse d’une structure de données définie par l’application qui est passée à la fonction de rappel dans son paramètre CaptureCallbackContext . 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 |
|---|---|
|
L’appelant n’a pas l’autorisation de capturer des exemples bruts ou la session n’a pas été ouverte à l’aide de l’indicateur WINBIO_FLAG_RAW . |
|
Le handle de session n’est pas valide. |
|
L’unité biométrique ne prend pas en charge l’opération demandée. |
|
Les pointeurs UnitId, SampleSize et RejectDetail ne peuvent pas être NULL. |
|
L’opération n’a pas pu être effectuée, car l’unité biométrique est actuellement utilisée pour une transaction d’inscription (pool système uniquement). |
Remarques
La fonction WinBioCaptureSampleWithCallback capture des exemples de manière asynchrone. Pour appeler correctement cette fonction, le handle de session doit avoir été ouvert en spécifiant WINBIO_FLAG_RAW. Seuls les comptes Administrateurs et Système local disposent des privilèges nécessaires.
Les combinaisons valides des paramètres Objectif et Indicateurs dépendent des fonctionnalités de l’unité biométrique utilisée. Consultez la documentation du capteur du fournisseur pour déterminer les combinaisons prises en charge et leur impact sur les données capturées.
Les appelants sont responsables de la libération de la structure WINBIO_BIR retournée par le paramètre Sample .
La routine de rappel doit avoir la signature suivante :
VOID CALLBACK CaptureCallback(
__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
);
Exemples
L’exemple de code suivant capture un exemple de manière asynchrone en appelant WinBioCaptureSampleWithCallback et en passant un pointeur vers une fonction de rappel personnalisée. La fonction de rappel, CaptureSampleCallback, s’affiche également. Créez un lien vers la bibliothèque statique Winbio.lib et incluez les fichiers d’en-tête suivants :
- 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;
}
}
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 |