Función WinBioAsyncOpenSession (winbio.h)

Se conecta de forma asincrónica a un proveedor de servicios biométricos y una o varias unidades biométricas. A partir de Windows 10, compilación 1607, esta función está disponible para su uso con una imagen móvil. Si se ejecuta correctamente, la función devuelve un identificador de sesión biométrica. Todas las operaciones realizadas mediante este identificador se completarán de forma asincrónica, incluido WinBioCloseSession, y los resultados se devolverán a la aplicación cliente mediante el método especificado en el parámetro NotificationMethod .

Para obtener una versión sincrónica de esta función, consulte WinBioOpenSession.

Sintaxis

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
);

Parámetros

[in] Factor

Máscara de bits de marcas de WINBIO_BIOMETRIC_TYPE que especifica los tipos de unidad biométrica que se van a enumerar. Actualmente solo se admite WINBIO_TYPE_FINGERPRINT .

[in] PoolType

Valor ULONG que especifica el tipo de las unidades biométricas que se usarán en la sesión. Puede ser uno de los siguientes valores:

Valor	Significado
WINBIO_POOL_SYSTEM	La sesión se conecta a una colección compartida de unidades biométricas administradas por el proveedor de servicios.
WINBIO_POOL_PRIVATE	La sesión se conecta a una colección de unidades biométricas administradas por el autor de la llamada.

[in] Flags

Valor ULONG que especifica la configuración de unidad biométrica y las características de acceso para la nueva sesión. Las marcas de configuración especifican la configuración general de unidades en la sesión. Las marcas de acceso especifican cómo usará la aplicación las unidades biométricas. Debe especificar una marca de configuración, pero puede combinar esa marca con cualquier marca de acceso.

Valor	Significado
WINBIO_FLAG_DEFAULT	Grupo: configuración Las unidades biométricas funcionan de la manera especificada durante la instalación. Debe usar este valor cuando se WINBIO_POOL_SYSTEM el parámetro PoolType.
WINBIO_FLAG_BASIC	Grupo: configuración Las unidades biométricas solo funcionan como dispositivos de captura básicos. Todos los complementos de software realizan todas las operaciones de procesamiento, coincidencia y almacenamiento.
WINBIO_FLAG_ADVANCED	Grupo: configuración Las unidades biométricas usan funcionalidades de procesamiento y almacenamiento internos.
WINBIO_FLAG_RAW	Grupo: acceso La aplicación cliente captura datos biométricos sin procesar mediante WinBioCaptureSample.
WINBIO_FLAG_MAINTENANCE	Grupo: acceso El cliente realiza operaciones de control definidas por el proveedor en una unidad biométrica mediante una llamada a WinBioControlUnitPrivileged.

[in, optional] UnitArray

Puntero a una matriz de identificadores de unidad biométrica que se incluirán en la sesión. Puede llamar a WinBioEnumBiometricUnits para enumerar las unidades biométricas. Establezca este valor en NULL si el parámetro PoolType está WINBIO_POOL_SYSTEM.

[in, optional] UnitCount

Valor que especifica el número de elementos de la matriz a la que apunta el parámetro UnitArray . Establezca este valor en cero si el parámetro PoolType está WINBIO_POOL_SYSTEM.

[in, optional] DatabaseId

Valor que especifica las bases de datos que va a usar la sesión. Si el parámetro PoolType es WINBIO_POOL_PRIVATE, debe especificar el GUID de una base de datos instalada. Si el parámetro PoolType no es WINBIO_POOL_PRIVATE, puede especificar uno de los siguientes valores comunes.

Valor	Significado
WINBIO_DB_DEFAULT	Cada unidad biométrica del grupo de sensores usa la base de datos predeterminada especificada en la configuración de unidad biométrica predeterminada. Debe especificar este valor si el parámetro PoolType está WINBIO_POOL_SYSTEM. No puede usar este valor si el parámetro PoolType es WINBIO_POOL_PRIVATE
WINBIO_DB_BOOTSTRAP	Puede especificar este valor que se usará para escenarios antes de iniciar Windows. Normalmente, la base de datos forma parte del chip del sensor o forma parte del BIOS y solo se puede usar para la inscripción y eliminación de plantillas.
WINBIO_DB_ONCHIP	La base de datos está en el chip del sensor y está disponible para la inscripción y la coincidencia.

[in] NotificationMethod

Especifica cómo se entregarán las notificaciones de finalización de operaciones asincrónicas en esta sesión biométrica a la aplicación cliente. Debe ser uno de los siguientes valores.

Valor	Significado
WINBIO_ASYNC_NOTIFY_CALLBACK	La sesión invoca la función de devolución de llamada definida por la aplicación.
WINBIO_ASYNC_NOTIFY_MESSAGE	La sesión publica un mensaje de ventana en la cola de mensajes de la aplicación.

[in, optional] TargetWindow

Identificador de la ventana que recibirá los avisos de finalización. Este valor se omite a menos que el parámetro NotificationMethod esté establecido en WINBIO_ASYNC_NOTIFY_MESSAGE.

[in, optional] MessageCode

Código de mensaje de ventana que el marco debe enviar para indicar los avisos de finalización. Este valor se omite a menos que el parámetro NotificationMethod esté establecido en WINBIO_ASYNC_NOTIFY_MESSAGE. El valor debe estar dentro del intervalo WM_APP(0x8000) para 0xBFFF.

Windows Biometric Framework establece el valor LPARAM del mensaje en la dirección de la estructura de WINBIO_ASYNC_RESULT que contiene los resultados de la operación. Debe llamar a WinBioFree para liberar la estructura una vez que haya terminado de usarlo.

[in, optional] CallbackRoutine

Dirección de la rutina de devolución de llamada que se invocará cuando se complete la operación iniciada mediante el identificador de sesión. Este valor se omite a menos que el parámetro NotificationMethod esté establecido en WINBIO_ASYNC_NOTIFY_CALLBACK.

[in, optional] UserData

Dirección de un búfer proporcionado por el autor de la llamada. El marco o la unidad biométrica no modifican el búfer. Se devuelve en la estructura WINBIO_ASYNC_RESULT . La aplicación puede usar los datos para ayudar a determinar qué acciones realizar al recibir el aviso de finalización o para mantener información adicional sobre la operación solicitada.

[in] AsynchronousOpen

Especifica si se va a bloquear hasta que se haya abierto la sesión del marco. Si se especifica FALSE , el proceso se bloqueará. Si se especifica TRUE , la sesión se abrirá de forma asincrónica.

Si especifica FALSE para abrir la sesión del marco de trabajo de forma sincrónica, esta función devuelve el resultado correcto o erróneo directamente al autor de la llamada en el valor devuelto HRESULT . Si la sesión se abre correctamente, el primer evento de finalización asincrónica que recibe la aplicación será para una operación asincrónica solicitada después de que se haya abierto el marco.

Si especifica TRUE para abrir la sesión del marco de trabajo de forma asincrónica, el primer aviso de finalización asincrónico recibido será para abrir el marco. Si el parámetro NotificationMethod se establece en WINBIO_ASYNC_NOTIFY_CALLBACK, los resultados de la operación se entregan a la estructura WINBIO_ASYNC_RESULT en la función de devolución de llamada especificada por el parámetro CallbackRoutine . Si el parámetro NotificationMethod se establece en WINBIO_ASYNC_NOTIFY_MESSAGE, los resultados de la operación se entregan a la estructura WINBIO_ASYNC_RESULT a la que apunta el campo LPARAM del mensaje de ventana.

[out, optional] SessionHandle

Si la función no se ejecuta correctamente, este parámetro será NULL.

Si la sesión se abre de forma sincrónica y correcta, este parámetro contendrá un puntero al identificador de sesión.

