Partager via

Fonction WinBioAsyncOpenSession (winbio.h)

  • Article

Se connecte de façon asynchrone à un fournisseur de services biométriques et à une ou plusieurs unités biométriques. À compter de Windows 10, build 1607, cette fonction peut être utilisée avec une image mobile. Si elle réussit, la fonction retourne un handle de session biométrique. Chaque opération effectuée à l’aide de ce handle est effectuée de manière asynchrone, y compris WinBioCloseSession, et les résultats sont retournés à l’application cliente à l’aide de la méthode spécifiée dans le paramètre NotificationMethod .

Pour obtenir une version synchrone de cette fonction, consultez WinBioOpenSession.

Syntaxe

HRESULT WinBioAsyncOpenSession(
  [in]            WINBIO_BIOMETRIC_TYPE             Factor,
  [in]            WINBIO_POOL_TYPE                  PoolType,
  [in]            WINBIO_SESSION_FLAGS              Flags,
  [in, optional]  WINBIO_UNIT_ID                    *UnitArray,
  [in, optional]  SIZE_T                            UnitCount,
  [in, optional]  GUID                              *DatabaseId,
  [in]            WINBIO_ASYNC_NOTIFICATION_METHOD  NotificationMethod,
  [in, optional]  HWND                              TargetWindow,
  [in, optional]  UINT                              MessageCode,
  [in, optional]  PWINBIO_ASYNC_COMPLETION_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                             UserData,
  [in]            BOOL                              AsynchronousOpen,
  [out, optional] WINBIO_SESSION_HANDLE             *SessionHandle
);

Paramètres

[in] Factor

Masque de bits d’indicateurs WINBIO_BIOMETRIC_TYPE qui spécifie les types d’unités biométriques à énumérer. Seule WINBIO_TYPE_FINGERPRINT est actuellement prise en charge.

[in] PoolType

Valeur ULONG qui spécifie le type des unités biométriques qui seront utilisées dans la session. Il peut s’agir de l’une des valeurs suivantes :

Valeur Signification
WINBIO_POOL_SYSTEM
 La session se connecte à une collection partagée d’unités biométriques gérées par le fournisseur de services.
WINBIO_POOL_PRIVATE
 La session se connecte à une collection d’unités biométriques gérées par l’appelant.

[in] Flags

Valeur ULONG qui spécifie la configuration de l’unité biométrique et les caractéristiques d’accès pour la nouvelle session. Les indicateurs de configuration spécifient la configuration générale des unités dans la session. Les indicateurs d’accès spécifient comment l’application utilisera les unités biométriques. Vous devez spécifier un indicateur de configuration, mais vous pouvez combiner cet indicateur avec n’importe quel indicateur d’accès.

Valeur Signification
WINBIO_FLAG_DEFAULT
 Groupe : configuration

Les unités biométriques fonctionnent de la manière spécifiée lors de l’installation. Vous devez utiliser cette valeur lorsque le paramètre PoolType est WINBIO_POOL_SYSTEM.
WINBIO_FLAG_BASIC
 Groupe : configuration

Les unités biométriques fonctionnent uniquement comme des appareils de capture de base. Toutes les opérations de traitement, de correspondance et de stockage sont effectuées par des plug-ins logiciels.
WINBIO_FLAG_ADVANCED
 Groupe : configuration

Les unités biométriques utilisent des fonctionnalités de traitement et de stockage internes.
WINBIO_FLAG_RAW
 Groupe : accès

L’application cliente capture les données biométriques brutes à l’aide de WinBioCaptureSample.
WINBIO_FLAG_MAINTENANCE
 Groupe : accès

Le client effectue des opérations de contrôle définies par le fournisseur sur une unité biométrique en appelant WinBioControlUnitPrivileged.

[in, optional] UnitArray

Pointeur vers un tableau d’identificateurs d’unités biométriques à inclure dans la session. Vous pouvez appeler WinBioEnumBiometricUnits pour énumérer les unités biométriques. Définissez cette valeur sur NULL si le paramètre PoolType est WINBIO_POOL_SYSTEM.

[in, optional] UnitCount

Valeur qui spécifie le nombre d’éléments dans le tableau vers lequel pointe le paramètre UnitArray . Définissez cette valeur sur zéro si le paramètre PoolType est WINBIO_POOL_SYSTEM.

