Função WinBioAsyncOpenFramework (winbio.h)

  • Artigo

Abre um identificador para a estrutura biométrica. A partir do Windows 10, build 1607, essa função está disponível para uso com uma imagem móvel. Você pode usar esse identificador para enumerar de forma assíncrona unidades biométricas, bancos de dados e provedores de serviços e receber notificação assíncrona quando unidades biométricas forem anexadas ao computador ou removidas.

Sintaxe

HRESULT WinBioAsyncOpenFramework(
  [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]          WINBIO_FRAMEWORK_HANDLE           *FrameworkHandle
);

Parâmetros

[in] NotificationMethod

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

Valor Significado
WINBIO_ASYNC_NOTIFY_CALLBACK
 A estrutura invoca a função de retorno de chamada definida pelo aplicativo.
WINBIO_ASYNC_NOTIFY_MESSAGE
 A estrutura 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 para avisos de conclusão. 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] FrameworkHandle

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 de estrutura.
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 FrameworkHandle 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 .

Comentários

O identificador de estrutura retornado pela função WinBioAsyncOpenFramework pode ser usado para gerar notificações de conclusão assíncronas para as seguintes funções:

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 WinBioAsyncOpenFramework 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

WinBioAsyncOpenSession