Si especifica que la sesión se abre de forma asincrónica, este método devuelve inmediatamente, el identificador de sesión será NULL y debe examinar la estructura de WINBIO_ASYNC_RESULT para determinar si la sesión se abrió correctamente.

Valor devuelto

Si la función se ejecuta correctamente, devuelve S_OK. Si se produce un error en la función, devuelve un valor HRESULT que indica el error. Entre los valores posibles se incluyen los que se indican en la tabla siguiente, entre otros. Para obtener una lista de códigos de error comunes, consulte Valores HRESULT comunes.

Código devuelto	Descripción
E_OUTOFMEMORY	No hay suficiente memoria disponible para crear la sesión biométrica.
E_INVALIDARG	Si establece el método de notificación en WINBIO_ASYNC_NOTIFY_MESSAGE, el parámetro TargetWindow no puede ser NULL ni HWND_BROADCAST y el parámetro MessageCode no puede ser cero (0).
E_POINTER	Se debe establecer el parámetro SessionHandle y el parámetro AsynchronousOpen . Si establece el método de notificación en WINBIO_ASYNC_NOTIFY_CALLBACK, también debe especificar la dirección de una función de devolución de llamada en el parámetro CallbackRoutine .
E_ACCESSDENIED	El parámetro Flags contiene el WINBIO_FLAG_RAW o la marca WINBIO_FLAG_MAINTENANCE y el autor de la llamada no se ha concedido ningún permiso de acceso.
WINBIO_E_INVALID_UNIT	Uno o varios de los números de unidad biométrica especificados en el parámetro UnitArray no son válidos.
WINBIO_E_NOT_ACTIVE_CONSOLE	La aplicación cliente se ejecuta en un cliente de Escritorio remoto e intenta abrir una sesión del grupo de sistemas.
WINBIO_E_SENSOR_UNAVAILABLE	El parámetro PoolType se establece en WINBIO_POOL_PRIVATE y uno o varios de los sensores solicitados en ese grupo no están disponibles.
WINBIO_E_DISABLED	La directiva administrativa actual prohíbe el uso de la API de Windows Biometric Framework.

Comentarios

El identificador de sesión devuelto por la función WinBioAsyncOpenSession se puede usar para generar notificaciones de finalización asincrónicas para cualquiera de las siguientes funciones:

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

El identificador de sesión devuelto por WinBioAsyncOpenSession no se puede usar con las siguientes funciones:

• WinBioCaptureSampleWithCallback
• WinBioEnrollCaptureWithCallback
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

Estas funciones, en primer lugar disponibles en Windows 7, tienen una firma de devolución de llamada incompatible y se desaconseja su uso en las nuevas aplicaciones. En su lugar, los desarrolladores que quieran devoluciones de llamada asincrónicas deben usar WinBioAsyncOpenSession con un notificationMethod de WINBIO_ASYNC_NOTIFY_CALLBACK.

El parámetro AsynchronousOpen determina solo si se bloqueará la operación abierta. Este parámetro no tiene ningún efecto en el comportamiento de finalización de las llamadas posteriores que usan el identificador de sesión.

Si establece el parámetro AsynchronousOpen en TRUE, esta función devolverá S_OK en cuanto haya realizado una validación inicial de los argumentos. Cualquier error detectado más allá de ese punto se notificará al autor de la llamada mediante el método especificado por el parámetro NotificationMethod . Es decir, un valor devuelto correcto indica solo que los parámetros WinBioAsyncOpenSession estaban bien y no que la operación abierta se realizó correctamente. Para determinar si la operación de apertura se realizó correctamente, debe examinar la estructura de WINBIO_ASYNC_RESULT .

Requisitos

Cliente mínimo compatible	Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbio.h (incluya Winbio.h)
Library	Winbio.lib
Archivo DLL	Winbio.dll

Consulte también

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession