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.
| Código de retorno | Descrição |
|---|---|
|
O chamador não tem permissão para se registrar. |
|
O identificador de sessão não é válido. |
|
O parâmetro SubFactor não pode ser igual a WINBIO_SUBTYPE_NO_INFORMATION ou WINBIO_SUBTYPE_ANY e o parâmetro UnitId não pode ser igual a zero. |
|
Uma operação de registro já está em andamento e apenas um registro pode ocorrer em um determinado momento. |
|
A unidade biométrica está em uso e está bloqueada. |
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
| 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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de