Função WinBioAsyncOpenSession (winbio.h)

Conecta-se de forma assíncrona a um provedor de serviços biométricos e a uma ou mais unidades biométricas. A partir do Windows 10, build 1607, essa função está disponível para uso com uma imagem móvel. Se tiver êxito, a função retornará um identificador de sessão biométrica. Todas as operações executadas usando esse identificador serão concluídas de forma assíncrona, incluindo WinBioCloseSession, e os resultados serão retornados ao aplicativo cliente usando o método especificado no parâmetro NotificationMethod .

Para obter uma versão síncrona dessa função, consulte WinBioOpenSession.

Sintaxe

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

Uma máscara de bits de sinalizadores de WINBIO_BIOMETRIC_TYPE que especifica os tipos de unidade biométrica a serem enumerados. Somente WINBIO_TYPE_FINGERPRINT tem suporte no momento.

[in] PoolType

Um valor ULONG que especifica o tipo das unidades biométricas que serão usadas na sessão. Esse valor pode ser um dos seguintes:

Valor	Significado
WINBIO_POOL_SYSTEM	A sessão se conecta a uma coleção compartilhada de unidades biométricas gerenciadas pelo provedor de serviços.
WINBIO_POOL_PRIVATE	A sessão se conecta a uma coleção de unidades biométricas gerenciadas pelo chamador.

[in] Flags

Um valor ULONG que especifica as características de configuração e acesso da unidade biométrica para a nova sessão. Os sinalizadores de configuração especificam a configuração geral das unidades na sessão. Os sinalizadores de acesso especificam como o aplicativo usará as unidades biométricas. Você deve especificar um sinalizador de configuração, mas pode combinar esse sinalizador com qualquer sinalizador de acesso.

Valor	Significado
WINBIO_FLAG_DEFAULT	Grupo: configuração As unidades biométricas operam da maneira especificada durante a instalação. Você deve usar esse valor quando o parâmetro PoolType for WINBIO_POOL_SYSTEM.
WINBIO_FLAG_BASIC	Grupo: configuração As unidades biométricas operam apenas como dispositivos de captura básicos. Todas as operações de processamento, correspondência e armazenamento são executadas por plug-ins de software.
WINBIO_FLAG_ADVANCED	Grupo: configuração As unidades biométricas usam recursos internos de processamento e armazenamento.
WINBIO_FLAG_RAW	Grupo: acesso O aplicativo cliente captura dados biométricos brutos usando WinBioCaptureSample.
WINBIO_FLAG_MAINTENANCE	Grupo: acesso O cliente executa operações de controle definidas pelo fornecedor em uma unidade biométrica chamando WinBioControlUnitPrivileged.

[in, optional] UnitArray

Ponteiro para uma matriz de identificadores de unidade biométrica a serem incluídos na sessão. Você pode chamar WinBioEnumBiometricUnits para enumerar as unidades biométricas. Defina esse valor como NULL se o parâmetro PoolType for WINBIO_POOL_SYSTEM.

[in, optional] UnitCount

Um valor que especifica o número de elementos na matriz apontada pelo parâmetro UnitArray . Defina esse valor como zero se o parâmetro PoolType for WINBIO_POOL_SYSTEM.

[in, optional] DatabaseId

Um valor que especifica os bancos de dados a serem usados pela sessão. Se o parâmetro PoolType for WINBIO_POOL_PRIVATE, você deverá especificar o GUID de um banco de dados instalado. Se o parâmetro PoolType não for WINBIO_POOL_PRIVATE, você poderá especificar um dos valores comuns a seguir.

Valor	Significado
WINBIO_DB_DEFAULT	Cada unidade biométrica no pool de sensores usa o banco de dados padrão especificado na configuração de unidade biométrica padrão. Você deve especificar esse valor se o parâmetro PoolType for WINBIO_POOL_SYSTEM. Você não poderá usar esse valor se o parâmetro PoolType for WINBIO_POOL_PRIVATE
WINBIO_DB_BOOTSTRAP	Você pode especificar esse valor a ser usado para cenários antes de iniciar o Windows. Normalmente, o banco de dados faz parte do chip do sensor ou faz parte do BIOS e só pode ser usado para registro e exclusão de modelo.
WINBIO_DB_ONCHIP	O banco de dados está no chip do sensor e está disponível para registro e correspondência.

[in] NotificationMethod

Especifica como as notificações de conclusão para operações assíncronas nesta sessão biométrica devem ser entregues ao aplicativo cliente. Esse deve ser um dos valores a seguir.

Valor	Significado
WINBIO_ASYNC_NOTIFY_CALLBACK	A sessão invoca a função de retorno de chamada definida pelo aplicativo.
WINBIO_ASYNC_NOTIFY_MESSAGE	A sessão posta uma mensagem de janela na fila de mensagens do aplicativo.

[in, optional] TargetWindow

Identificador da janela que receberá os avisos de conclusão. Esse valor é ignorado, a menos que o parâmetro NotificationMethod seja definido como WINBIO_ASYNC_NOTIFY_MESSAGE.

[in, optional] MessageCode

Código de mensagem de janela que a estrutura deve enviar para significar avisos de conclusão. Esse valor é ignorado, a menos que o parâmetro NotificationMethod seja definido como WINBIO_ASYNC_NOTIFY_MESSAGE. O valor deve estar dentro do intervalo WM_APP(0x8000) para 0xBFFF.

A Estrutura Biométrica do Windows define o valor LPARAM da mensagem como o endereço da estrutura WINBIO_ASYNC_RESULT que contém os resultados da operação. Você deve chamar WinBioFree para liberar a estrutura depois de terminar de usá-la.

[in, optional] CallbackRoutine

Endereço da rotina de retorno de chamada a ser invocado quando a operação iniciada usando o identificador de sessão for concluída. Esse valor é ignorado, a menos que o parâmetro NotificationMethod esteja definido como WINBIO_ASYNC_NOTIFY_CALLBACK.

[in, optional] UserData

Endereço de um buffer fornecido pelo chamador. O buffer não é modificado pela estrutura ou pela unidade biométrica. Ele é retornado na estrutura WINBIO_ASYNC_RESULT . Seu aplicativo pode usar os dados para ajudá-lo a determinar quais ações executar após o recebimento do aviso de conclusão ou para manter informações adicionais sobre a operação solicitada.

[in] AsynchronousOpen

Especifica se deve ser bloqueado até que a sessão da estrutura seja aberta. Especificar FALSE faz com que o processo seja bloqueado. Especificar TRUE faz com que a sessão seja aberta de forma assíncrona.

Se você especificar FALSE para abrir a sessão da estrutura de forma síncrona, êxito ou falha será retornado ao chamador diretamente por essa função no valor retornado hresult . Se a sessão for aberta com êxito, o primeiro evento de conclusão assíncrona recebido pelo aplicativo será para uma operação assíncrona solicitada após a abertura da estrutura.

Se você especificar TRUE para abrir a sessão da estrutura de forma assíncrona, o primeiro aviso de conclusão assíncrono recebido será para abrir a estrutura. Se o parâmetro NotificationMethod estiver definido como WINBIO_ASYNC_NOTIFY_CALLBACK, os resultados da operação serão entregues à estrutura WINBIO_ASYNC_RESULT na função de retorno de chamada especificada pelo parâmetro CallbackRoutine . Se o parâmetro NotificationMethod estiver definido como WINBIO_ASYNC_NOTIFY_MESSAGE, os resultados da operação serão entregues à estrutura WINBIO_ASYNC_RESULT apontada pelo campo LPARAM da mensagem da janela.

[out, optional] SessionHandle

Se a função não for bem-sucedida, esse parâmetro será NULL.

Se a sessão for aberta de forma síncrona e bem-sucedida, esse parâmetro conterá um ponteiro para o identificador de sessão.

Se você especificar que a sessão seja aberta de forma assíncrona, esse método retornará imediatamente, o identificador de sessão será NULL e você deverá examinar a estrutura WINBIO_ASYNC_RESULT para determinar se a sessão foi aberta com êxito.

Valor retornado

Se a função for bem-sucedida, ela retornará S_OK. Se a função falhar, ela retornará um valor HRESULT que indica o erro. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir. Para obter uma lista de códigos de erro comuns, consulte Valores HRESULT comuns.

Código de retorno	Descrição
E_OUTOFMEMORY	Não há memória suficiente disponível para criar a sessão biométrica.
E_INVALIDARG	Se você definir o método de notificação como WINBIO_ASYNC_NOTIFY_MESSAGE, o parâmetro TargetWindow não poderá ser NULL ou HWND_BROADCAST e o parâmetro MessageCode não poderá ser zero (0).
E_POINTER	O parâmetro SessionHandle e o parâmetro AsynchronousOpen devem ser definidos . Se você definir o método de notificação como WINBIO_ASYNC_NOTIFY_CALLBACK, também deverá especificar o endereço de uma função de retorno de chamada no parâmetro CallbackRoutine .
E_ACCESSDENIED	O parâmetro Flags contém a WINBIO_FLAG_RAW ou o sinalizador WINBIO_FLAG_MAINTENANCE e o chamador não recebeu nenhuma permissão de acesso.
WINBIO_E_INVALID_UNIT	Um ou mais dos números de unidade biométrica especificados no parâmetro UnitArray não são válidos.
WINBIO_E_NOT_ACTIVE_CONSOLE	O aplicativo cliente está em execução em um cliente de área de trabalho remota e está tentando abrir uma sessão de pool do sistema.
WINBIO_E_SENSOR_UNAVAILABLE	O parâmetro PoolType é definido como WINBIO_POOL_PRIVATE e um ou mais dos sensores solicitados nesse pool não estão disponíveis.
WINBIO_E_DISABLED	A política administrativa atual proíbe o uso da API do Windows Biometric Framework.

Comentários

O identificador de sessão retornado pela função WinBioAsyncOpenSession pode ser usado para gerar notificações de conclusão assíncronas para qualquer uma das seguintes funções:

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

O identificador de sessão retornado por WinBioAsyncOpenSession não pode ser usado com as seguintes funções:

• WinBioCaptureSampleWithCallback
• WinBioEnrollCaptureWithCallback
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

Essas funções, primeiramente disponíveis no Windows 7, têm uma assinatura de retorno de chamada incompatível e seu uso em novos aplicativos é desencorajado. Os desenvolvedores que desejam retornos de chamada assíncronos devem usar WinBioAsyncOpenSession com um NotificationMethod de WINBIO_ASYNC_NOTIFY_CALLBACK.

O parâmetro AsynchronousOpen determina apenas se a operação aberta será bloqueada. Esse parâmetro não tem efeito sobre o comportamento de conclusão de chamadas subsequentes que usam o identificador de sessão.

Se você definir o parâmetro AsynchronousOpen como TRUE, essa função retornará S_OK assim que tiver executado uma validação inicial dos argumentos. Todos os erros detectados além desse ponto serão relatados ao chamador usando o método especificado pelo parâmetro NotificationMethod . Ou seja, um valor retornado bem-sucedido indica apenas que os parâmetros WinBioAsyncOpenSession foram bons e não que a operação aberta foi bem-sucedida. Para determinar se a operação aberta foi bem-sucedida, você deve examinar a estrutura WINBIO_ASYNC_RESULT .

Requisitos

Cliente mínimo com suporte	Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winbio.h (inclua Winbio.h)
Biblioteca	Winbio.lib
DLL	Winbio.dll

Confira também

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession