Função WinBioCaptureSampleWithCallback (winbio.h)

Artigo
08/27/2023

Captura uma amostra biométrica de forma assíncrona e retorna os dados brutos ou processados em um BIR (registro de informações biométricas). A função retorna imediatamente ao chamador, captura o exemplo em um thread separado e chama uma função de retorno de chamada definida pelo aplicativo para atualizar a operação status.

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 WinBioCaptureSample. 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 WinBioCaptureSampleWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_BIR_PURPOSE       Purpose,
  [in]           WINBIO_BIR_DATA_FLAGS    Flags,
  [in]           PWINBIO_CAPTURE_CALLBACK CaptureCallback,
  [in, optional] PVOID                    CaptureCallbackContext
);

Parâmetros

[in] SessionHandle

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

[in] Purpose

Uma máscara de bits WINBIO_BIR_PURPOSE que especifica o uso pretendido do exemplo. Isso pode ser um OR bit a bit dos seguintes valores:

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

Um valor que especifica o tipo de processamento a ser aplicado ao exemplo capturado. Isso pode ser um OR bit a bit dos seguintes sinalizadores de nível de segurança e processamento:

WINBIO_DATA_FLAG_PRIVACY

Criptografe o exemplo.

WINBIO_DATA_FLAG_INTEGRITY

Assine o exemplo ou proteja-o usando um MAC (código de autenticação de mensagem).

WINBIO_DATA_FLAG_SIGNED

Se esse sinalizador e o WINBIO_DATA_FLAG_INTEGRITYflag estiverem definidos, assine o exemplo. Se esse sinalizador não estiver definido, mas o sinalizador WINBIO_DATA_FLAG_INTEGRITY estiver definido, compute um MAC.

WINBIO_DATA_FLAG_RAW

Retorne o exemplo exatamente como foi capturado pelo sensor.

WINBIO_DATA_FLAG_INTERMEDIATE

Retorne o exemplo depois de ter sido limpo e filtrado.

WINBIO_DATA_FLAG_PROCESSED

Retorne o exemplo depois que ele estiver pronto para ser usado para a finalidade especificada pelo parâmetro Purpose .

[in] CaptureCallback

Endereço de uma função de retorno de chamada que será chamada pela função WinBioCaptureSampleWithCallback quando a operação de captura for bem-sucedida ou falhar. Você deve criar o retorno de chamada.

[in, optional] CaptureCallbackContext

Endereço de uma estrutura de dados definida pelo aplicativo que é passada para a função de retorno de chamada em seu parâmetro CaptureCallbackContext . 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_ACCESSDENIED	O chamador não tem permissão para capturar amostras brutas ou a sessão não foi aberta usando o sinalizador WINBIO_FLAG_RAW .
E_HANDLE	O identificador de sessão não é válido.
E_NOTIMPL	A unidade biométrica não dá suporte à operação solicitada.
E_POINTER	Os ponteiros UnitId, Sample, SampleSize e RejectDetail não podem ser NULL.
WINBIO_E_ENROLLMENT_IN_PROGRESS	A operação não pôde ser concluída porque a unidade biométrica está sendo usada no momento para uma transação de registro (somente pool do sistema).

Comentários

A função WinBioCaptureSampleWithCallback captura exemplos de forma assíncrona. Para chamar essa função com êxito, o identificador de sessão deve ter sido aberto especificando WINBIO_FLAG_RAW. Somente as contas Administradores e Sistema Local têm os privilégios necessários.

Combinações válidas dos parâmetros Purpose e Flags dependem dos recursos da unidade biométrica que está sendo usada. Consulte a documentação do sensor do fornecedor para determinar quais combinações têm suporte e como elas afetam os dados capturados.

Os chamadores são responsáveis por liberar a estrutura de WINBIO_BIR retornada pelo parâmetro Sample .

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

VOID CALLBACK CaptureCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
);

Exemplos

O exemplo de código a seguir captura um exemplo de forma assíncrona chamando WinBioCaptureSampleWithCallback e passando um ponteiro para uma função de retorno de chamada personalizada. A função de retorno de chamada, CaptureSampleCallback, também é mostrada. 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 CaptureSampleWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;

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

    // Capture a biometric sample asynchronously.
    wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
    hr = WinBioCaptureSampleWithCallback(
            sessionHandle,                  // Open session handle
            WINBIO_NO_PURPOSE_AVAILABLE,    // Intended use of the sample
            WINBIO_DATA_FLAG_RAW,           // Sample format
            CaptureSampleCallback,          // Callback function
            NULL                            // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the capture process if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...");
        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 capture 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)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

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

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
    __in_opt PVOID CaptureCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in_bcount(SampleSize) PWINBIO_BIR Sample,
    __in SIZE_T SampleSize,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(CaptureCallbackContext);

    wprintf_s(L"\n CaptureSampleCallback executing");
    wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);

    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
         }
        else
        {
            wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
            wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Captured %d bytes.\n", SampleSize);

e_Exit:

    if (Sample != NULL)
    {
        WinBioFree(Sample);
        Sample = NULL;
    }
}

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

WinBioCaptureSample

Compartilhar via

Função WinBioCaptureSampleWithCallback (winbio.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Exemplos

Requisitos

Confira também

Comentários

Recursos adicionais