WinBioRegisterEventMonitor, fonction (winbio.h)
La fonction WinBioRegisterEventMonitor inscrit une fonction de rappel pour recevoir des notifications d’événements du fournisseur de services associé à une session ouverte.
Syntaxe
HRESULT WinBioRegisterEventMonitor(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_EVENT_TYPE EventMask,
[in] PWINBIO_EVENT_CALLBACK EventCallback,
[in] PVOID EventCallbackContext
);
Paramètres
[in] SessionHandle
Valeur WINBIO_SESSION_HANDLE qui identifie la session biométrique ouverte. Ouvrez le handle de session en appelant WinBioOpenSession.
[in] EventMask
Valeur qui spécifie les types d’événements à surveiller. Seul le fournisseur d’empreintes digitales est actuellement pris en charge. Vous devez spécifier l’un des indicateurs suivants.
- WINBIO_EVENT_FP_UNCLAIMED
Le capteur a détecté un mouvement de balayage du doigt qui n’a pas été demandé par l’application, ou l’application qui demande n’a pas de focus sur la fenêtre. L’infrastructure biométrique Windows appelle votre fonction de rappel pour indiquer qu’un balayage du doigt s’est produit, mais qu’il n’essaie pas d’identifier l’empreinte digitale.
- WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY
Le capteur a détecté un mouvement de balayage du doigt qui n’a pas été demandé par l’application, ou l’application qui demande n’a pas de focus sur la fenêtre. L’infrastructure biométrique Windows tente d’identifier l’empreinte digitale et transmet le résultat de ce processus à votre fonction de rappel.
[in] EventCallback
Adresse d’une fonction de rappel qui reçoit les notifications d’événements envoyées par l’infrastructure biométrique Windows. Vous devez définir cette fonction.
[in] EventCallbackContext
Valeur facultative définie par l’application qui est retournée dans le paramètre pvContext de la fonction de rappel. Cette valeur 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 handle de session n’est pas valide. |
|
L’adresse de la fonction de rappel spécifiée par le paramètre EventCallback ne peut pas être NULL. |
|
Le paramètre EventMask ne peut pas être égal à zéro et vous ne pouvez pas spécifier à la fois WINBIO_EVENT_FP_UNCLAIMED et WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY en même temps. |
|
Un moniteur d’événements actif a déjà été inscrit. |
|
Le fournisseur de services ne prend pas en charge la notification d’événement. |
Remarques
Cette fonction est uniquement valide pour les sessions connectées à un pool de capteurs système.
Les rappels d’événements sont remis à l’application cliente en série. Par conséquent, les notifications d’événements suivantes ne sont pas remises tant que le client n’est pas retourné à partir du rappel actuel. Les événements qui se produisent pendant qu’un rappel est en cours d’exécution peuvent être ignorés par le système. Pour éviter de perdre des événements, vous ne devez pas effectuer de travail fastidieux dans votre routine de rappel.
L’application cliente doit être prête à recevoir des événements dès que WinBioRegisterEventMonitor est appelé. L’application doit appeler WinBioFree pour libérer la structure retournée dans l’argument Event du rappel. Si vous ne le faites pas, cela entraîne une fuite de mémoire dans le processus appelant.
Une fois qu’un moniteur d’événements a été démarré, la session à laquelle le moniteur est associé ne pourra pas traiter d’autres appels d’API de l’infrastructure biométrique Windows tant que le moniteur d’événements n’a pas été arrêté. Si votre application doit effectuer d’autres appels d’API tout en recevant toujours des notifications de moniteur d’événements, vous devez ouvrir deux sessions : l’une pour le moniteur d’événements et l’autre pour d’autres opérations.
Appelez WinBioUnregisterEventMonitor pour arrêter d’envoyer des notifications d’événements à votre fonction de rappel.
Si une application inscrit un moniteur d’événements WinBio et laisse ce moniteur actif pendant un cycle veille/veille, les systèmes qui implémentent des fonctionnalités d’authentification biométrique avant démarrage (PBA) ou d’authentification unique peuvent ne pas toujours fonctionner. Le problème est que l’appel biométrique PBA est intercepté par le moniteur d’événements avant que le fournisseur d’informations d’identification biométriques du système ait la possibilité d’effectuer sa première opération WinBioIdentify . Les applications qui utilisent la fonctionnalité de surveillance des événements WinBio doivent annuler l’inscription de leurs moniteurs avant la mise en veille du système et les réinscrire après la mise en éveil du système. Pour plus d’informations sur la gestion des événements pendant les changements d’état d’alimentation, consultez À propos de la gestion de l’alimentation.
La routine de rappel doit avoir la signature suivante :
VOID CALLBACK EventCallback(
__in_opt PVOID EventCallbackContext,
__in HRESULT OperationStatus,
__in PWINBIO_EVENT Event
);
Exemples
La fonction suivante inscrit un moniteur d’événements en appelant la fonction WinBioRegisterEventMonitor et en transmettant l’adresse d’une routine de rappel. Le rappel, également inclus, reçoit des notifications d’événements de l’infrastructure biométrique Windows. 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 RegisterSystemEventMonitor(BOOL bCancel)
{
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 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 WinBioOpenSession failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Call the WinBioRegisterEventMonitor function.
wprintf_s(L"\n Calling WinBioRegisterEventMonitor.\n");
hr = WinBioRegisterEventMonitor(
sessionHandle, // Open session handle
WINBIO_EVENT_FP_UNCLAIMED, // Events to monitor
EventMonitorCallback, // Callback function
NULL // Optional context.
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioRegisterEventMonitor failed.");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Waiting for an event.\n");
// Cancel the identification 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 an event to happen.
//wprintf_s(L"\n Swipe the sensor to receive an event notice ");
//wprintf_s(L"\n or press any key to stop waiting...\n");
wprintf_s(L"\n Swipe the sensor one or more times ");
wprintf_s(L"to generate events.");
wprintf_s(L"\n When done, press a key to exit...\n");
_getch();
// Unregister the event monitor.
wprintf_s(L"\n Calling WinBioUnregisterEventMonitor\n");
hr = WinBioUnregisterEventMonitor( sessionHandle);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioUnregisterEventMonitor failed.");
wprintf_s(L"hr = 0x%x\n", hr);
}
e_Exit:
if (sessionHandle != NULL)
{
wprintf_s(L"\n Closing the session.\n");
hr = WinBioCloseSession(sessionHandle);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioCloseSession failed. hr = 0x%x\n", hr);
}
sessionHandle = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function is the callback for WinBioRegisterEventMonitor.
// The function filters any event notice from the biometric subsystem and
// writes a result to the console window.
//
VOID CALLBACK EventMonitorCallback(
__in_opt PVOID EventCallbackContext,
__in HRESULT OperationStatus,
__in PWINBIO_EVENT Event
)
{
UNREFERENCED_PARAMETER(EventCallbackContext);
wprintf_s(L"\n EventMonitorCallback executing.");
// Failure.
if (FAILED(OperationStatus))
{
wprintf_s(L"\n EventMonitorCallback failed. ");
wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
goto e_Exit;
}
// An event notice was received.
if (Event != NULL)
{
wprintf_s(L"\n MonitorEvent: ");
switch (Event->Type)
{
case WINBIO_EVENT_FP_UNCLAIMED:
wprintf_s(L"WINBIO_EVENT_FP_UNCLAIMED");
wprintf_s(L"\n Unit ID: %d",
Event->Parameters.Unclaimed.UnitId);
wprintf_s(L"\n Reject detail: %d\n",
Event->Parameters.Unclaimed.RejectDetail);
break;
case WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY:
wprintf_s(L"WINBIO_EVENT_FP_UNCLAIMED_IDENTIFY");
wprintf_s(L"\n Unit ID: %d",
Event->Parameters.UnclaimedIdentify.UnitId);
wprintf_s(L"\n Reject detail: %d\n",
Event->Parameters.UnclaimedIdentify.RejectDetail);
break;
case WINBIO_EVENT_ERROR:
wprintf_s(L"WINBIO_EVENT_ERROR\n");
break;
default:
wprintf_s(L"(0x%08x - Invalid type)\n", Event->Type);
break;
}
}
e_Exit:
if (Event != NULL)
{
//wprintf_s(L"\n Press any key to continue...\n");
WinBioFree(Event);
Event = NULL;
}
}
Configuration requise
| 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 |