Função WinBioEnumEnrollments (winbio.h)

Artigo
08/27/2023

Recupera os subfators biométricos registrados para uma identidade especificada e uma unidade biométrica. A partir do Windows 10, build 1607, essa função está disponível para uso com uma imagem móvel.

Sintaxe

HRESULT WinBioEnumEnrollments(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_UNIT_ID           UnitId,
  [in]            WINBIO_IDENTITY          *Identity,
                  WINBIO_BIOMETRIC_SUBTYPE **SubFactorArray,
  [out, optional] SIZE_T                   *SubFactorCount
);

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

Um valor WINBIO_UNIT_ID que especifica a unidade biométrica.

[in] Identity

Ponteiro para uma estrutura WINBIO_IDENTITY que contém o GUID ou SID do modelo do qual os subfators devem ser recuperados.

SubFactorArray

Endereço de uma variável que recebe um ponteiro para uma matriz de subfators. Se a função não for bem-sucedida, o ponteiro será definido como NULL. Se a função for bem-sucedida, você deverá passar o ponteiro para WinBioFree para liberar a memória alocada internamente para a matriz.

[out, optional] SubFactorCount

Ponteiro para um valor que especifica o número de elementos na matriz apontada pelo parâmetro SubFactorArray . Se a função não for bem-sucedida, esse valor será definido como zero.

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_INVALIDARG	O parâmetro UnitId não pode ser zero.
E_POINTER	Os parâmetros Identity, SubFactorArray e SubFactorCount 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 especificada pelo parâmetro UnitId está sendo usada atualmente para uma transação de registro.
WINBIO_E_UNKNOWN_ID	O GUID ou SID especificado pelo parâmetro Identity não pode ser encontrado.

Comentários

A função WinBioEnumEnrollments é fornecida principalmente para que os aplicativos possam fornecer comentários do usuário. Por exemplo, seu aplicativo pode chamar essa função para informar ao usuário quais impressões digitais já estão registradas em um leitor de impressão digital específico.

Depois de terminar de usar as estruturas retornadas para o parâmetro SubFactorArray , você deve chamar WinBioFree para liberar a memória alocada internamente para a matriz.

Para usar WinBioEnumEnrollments 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 WinBioEnumEnrollments 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_IDENTITY e WINBIO_BIOMETRIC_SUBTYPE informações em uma estrutura aninhada de EnumEnrollments . 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.

Exemplos

A função a seguir chama WinBioEnumEnrollments para enumerar os subfators biométricos registrados para um modelo. 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 EnumEnrollments( )
{
    // Declare variables.
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    PWINBIO_BIOMETRIC_SUBTYPE subFactorArray = NULL;
    WINBIO_BIOMETRIC_SUBTYPE SubFactor = 0;
    SIZE_T subFactorCount = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_BIOMETRIC_SUBTYPE subFactor = WINBIO_SUBTYPE_NO_INFORMATION;

    // 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;
    }

    // Locate the biometric sensor and retrieve a WINBIO_IDENTITY object.
    wprintf_s(L"\n Calling WinBioIdentify - Swipe finger on sensor...\n");
    hr = WinBioIdentify( 
            sessionHandle,              // Session handle
            &unitId,                    // Biometric unit ID
            &identity,                  // User SID
            &subFactor,                 // Finger sub factor
            &rejectDetail               // Rejection information
            );
    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_UNKNOWN_ID)
        {
            wprintf_s(L"\n Unknown identity.\n");
        }
        else if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    // Retrieve the biometric sub-factors for the template.
    hr = WinBioEnumEnrollments( 
            sessionHandle,              // Session handle
            unitId,                     // Biometric unit ID
            &identity,                  // Template ID
            &subFactorArray,            // Subfactors
            &subFactorCount             // Count of subfactors
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnumEnrollments failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Print the sub-factor(s) to the console.
    wprintf_s(L"\n Enrollments for this user on Unit ID %d:", unitId);
    for (SIZE_T index = 0; index < subFactorCount; ++index)
    {
        SubFactor = subFactorArray[index];
        switch (SubFactor)
        {
            case WINBIO_ANSI_381_POS_RH_THUMB:
                wprintf_s(L"\n   RH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_RH_INDEX_FINGER:
                wprintf_s(L"\n   RH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER:
                wprintf_s(L"\n   RH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_RING_FINGER:
                wprintf_s(L"\n   RH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_LITTLE_FINGER:
                wprintf_s(L"\n   RH little finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_THUMB:
                wprintf_s(L"\n   LH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_LH_INDEX_FINGER:
                wprintf_s(L"\n   LH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER:
                wprintf_s(L"\n   LH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_RING_FINGER:
                wprintf_s(L"\n   LH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_LITTLE_FINGER:
                wprintf_s(L"\n   LH little finger\n");
                break;
            default:
                wprintf_s(L"\n   The sub-factor is not correct\n");
                break;
        }
 
    }

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

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

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

    return hr;
}

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

WinBioEnumBiometricUnits

WinBioEnumDatabases

WinBioEnumServiceProviders

Compartilhar via

Função WinBioEnumEnrollments (winbio.h)

Sintaxe

Parâmetros

Retornar valor

Comentários

Exemplos

Requisitos

Confira também

Comentários

Recursos adicionais