[in, optional] DatabaseId

Valeur qui spécifie la ou les bases de données à utiliser par la session. Si le paramètre PoolType est WINBIO_POOL_PRIVATE, vous devez spécifier le GUID d’une base de données installée. Si le paramètre PoolType n’est pas WINBIO_POOL_PRIVATE, vous pouvez spécifier l’une des valeurs communes suivantes.

Valeur Signification
WINBIO_DB_DEFAULT
 Chaque unité biométrique du pool de capteurs utilise la base de données par défaut spécifiée dans la configuration d’unité biométrique par défaut. Vous devez spécifier cette valeur si le paramètre PoolType est WINBIO_POOL_SYSTEM. Vous ne pouvez pas utiliser cette valeur si le paramètre PoolType est WINBIO_POOL_PRIVATE
WINBIO_DB_BOOTSTRAP
 Vous pouvez spécifier cette valeur à utiliser pour les scénarios avant le démarrage de Windows. En règle générale, la base de données fait partie de la puce du capteur ou fait partie du BIOS et ne peut être utilisée que pour l’inscription et la suppression de modèles.
WINBIO_DB_ONCHIP
 La base de données se trouve sur la puce du capteur et est disponible pour l’inscription et la correspondance.

[in] NotificationMethod

Spécifie comment les notifications d’achèvement des opérations asynchrones dans cette session biométrique doivent être remises à l’application cliente. Il doit s’agir de l’une des valeurs suivantes.

Valeur Signification
WINBIO_ASYNC_NOTIFY_CALLBACK
 La session appelle la fonction de rappel définie par l’application.
WINBIO_ASYNC_NOTIFY_MESSAGE
 La session publie un message de fenêtre dans la file d’attente des messages de l’application.

[in, optional] TargetWindow

Handle de la fenêtre qui recevra les avis d’achèvement. Cette valeur est ignorée, sauf si le paramètre NotificationMethod est défini sur WINBIO_ASYNC_NOTIFY_MESSAGE.

[in, optional] MessageCode

Code de message de fenêtre que l’infrastructure doit envoyer pour indiquer les avis d’achèvement. Cette valeur est ignorée, sauf si le paramètre NotificationMethod est défini sur WINBIO_ASYNC_NOTIFY_MESSAGE. La valeur doit se trouver dans la plage WM_APP(0x8000) à 0xBFFF.

L’infrastructure biométrique Windows définit la valeur LPARAM du message sur l’adresse de la structure WINBIO_ASYNC_RESULT qui contient les résultats de l’opération. Vous devez appeler WinBioFree pour libérer la structure une fois que vous avez terminé de l’utiliser.

[in, optional] CallbackRoutine

Adresse de la routine de rappel à appeler lorsque l’opération a démarré à l’aide du handle de session. Cette valeur est ignorée, sauf si le paramètre NotificationMethod est défini sur WINBIO_ASYNC_NOTIFY_CALLBACK.

[in, optional] UserData

Adresse d’une mémoire tampon fournie par l’appelant. La mémoire tampon n’est pas modifiée par l’infrastructure ou l’unité biométrique. Elle est retournée dans la structure WINBIO_ASYNC_RESULT . Votre application peut utiliser les données pour l’aider à déterminer les actions à effectuer à la réception de l’avis d’achèvement ou pour conserver des informations supplémentaires sur l’opération demandée.

[in] AsynchronousOpen

Spécifie s’il faut bloquer jusqu’à ce que la session d’infrastructure ait été ouverte. La spécification de FALSE entraîne le blocage du processus. La spécification de TRUE entraîne l’ouverture asynchrone de la session.

Si vous spécifiez FALSE pour ouvrir la session d’infrastructure de façon synchrone, la réussite ou l’échec est retourné directement à l’appelant par cette fonction dans la valeur de retour HRESULT . Si la session est ouverte correctement, le premier événement d’achèvement asynchrone que votre application reçoit concerne une opération asynchrone demandée après l’ouverture de l’infrastructure.

Si vous spécifiez TRUE pour ouvrir la session d’infrastructure de manière asynchrone, la première notification d’achèvement asynchrone reçue concerne l’ouverture de l’infrastructure. Si le paramètre NotificationMethod a la valeur WINBIO_ASYNC_NOTIFY_CALLBACK, les résultats de l’opération sont remis à la structure WINBIO_ASYNC_RESULT dans la fonction de rappel spécifiée par le paramètre CallbackRoutine . Si le paramètre NotificationMethod a la valeur WINBIO_ASYNC_NOTIFY_MESSAGE, les résultats de l’opération sont remis à la structure WINBIO_ASYNC_RESULT pointée par le champ LPARAM du message de fenêtre.

[out, optional] SessionHandle

Si la fonction échoue, ce paramètre est NULL.

Si la session est ouverte de manière synchrone et correctement, ce paramètre contient un pointeur vers le handle de session.

Si vous spécifiez que la session doit être ouverte de manière asynchrone, cette méthode retourne immédiatement, le handle de session sera NULL et vous devez examiner la structure WINBIO_ASYNC_RESULT pour déterminer si la session a été correctement ouverte.

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
E_OUTOFMEMORY
 La mémoire disponible est insuffisante pour créer la session biométrique.
E_INVALIDARG
 Si vous définissez la méthode de notification sur WINBIO_ASYNC_NOTIFY_MESSAGE, le paramètre TargetWindow ne peut pas être NULL ou HWND_BROADCAST et le paramètre MessageCode ne peut pas être égal à zéro (0).
E_POINTER
 Le paramètre SessionHandle et le paramètre AsynchroneOpen doivent être définis.

Si vous définissez la méthode de notification sur WINBIO_ASYNC_NOTIFY_CALLBACK, vous devez également spécifier l’adresse d’une fonction de rappel dans le paramètre CallbackRoutine .
E_ACCESSDENIED
 Le paramètre Flags contient l’indicateur WINBIO_FLAG_RAW ou WINBIO_FLAG_MAINTENANCE et l’appelant n’a pas reçu l’autorisation d’accès.
WINBIO_E_INVALID_UNIT
 Un ou plusieurs des numéros d’unité biométrique spécifiés dans le paramètre UnitArray ne sont pas valides.
WINBIO_E_NOT_ACTIVE_CONSOLE
 L’application cliente s’exécute sur un client Bureau à distance et tente d’ouvrir une session de pool système.
WINBIO_E_SENSOR_UNAVAILABLE
 Le paramètre PoolType est défini sur WINBIO_POOL_PRIVATE et un ou plusieurs des capteurs demandés dans ce pool ne sont pas disponibles.
WINBIO_E_DISABLED
 La stratégie d’administration actuelle interdit l’utilisation de l’API Du framework biométrique Windows.

Remarques

Le handle de session retourné par la fonction WinBioAsyncOpenSession peut être utilisé pour générer des notifications d’achèvement asynchrones pour l’une des fonctions suivantes :

Le handle de session retourné par WinBioAsyncOpenSession ne peut pas être utilisé avec les fonctions suivantes : Ces fonctions, d’abord disponibles dans Windows 7, ont une signature de rappel incompatible, et leur utilisation dans les nouvelles applications est déconseillée. Les développeurs qui souhaitent des rappels asynchrones doivent plutôt utiliser WinBioAsyncOpenSession avec notificationMethodde WINBIO_ASYNC_NOTIFY_CALLBACK.

Le paramètre AsynchroneOpen détermine uniquement si l’opération d’ouverture sera bloquée. Ce paramètre n’a aucun effet sur le comportement d’achèvement des appels suivants qui utilisent le handle de session.

Si vous définissez le paramètre AsynchroneOpen sur TRUE, cette fonction retourne S_OK dès qu’elle a effectué une validation initiale des arguments. Toutes les erreurs détectées au-delà de ce point sont signalées à l’appelant à l’aide de la méthode spécifiée par le paramètre NotificationMethod . Autrement dit, une valeur de retour réussie indique uniquement que les paramètres WinBioAsyncOpenSession étaient corrects et non que l’opération d’ouverture a réussi. Pour déterminer si l’opération d’ouverture a réussi, vous devez examiner la structure WINBIO_ASYNC_RESULT .

Configuration requise

   
Client minimal pris en charge Windows 8 [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2012 [applications de bureau uniquement]
Plateforme cible Windows
En-tête winbio.h (inclure Winbio.h)
Bibliothèque Winbio.lib
DLL Winbio.dll

Voir aussi

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession