Función WinBioIdentify (winbio.h)
Captura una muestra biométrica y determina si coincide con una plantilla biométrica existente. A partir de Windows 10, compilación 1607, esta función está disponible para su uso con una imagen móvil.
Sintaxis
HRESULT WinBioIdentify(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[out, optional] WINBIO_UNIT_ID *UnitId,
[out, optional] WINBIO_IDENTITY *Identity,
[out, optional] WINBIO_BIOMETRIC_SUBTYPE *SubFactor,
[out, optional] WINBIO_REJECT_DETAIL *RejectDetail
);
Parámetros
[in] SessionHandle
Valor de 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.
[out, optional] UnitId
Puntero a un valor ULONG que especifica la unidad biométrica utilizada para realizar la identificación.
[out, optional] Identity
Puntero a una estructura de WINBIO_IDENTITY que recibe el GUID o el SID del usuario que proporciona la muestra biométrica.
[out, optional] SubFactor
Puntero a un valor de WINBIO_BIOMETRIC_SUBTYPE que recibe el subfactor asociado a la muestra biométrica. Para obtener información más detallada, consulte la sección Comentarios.
[out, optional] RejectDetail
Puntero a un valor ULONG que contiene información adicional sobre el error, si existe, para capturar una muestra biométrica. Si la captura se realizó correctamente, este parámetro se establece en cero. Los valores siguientes 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 ejecuta 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 puntero especificado por los parámetros UnitId, Identity, SubFactor o RejectDetail no puede ser NULL. |
|
No se pudo capturar el ejemplo. Use el valor RejectDetail para obtener más información. |
|
No se pudo completar la operación porque la unidad biométrica se está usando actualmente para una transacción de inscripción (solo para el grupo de sistemas). |
|
El ejemplo biométrico no coincide con ningún guardado en la base de datos. |
Comentarios
El valor devuelto en el parámetro SubFactor especifica el subfactor asociado a la muestra biométrica. Windows Biometric Framework (WBF) actualmente solo admite la captura de huellas digitales y usa 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
Para usar WinBioIdentify 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 error de la operación. Si la operación se realiza correctamente, el marco devuelve WINBIO_IDENTITY y WINBIO_BIOMETRIC_SUBTYPE información en una estructura de identificación anidada. Si la operación no se realiza correctamente, el marco devuelve WINBIO_REJECT_DETAIL información en la estructura Identificar . 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, en función del 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 avisos de finalización mediante la cola de mensajes de la aplicación, debe establecer el parámetro NotificationMethod en 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 WinBioIdentifyWithCallback . 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_IDENTIFY_CALLBACK implementada por la aplicación.
Ejemplos
La siguiente función llama a WinBioEnumEnrollments para enumerar los subfactores biométricos inscritos para una plantilla y llama a WinBioIdentify para recuperar un objeto WINBIO_IDENTITY que identifica al usuario. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:
- 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 | 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 (incluya Winbio.h) |
| Library | Winbio.lib |
| Archivo DLL | Winbio.dll |