Función WinBioVerify (winbio.h)
Captura una muestra biométrica y determina si la muestra corresponde a la identidad de usuario especificada. A partir de Windows 10, compilación 1607, esta función está disponible para su uso con una imagen móvil.
Sintaxis
HRESULT WinBioVerify(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_IDENTITY *Identity,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[out, optional] WINBIO_UNIT_ID *UnitId,
[out, optional] BOOLEAN *Match,
[out, optional] WINBIO_REJECT_DETAIL *RejectDetail
);
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] Identity
Puntero a una estructura de WINBIO_IDENTITY que contiene el GUID o el SID del usuario que proporciona la muestra biométrica.
[in] SubFactor
Valor de WINBIO_BIOMETRIC_SUBTYPE que especifica el subfactor asociado a la muestra biométrica. El marco biométrico de Windows (WBF) actualmente solo admite la captura de huellas digitales y puede usar las siguientes constantes para representar información de subtipo.
- 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
- WINBIO_SUBTYPE_ANY
[out, optional] UnitId
Puntero a un valor de WINBIO_UNIT_ID que especifica la unidad biométrica que realizó la comprobación.
[out, optional] Match
Puntero a un valor booleano que especifica si el ejemplo capturado coincide con la identidad de usuario especificada por el parámetro Identity .
[out, optional] RejectDetail
Puntero a un valor ULONG que contiene información adicional sobre el error de captura de una muestra biométrica. Si la captura se realizó correctamente, este parámetro se establece en cero. Los siguientes valores se definen para la captura de huellas digitales:
- 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 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 identificador de sesión no es válido. |
|
El argumento SubFactor es incorrecto. |
|
El puntero especificado por los parámetros UnitId, Identity, SubFactor o RejectDetail no puede ser NULL. |
|
No se pudo capturar la muestra biométrica. Use el valor RejectDetail para obtener más información. |
|
No se pudo completar la operación porque la unidad biométrica especificada se está usando actualmente para una transacción de inscripción (solo para el grupo del sistema). |
|
La muestra biométrica no corresponde a la combinación de Identidad y SubFactor especificada. |
Comentarios
Si se produce un error en la captura de la muestra biométrica, el parámetro UnitId contendrá el número de unidad del sensor que intentó realizar la captura.
Las llamadas a esta función mediante el grupo de sistemas se bloquearán hasta que la aplicación adquiera el foco de la ventana y el usuario haya proporcionado una muestra biométrica. Por lo tanto, se recomienda que la aplicación no llame a WinBioVerify 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 WinBioVerify 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 WinBioVerify 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 un valor de coincidencia BOOLEAN en una estructura Verify anidada. Si la operación no se realiza correctamente, el marco devuelve WINBIO_REJECT_DETAIL información en la estructura Verify . 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.
Windows 7: Puede realizar esta operación de forma asincrónica mediante la función WinBioVerifyWithCallback . La función comprueba los argumentos de entrada y devuelve inmediatamente. Si los argumentos de entrada no son válidos, la función devuelve un código de error. De lo contrario, el marco inicia la operación en otro subproceso. Cuando la operación asincrónica finaliza o encuentra un error, el marco envía los resultados a la función PWINBIO_VERIFY_CALLBACK implementada por la aplicación.
Ejemplos
La siguiente función llama a WinBioVerify para determinar si un ejemplo biométrico coincide con la identidad iniciada del usuario actual. También se incluye la función auxiliar GetCurrentUserIdentity. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT Verify(WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
WINBIO_REJECT_DETAIL rejectDetail = 0;
WINBIO_IDENTITY identity = {0};
BOOLEAN match = FALSE;
// Find the identity of the user.
hr = GetCurrentUserIdentity( &identity );
if (FAILED(hr))
{
wprintf_s(L"\n User identity not found. hr = 0x%x\n", hr);
goto e_Exit;
}
// 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;
}
// Verify a biometric sample.
wprintf_s(L"\n Calling WinBioVerify - Swipe finger on sensor...\n");
hr = WinBioVerify(
sessionHandle,
&identity,
subFactor,
&unitId,
&match,
&rejectDetail
);
wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
if (FAILED(hr))
{
if (hr == WINBIO_E_NO_MATCH)
{
wprintf_s(L"\n- NO MATCH - identity verification failed.\n");
}
else if (hr == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n- Bad capture; reason: %d\n", rejectDetail);
}
else
{
wprintf_s(L"\n WinBioVerify failed. hr = 0x%x\n", hr);
}
goto e_Exit;
}
wprintf_s(L"\n Fingerprint verified:\n", unitId);
e_Exit:
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L"\n Press any key to exit...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function retrieves the identity of the current user.
// This is a helper function and is not part of the Windows Biometric
// Framework API.
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
// Declare variables.
HRESULT hr = S_OK;
HANDLE tokenHandle = NULL;
DWORD bytesReturned = 0;
struct{
TOKEN_USER tokenUser;
BYTE buffer[SECURITY_MAX_SID_SIZE];
} tokenInfoBuffer;
// Zero the input identity and specify the type.
ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
Identity->Type = WINBIO_ID_TYPE_NULL;
// Open the access token associated with the
// current process
if (!OpenProcessToken(
GetCurrentProcess(), // Process handle
TOKEN_READ, // Read access only
&tokenHandle)) // Access token handle
{
DWORD win32Status = GetLastError();
wprintf_s(L"Cannot open token handle: %d\n", win32Status);
hr = HRESULT_FROM_WIN32(win32Status);
goto e_Exit;
}
// Zero the tokenInfoBuffer structure.
ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));
// Retrieve information about the access token. In this case,
// retrieve a SID.
if (!GetTokenInformation(
tokenHandle, // Access token handle
TokenUser, // User for the token
&tokenInfoBuffer.tokenUser, // Buffer to fill
sizeof(tokenInfoBuffer), // Size of the buffer
&bytesReturned)) // Size needed
{
DWORD win32Status = GetLastError();
wprintf_s(L"Cannot query token information: %d\n", win32Status);
hr = HRESULT_FROM_WIN32(win32Status);
goto e_Exit;
}
// Copy the SID from the tokenInfoBuffer structure to the
// WINBIO_IDENTITY structure.
CopySid(
SECURITY_MAX_SID_SIZE,
Identity->Value.AccountSid.Data,
tokenInfoBuffer.tokenUser.User.Sid
);
// Specify the size of the SID and assign WINBIO_ID_TYPE_SID
// to the type member of the WINBIO_IDENTITY structure.
Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
Identity->Type = WINBIO_ID_TYPE_SID;
e_Exit:
if (tokenHandle != NULL)
{
CloseHandle(tokenHandle);
}
return hr;
}
Requisitos
| 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 (incluya Winbio.h) |
| Library | Winbio.lib |
| Archivo DLL | Winbio.dll |