Función WinBioEnrollBegin (winbio.h)
Inicia una secuencia de inscripción biométrica y crea una plantilla biométrica vacía. A partir de Windows 10, compilación 1607, esta función está disponible para su uso con una imagen móvil.
Sintaxis
HRESULT WinBioEnrollBegin(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[in] WINBIO_UNIT_ID UnitId
);
Parámetros
[in] SessionHandle
Valor WINBIO_SESSION_HANDLE que identifica una sesión biométrica abierta. Abra un identificador de sesión sincrónico llamando a WinBioOpenSession. Abra un identificador de sesión asincrónico llamando a WinBioAsyncOpenSession.
[in] SubFactor
Valor de WINBIO_BIOMETRIC_SUBTYPE que proporciona información adicional sobre la inscripción. Debe ser uno de los siguientes 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
Valor WINBIO_UNIT_ID que identifica la unidad biométrica. Este valor no puede ser cero. Puede encontrar un identificador de unidad llamando a las funciones WinBioEnumBiometricUnits o WinBioLocateSensor .
Valor devuelto
Si la función se realiza correctamente, devuelve S_OK. Si se produce un error en la función, devuelve un valor HRESULT que indica el error. Entre los valores posibles se incluyen los que se indican en la tabla siguiente, entre otros. Para obtener una lista de códigos de error comunes, consulte Valores HRESULT comunes.
| Código devuelto | Descripción |
|---|---|
|
El autor de la llamada no tiene permiso para inscribirse. |
|
El identificador de sesión no es válido. |
|
El parámetro SubFactor no puede ser igual a WINBIO_SUBTYPE_NO_INFORMATION o WINBIO_SUBTYPE_ANY, y el parámetro UnitId no puede ser igual a cero. |
|
Una operación de inscripción ya está en curso y solo se puede producir una inscripción en un momento dado. |
|
La unidad biométrica está en uso y está bloqueada. |
Comentarios
Una única inscripción biométrica requiere la recopilación de varios ejemplos de un usuario. Solo se puede realizar una operación de inscripción en cualquier momento y el mismo sensor debe generar todas las muestras biométricas que se aplican a una sola inscripción. El parámetro UnitId especifica este sensor.
Cualquier aplicación que se inscriba mediante una unidad biométrica en el grupo de sistemas debe tener el foco de ventana cuando llama a WinBioEnrollBegin. Si no es así, la llamada se bloquea hasta que la aplicación adquiere el foco de la ventana y el usuario ha proporcionado una muestra biométrica. Por lo tanto, se recomienda que la aplicación no llame a WinBioEnrollBegin hasta que haya adquirido el foco. La manera en que adquiere el foco depende del tipo de aplicación que está escribiendo. Por ejemplo, si va a crear una aplicación de GUI, puede implementar un controlador de mensajes que capture un WM_ACTIVATE, WM_SETFOCUS u otro mensaje adecuado. Si va a escribir una aplicación CUI, llame a GetConsoleWindow para recuperar un identificador en la ventana de la consola y pase ese identificador a la función SetForegroundWindow para forzar la ventana de consola en primer plano y asignarle el foco. Si la aplicación se ejecuta en un proceso desasociado y no tiene ninguna ventana o es un servicio de Windows, use WinBioAcquireFocus y WinBioReleaseFocus para controlar manualmente el foco.
Para usar WinBioEnrollBegin de forma sincrónica, llame a la función con un identificador de sesión creado mediante una llamada a WinBioOpenSession. La función se bloquea hasta que se completa la operación o se produce un error.
Para usar WinBioEnrollBegin de forma asincrónica, llame a la función con un identificador de sesión creado mediante una llamada a WinBioAsyncOpenSession. El marco asigna una estructura de WINBIO_ASYNC_RESULT y la usa para devolver información sobre el éxito o el error de la operación. Si la operación se realiza correctamente, el marco devuelve WINBIO_BIOMETRIC_SUBTYPE información en una estructura EnrollBegin anidada. Si la operación no se realiza correctamente, el marco devuelve información de error. La estructura WINBIO_ASYNC_RESULT se devuelve a la devolución de llamada de la aplicación o a la cola de mensajes de la aplicación, según el valor establecido en el parámetro NotificationMethod de la función WinBioAsyncOpenSession :
- Si decide recibir avisos de finalización mediante una devolución de llamada, debe implementar una función de PWINBIO_ASYNC_COMPLETION_CALLBACK y establecer el parámetro NotificationMethod en WINBIO_ASYNC_NOTIFY_CALLBACK.
- Si decide recibir notificaciones de finalización mediante la cola de mensajes de la aplicación, debe establecer el parámetro NotificationMethoden WINBIO_ASYNC_NOTIFY_MESSAGE. El marco devuelve un puntero WINBIO_ASYNC_RESULT al campo LPARAM del mensaje de ventana.
Ejemplos
La siguiente función inscribe una plantilla biométrica en el grupo de sistemas. Llama a WinBioEnrollBegin para iniciar la secuencia de inscripción. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:
- 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 | Value |
|---|---|
| Cliente mínimo compatible | Windows 7 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 R2 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | winbio.h (incluye Winbio.h) |
| Library | Winbio.lib |
| Archivo DLL | Winbio.dll |