Função WinBioCaptureSample (winbio.h)

Artigo
03/08/2023

Captura um exemplo biométrico e preenche um BIR (registro de informações biométricas) com os dados brutos ou processados.

Sintaxe

HRESULT WinBioCaptureSample(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_BIR_PURPOSE    Purpose,
  [in]            WINBIO_BIR_DATA_FLAGS Flags,
  [out, optional] WINBIO_UNIT_ID        *UnitId,
                  PWINBIO_BIR           *Sample,
  [out, optional] SIZE_T                *SampleSize,
  [out, optional] WINBIO_REJECT_DETAIL  *RejectDetail
);

Parâmetros

[in] SessionHandle

Um valor WINBIO_SESSION_HANDLE que identifica uma sessão biométrica aberta. Abra um identificador de sessão síncrona chamando WinBioOpenSession. Abra um identificador de sessão assíncrono chamando WinBioAsyncOpenSession.

[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 sinalizador WINBIO_DATA_FLAG_INTEGRITY 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.

[out, optional] UnitId

Um ponteiro para um valor WINBIO_UNIT_ID que contém a ID da unidade biométrica que gerou a amostra.

Sample

Endereço de uma variável que recebe um ponteiro para uma estrutura WINBIO_BIR que contém o exemplo. Quando terminar de usar a estrutura, você deverá passar o ponteiro para WinBioFree para liberar a memória alocada para o exemplo.

[out, optional] SampleSize

Um ponteiro para um valor SIZE_T que contém o tamanho, em bytes, da estrutura WINBIO_BIR retornada no parâmetro Sample .

[out, optional] RejectDetail

Um ponteiro para um valor WINBIO_REJECT_DETAIL que contém informações adicionais sobre a falha na captura de uma amostra biométrica. Se a captura tiver sido bem-sucedida, esse parâmetro será definido como zero. Os seguintes valores são definidos para captura de impressão digital:

WINBIO_FP_TOO_HIGH
WINBIO_FP_TOO_LOW
WINBIO_FP_TOO_LEFT
WINBIO_FP_TOO_RIGHT
WINBIO_FP_TOO_FAST
WINBIO_FP_TOO_SLOW
WINBIO_FP_POOR_QUALITY
WINBIO_FP_TOO_SKEWED
WINBIO_FP_TOO_SHORT
WINBIO_FP_MERGE_FAILURE

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_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).
WINBIO_E_INVALID_OPERATION	A operação não pôde ser concluída porque um sensor seguro está presente no pool de sensores.

Comentários

Para chamar essa função com êxito, você deve abrir o identificador de sessão especificando WINBIO_FLAG_RAW no parâmetro Flags das funções WinBioOpenSession ou WinBioAsyncOpenSession . Atualmente, somente os aplicativos em execução nas 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 de valores de Uso e Sinalizadores válidos têm suporte e como eles afetam os dados capturados. Depois que você terminar de usar o exemplo, seu aplicativo deverá chamar WinBioFree para liberar a memória alocada para ele pela função WinBioCaptureSample .

Para usar WinBioCaptureSample de forma síncrona, chame a função com um identificador de sessão criado chamando WinBioOpenSession. A função é bloqueada até que um exemplo seja capturado ou que um erro seja encontrado. As chamadas para WinBioCaptureSample usando o pool do sistema serão bloqueadas até que o aplicativo de chamada tenha o foco da janela e o usuário forneça um exemplo para um dos sensores no pool. Se o sensor escolhido pelo usuário já estiver sendo usado para uma transação de registro, a função falhará e retornará WINBIO_E_ENROLLMENT_IN_PROGRESS.

Para usar WinBioCaptureSample de forma assíncrona, chame a função com um identificador de sessão criado chamando WinBioAsyncOpenSession. A estrutura aloca uma estrutura WINBIO_ASYNC_RESULT e a usa para retornar informações sobre êxito ou falha da operação. Se a operação de captura for bem-sucedida, a estrutura retornará informações sobre o exemplo em uma estrutura aninhada do CaptureSample . Se a operação não for bem-sucedida, a estrutura retornará informações de erro. A estrutura WINBIO_ASYNC_RESULT é retornada para o retorno de chamada do aplicativo ou para a fila de mensagens do aplicativo, dependendo do valor definido no parâmetro NotificationMethod da função WinBioAsyncOpenSession :

Se você optar por receber avisos de conclusão usando um retorno de chamada, deverá implementar uma função PWINBIO_ASYNC_COMPLETION_CALLBACK e definir o parâmetro NotificationMethod como WINBIO_ASYNC_NOTIFY_CALLBACK.
Se você optar por receber avisos de conclusão usando a fila de mensagens do aplicativo, deverá definir o parâmetro NotificationMethod como WINBIO_ASYNC_NOTIFY_MESSAGE. A estrutura retorna um ponteiro WINBIO_ASYNC_RESULT para o campo LPARAM da mensagem de janela.

Para evitar vazamentos de memória, você deve chamar WinBioFree para liberar a estrutura WINBIO_ASYNC_RESULT depois de terminar de usá-la.

Windows 7: Você pode executar essa operação de forma assíncrona usando a função WinBioCaptureSampleWithCallback . A função verifica os argumentos de entrada e retorna imediatamente. Se os argumentos de entrada não forem válidos, a função retornará um código de erro. Caso contrário, a estrutura iniciará a operação em outro thread. Quando a operação assíncrona é concluída ou encontra um erro, a estrutura envia os resultados para a função PWINBIO_CAPTURE_CALLBACK implementada pelo aplicativo.

Exemplos

A função a seguir chama WinBioCaptureSample para capturar um exemplo biométrico de um usuário. 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 CaptureSample()
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    PWINBIO_BIR sample = NULL;
    SIZE_T sampleSize = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Access: Capture raw data
            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.
    wprintf_s(L"\n Calling WinBioCaptureSample - Swipe sensor...\n");
    hr = WinBioCaptureSample(
            sessionHandle,
            WINBIO_NO_PURPOSE_AVAILABLE,
            WINBIO_DATA_FLAG_RAW,
            &unitId,
            &sample,
            &sampleSize,
            &rejectDetail
            );
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioCaptureSample failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    wprintf_s(L"\n Captured %d bytes.\n", sampleSize);


e_Exit:
    if (sample != NULL)
    {
        WinBioFree(sample);
        sample = NULL;
    }

    if (sessionHandle != NULL)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

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

    return hr;
}

Requisitos


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

WinBioCaptureSampleWithCallback

Compartilhar via

Função WinBioCaptureSample (winbio.h)

Sintaxe

Parâmetros

Valor retornado

Comentários

Exemplos

Requisitos

Confira também

Comentários

Recursos adicionais