Função WinBioEnrollBegin (winbio.h)

Inicia uma sequência de registro biométrico e cria um modelo biométrico vazio. A partir do Windows 10, build 1607, essa função está disponível para uso com uma imagem móvel.

Sintaxe

HRESULT WinBioEnrollBegin(
  [in] WINBIO_SESSION_HANDLE    SessionHandle,
  [in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [in] WINBIO_UNIT_ID           UnitId
);

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] SubFactor

Um valor WINBIO_BIOMETRIC_SUBTYPE que fornece informações adicionais sobre o registro. Esse deve ser um dos seguintes valores:

• WINBIO_ANSI_381_POS_RH_THUMB
• WINBIO_ANSI_381_POS_RH_INDEX_FINGER
• WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
• WINBIO_ANSI_381_POS_RH_RING_FINGER
• WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
• WINBIO_ANSI_381_POS_LH_THUMB
• WINBIO_ANSI_381_POS_LH_INDEX_FINGER
• WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
• WINBIO_ANSI_381_POS_LH_RING_FINGER
• WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
• WINBIO_ANSI_381_POS_RH_FOUR_FINGERS
• WINBIO_ANSI_381_POS_LH_FOUR_FINGERS

[in] UnitId

Um valor WINBIO_UNIT_ID que identifica a unidade biométrica. Esse valor não pode ser zero. Você pode encontrar uma ID de unidade chamando as funções WinBioEnumBiometricUnits ou WinBioLocateSensor .

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.

Comentários

Um único registro biométrico requer a coleção de vários exemplos de um usuário. Somente uma operação de registro pode ocorrer a qualquer momento e todos os exemplos biométricos que se aplicam a um único registro devem ser gerados pelo mesmo sensor. Esse sensor é especificado pelo parâmetro UnitId .

Qualquer aplicativo que se registra usando uma unidade biométrica no pool do sistema deve ter o foco da janela quando chama WinBioEnrollBegin. Se isso não acontecer, a chamada será bloqueada até que o aplicativo adquira o foco da janela e o usuário tenha fornecido uma amostra biométrica. Recomendamos, portanto, que seu aplicativo não chame WinBioEnrollBegin até que ele tenha adquirido o foco. 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.

Para usar WinBioEnrollBegin de forma síncrona, chame a função com um identificador de sessão criado chamando WinBioOpenSession. A função é bloqueada até que a operação seja concluída ou um erro seja encontrado.

Para usar WinBioEnrollBegin 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 for bem-sucedida, a estrutura retornará WINBIO_BIOMETRIC_SUBTYPE informações em uma estrutura EnrollBegin aninhada. 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.

Exemplos

A função a seguir registra um modelo biométrico no pool do sistema. Ele chama WinBioEnrollBegin para iniciar a sequência de registro. 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 EnrollSysPool(
                      BOOL discardEnrollment, 
                      WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    BOOLEAN isNewTemplate = TRUE;

    // 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. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate a sensor.
    wprintf_s(L"\n Swipe your finger on the sensor...\n");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Begin the enrollment sequence. 
    wprintf_s(L"\n Starting enrollment sequence...\n");
    hr = WinBioEnrollBegin(
            sessionHandle,      // Handle to open biometric session
            subFactor,          // Finger to create template for
            unitId              // Biometric unit ID
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnrollBegin failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture enrollment information by swiping the sensor with
    // the finger identified by the subFactor argument in the 
    // WinBioEnrollBegin function.
    for (int swipeCount = 1;; ++swipeCount)
    {
        wprintf_s(L"\n Swipe the sensor to capture %s sample.",
                 (swipeCount == 1)?L"the first":L"another");

        hr = WinBioEnrollCapture(
                sessionHandle,  // Handle to open biometric session
                &rejectDetail   // [out] Failure information
                );

        wprintf_s(L"\n Sample %d captured from unit number %d.", 
                  swipeCount, 
                  unitId);

        if (hr == WINBIO_I_MORE_DATA)
        {
            wprintf_s(L"\n    More data required.\n");
            continue;
        }
        if (FAILED(hr))
        {
            if (hr == WINBIO_E_BAD_CAPTURE)
            {
                wprintf_s(L"\n  Error: Bad capture; reason: %d", 
                          rejectDetail);
                continue;
            }
            else
            {
                wprintf_s(L"\n WinBioEnrollCapture failed. hr = 0x%x", hr);
                goto e_Exit;
            }
        }
        else
        {
            wprintf_s(L"\n    Template completed.\n");
            break;
        }
    }

    // Discard the enrollment if the appropriate flag is set.
    // Commit the enrollment if it is not discarded.
    if (discardEnrollment == TRUE)
    {
        wprintf_s(L"\n Discarding enrollment...\n\n");
        hr = WinBioEnrollDiscard( sessionHandle );
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;    
    }
    else
    {
        wprintf_s(L"\n Committing enrollment...\n");
        hr = WinBioEnrollCommit( 
                sessionHandle,      // Handle to open biometric session
                &identity,          // WINBIO_IDENTITY object for the user
                &isNewTemplate);    // Is this a new template

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


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

    wprintf_s(L" Press any key to continue...");
    _getch();

    return hr;
}

Requisitos

Confira também

WinBioAcquireFocus

WinBioEnrollCapture

WinBioEnrollCaptureWithCallback

WinBioEnrollCommit

WinBioEnrollDiscard

WinBioReleaseFocus