WinBioAsyncOpenSession, fonction (winbio.h)

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 est disponible pour ê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 des indicateurs de 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 :

[in] Flags

Valeur ULONG qui spécifie la configuration d’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 la façon dont 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.

[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 pointé par 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 courantes suivantes.

[in] NotificationMethod

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

[in, optional] TargetWindow

Handle of the window that will receive the completion notices. 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 signer 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.

Le Framework biométrique Windows définit la valeur LPARAM du message à 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 fini de l’utiliser.

[in, optional] CallbackRoutine

Adresse de la routine de rappel à appeler une fois l’opération démarrée à l’aide du handle de session terminé. 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 lors de 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 de framework de manière 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 avec succès, le premier événement d’achèvement asynchrone reçu par votre application est destiné à 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 sera destinée à ouvrir l’infrastructure. Si le paramètre NotificationMethod est défini sur 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 est défini sur 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 ne réussit pas, ce paramètre est NULL.

Si la session est ouverte de façon synchrone et réussie, ce paramètre contient un pointeur vers le handle de session.

Si vous spécifiez que la session est ouverte de façon asynchrone, cette méthode retourne immédiatement, le handle de session est 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 incluent, mais ne sont pas limitées à celles du tableau suivant. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.

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 :

• WinBioCancel
• WinBioCaptureSample
• WinBioCloseSession
• WinBioControlUnit
• WinBioControlUnitPrivileged
• WinBioDeleteTemplate
• WinBioEnrollBegin
• WinBioEnrollCapture
• WinBioEnrollCommit
• WinBioEnrollDiscard
• WinBioEnumEnrollments
• WinBioGetProperty
• WinBioIdentify
• WinBioLocateSensor
• WinBioLockUnit
• WinBioLogonIdentifiedUser
• WinBioRegisterEventMonitor
• WinBioUnlockUnit
• WinBioUnregisterEventMonitor
• WinBioVerify
• WinBioWait

• WinBioCaptureSampleWithCallback
• WinBioEnrollCaptureWithCallback
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

Le paramètre AsynchroneOpen détermine uniquement si l’opération d’ouverture se bloque. 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 ouverte a réussi. Pour déterminer si l’opération ouverte a réussi, vous devez examiner la structure WINBIO_ASYNC_RESULT .

Spécifications

Voir aussi

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession