Função WinBioLocateSensorWithCallback (winbio.h)

Artigo
03/03/2024

Recupera de forma assíncrona o número de ID da unidade biométrica selecionada interativamente por um usuário. A função retorna imediatamente ao chamador, processa em um thread separado e relata a unidade biométrica selecionada chamando uma função de retorno de chamada definida pelo aplicativo.

Importante

Recomendamos que, começando com Windows 8, você não use mais essa função para iniciar uma operação assíncrona. Em vez disso, faça o seguinte:

Implemente uma função PWINBIO_ASYNC_COMPLETION_CALLBACK para receber aviso quando a operação for concluída.
Chame a função WinBioAsyncOpenSession . Passe o endereço do retorno de chamada no parâmetro CallbackRoutine . Passe WINBIO_ASYNC_NOTIFY_CALLBACK no parâmetro NotificationMethod . Recupere um identificador de sessão assíncrono.
Use o identificador de sessão assíncrona para chamar WinBioLocateSensor. Quando a operação for concluída, a Estrutura Biométrica do Windows alocará e inicializará uma estrutura WINBIO_ASYNC_RESULT com os resultados e invocará o retorno de chamada com um ponteiro para a estrutura de resultados.
Chame WinBioFree de sua implementação de retorno de chamada para liberar a estrutura WINBIO_ASYNC_RESULT depois de terminar de usá-la.

Sintaxe

HRESULT WinBioLocateSensorWithCallback(
  [in]           WINBIO_SESSION_HANDLE          SessionHandle,
  [in]           PWINBIO_LOCATE_SENSOR_CALLBACK LocateCallback,
  [in, optional] PVOID                          LocateCallbackContext
);

Parâmetros

[in] SessionHandle

Um valor WINBIO_SESSION_HANDLE que identifica uma sessão biométrica aberta.

[in] LocateCallback

Endereço de uma função de retorno de chamada que será chamada pela função WinBioLocateSensorWithCallback quando o local do sensor for bem-sucedido ou falhar. Você deve criar o retorno de chamada.

[in, optional] LocateCallbackContext

Endereço de uma estrutura de dados definida pelo aplicativo que é passada para a função de retorno de chamada em seu parâmetro LocateCallbackContext . Essa estrutura pode conter todos os dados que a função de retorno de chamada personalizada foi projetada para manipular.

Retornar valor

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_HANDLE	O identificador de sessão não é válido.
E_POINTER	O endereço especificado pelo parâmetro LocateCallback não pode ser NULL.

Comentários

Você pode usar essa função em sistemas com vários sensores para determinar qual sensor é preferencial para registro pelo usuário. Nenhuma informação de identificação é retornada por essa função. Ele é fornecido apenas para indicar a seleção do sensor de usuário.

Se o parâmetro SessionHandle se referir ao pool de sensores do sistema, a função de retorno de chamada não será chamada até que o aplicativo adquira o foco da janela e o usuário tenha fornecido uma amostra biométrica. A maneira como você adquire o foco depende do tipo de aplicativo que você está escrevendo. Por exemplo, se você estiver criando um aplicativo gui, poderá implementar um manipulador de mensagens que captura um WM_ACTIVATE, WM_SETFOCUS ou outra mensagem apropriada. Se você estiver escrevendo um aplicativo CUI, chame GetConsoleWindow para recuperar um identificador para a janela do console e passe esse identificador para a função SetForegroundWindow para forçar a janela do console para o primeiro plano e atribuí-lo ao foco. Se o aplicativo estiver em execução em um processo desanexado e não tiver janela ou for um serviço do Windows, use WinBioAcquireFocus e WinBioReleaseFocus para controlar manualmente o foco.

A rotina de retorno de chamada deve ter a seguinte assinatura:


VOID CALLBACK LocateCallback(
__in_opt PVOID LocateCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId
);

Exemplos

A função a seguir chama WinBioLocateSensorWithCallback para localizar o sensor biométrico. O WinBioLocateSensorWithCallback é uma função assíncrona que configura o subsistema biométrico para localizar o sensor em outro thread. A saída do subsistema biométrico é enviada para uma função de retorno de chamada personalizada chamada LocateSensorCallback. Link para a biblioteca estática Winbio.lib e inclua os seguintes arquivos de cabeçalho:

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT LocateSensorWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_DEFAULT,        // Configuration and access
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            NULL,                       // Database ID
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    wprintf_s(L"\n Calling WinBioLocateSensorWithCallback.");
    hr = WinBioLocateSensorWithCallback(
                sessionHandle,          // Open biometric session
                LocateSensorCallback,   // Callback function
                NULL                    // Optional context
                );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensorWithCallback failed.");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the identification if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...\n");
        Sleep( 7000 );

        wprintf_s(L"\n Calling WinBioCancel\n");
        hr = WinBioCancel( sessionHandle );
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioCancel failed. hr = 0x%x\n", hr);
            goto e_Exit;
        }
    }

    // Wait for the asynchronous identification process to complete 
    // or be canceled.
    hr = WinBioWait( sessionHandle );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
    }

e_Exit:

    if (sessionHandle != NULL)
    {
       wprintf_s(L"\n Closing the session.\n");

        hr = WinBioCloseSession(sessionHandle);
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioCloseSession failed. hr = 0x%x\n", hr);
        }
        sessionHandle = NULL;
    }

    wprintf_s(L"\n Hit any key to exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for 
// WinBioLocateSensorWithCallback. The function filters the response 
// from the biometric subsystem and writes a result to the console window.
// 
VOID CALLBACK LocateSensorCallback(
    __in_opt PVOID LocateCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId
    )
{
    UNREFERENCED_PARAMETER(LocateCallbackContext);

    wprintf_s(L"\n LocateSensorCallback executing.");

    // A sensor could not be located.
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n LocateSensorCallback failed.");
        wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus);
    }
    // A sensor was located.
    else
    {
        wprintf_s(L"\n Selected unit ID: %d\n", UnitId);
    }
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 R2 [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

WinBioLocateSensor

Compartilhar via

Função WinBioLocateSensorWithCallback (winbio.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Exemplos

Requisitos

Confira também

Comentários

Recursos adicionais