Função WinBioCaptureSample (winbio.h)

  • Artigo

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