Funzione WinBioVerify (winbio.h)
Acquisisce un esempio biometrico e determina se l'esempio corrisponde all'identità utente specificata. A partire da Windows 10, build 1607, questa funzione è disponibile per l'uso con un'immagine per dispositivi mobili.
Sintassi
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
);
Parametri
[in] SessionHandle
Valore WINBIO_SESSION_HANDLE che identifica una sessione biometrica aperta. Aprire un handle di sessione sincrono chiamando WinBioOpenSession. Aprire un handle di sessione asincrono chiamando WinBioAsyncOpenSession.
[in] Identity
Puntatore a una struttura WINBIO_IDENTITY che contiene il GUID o il SID dell'utente che fornisce l'esempio biometrico.
[in] SubFactor
Valore WINBIO_BIOMETRIC_SUBTYPE che specifica il sotto-fattore associato al campione biometrico. Windows Biometric Framework (WBF) supporta attualmente solo l'acquisizione delle impronte digitali e può usare le costanti seguenti per rappresentare le informazioni sul sottotipo.
- 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
Puntatore a un valore WINBIO_UNIT_ID che specifica l'unità biometrica che ha eseguito la verifica.
[out, optional] Match
Puntatore a un valore booleano che specifica se l'esempio acquisito corrisponde all'identità utente specificata dal parametro Identity .
[out, optional] RejectDetail
Puntatore a un valore ULONG contenente informazioni aggiuntive sull'errore di acquisizione di un campione biometrico. Se l'acquisizione ha avuto esito positivo, questo parametro è impostato su zero. I valori seguenti sono definiti per l'acquisizione delle impronte digitali:
- 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
Valore restituito
Se la funzione ha esito positivo, restituisce S_OK. Se la funzione ha esito negativo, restituisce un valore HRESULT che indica l'errore. I valori possibili includono, ma non sono limitati a, quelli indicati nella tabella seguente. Per un elenco di codici di errore comuni, vedere Valori HRESULT comuni.
| Codice restituito | Descrizione |
|---|---|
|
L'handle di sessione non è valido. |
|
L'argomento SubFactor non è corretto. |
|
Il puntatore specificato dai parametri UnitId, Identity, SubFactor o RejectDetail non può essere NULL. |
|
Impossibile acquisire il campione biometrico. Usare il valore RejectDetail per altre informazioni. |
|
Impossibile completare l'operazione perché l'unità biometrica specificata è attualmente usata per una transazione di registrazione (solo pool di sistema). |
|
L'esempio biometrico non corrisponde alla combinazione Identity e SubFactor specificata. |
Commenti
Se l'acquisizione del campione biometrico ha esito negativo, il parametro UnitId conterrà il numero di unità del sensore che ha tentato di eseguire l'acquisizione.
Le chiamate a questa funzione usando il pool di sistema verranno bloccate finché l'applicazione acquisisce lo stato attivo della finestra e l'utente ha fornito un esempio biometrico. È quindi consigliabile che l'applicazione non chiami WinBioVerify finché non ha acquisito lo stato attivo. Il modo in cui si acquisisce lo stato attivo dipende dal tipo di applicazione che si scrive. Ad esempio, se si sta creando un'applicazione GUI, è possibile implementare un gestore messaggi che acquisisce un WM_ACTIVATE, WM_SETFOCUS o un altro messaggio appropriato. Se si scrive un'applicazione CUI, chiamare GetConsoleWindow per recuperare un handle nella finestra della console e passare tale handle alla funzione SetForegroundWindow per forzare la finestra della console in primo piano e assegnarla lo stato attivo. Se l'applicazione è in esecuzione in un processo scollegato e non ha una finestra o è un servizio Windows, usare WinBioAcquireFocus e WinBioReleaseFocus per controllare manualmente lo stato attivo.
Per usare WinBioVerify in modo sincrono, chiamare la funzione con un handle di sessione creato chiamando WinBioOpenSession. La funzione blocca finché l'operazione non viene completata o viene rilevato un errore.
Per usare WinBioVerify in modo asincrono, chiamare la funzione con un handle di sessione creato chiamando WinBioAsyncOpenSession. Il framework alloca una struttura WINBIO_ASYNC_RESULT e la usa per restituire informazioni sull'esito positivo o negativo dell'operazione. Se l'operazione ha esito positivo, il framework restituisce un valore di corrispondenza BOOLEAN in una struttura Verifica annidata. Se l'operazione ha esito negativo, il framework restituisce WINBIO_REJECT_DETAIL informazioni nella struttura Verifica . La struttura WINBIO_ASYNC_RESULT viene restituita al callback dell'applicazione o alla coda dei messaggi dell'applicazione, a seconda del valore impostato nel parametro NotificationMethod della funzione WinBioAsyncOpenSession :
- Se si sceglie di ricevere avvisi di completamento usando un callback, è necessario implementare una funzione PWINBIO_ASYNC_COMPLETION_CALLBACK e impostare il parametro NotificationMethod su WINBIO_ASYNC_NOTIFY_CALLBACK.
- Se si sceglie di ricevere avvisi di completamento usando la coda di messaggi dell'applicazione, è necessario impostare il parametro NotificationMethod su WINBIO_ASYNC_NOTIFY_MESSAGE. Il framework restituisce un puntatore WINBIO_ASYNC_RESULT al campo LPARAM del messaggio della finestra.
Windows 7: È possibile eseguire questa operazione in modo asincrono usando la funzione WinBioVerifyWithCallback . La funzione verifica gli argomenti di input e restituisce immediatamente. Se gli argomenti di input non sono validi, la funzione restituisce un codice di errore. In caso contrario, il framework avvia l'operazione in un altro thread. Al termine dell'operazione asincrona o si verifica un errore, il framework invia i risultati alla funzione PWINBIO_VERIFY_CALLBACK implementata dall'applicazione.
Esempio
La funzione seguente chiama WinBioVerify per determinare se un campione biometrico corrisponde all'identità registrata dell'utente corrente. La funzione helper GetCurrentUserIdentity è inclusa anche. Collegare alla libreria statica Winbio.lib e includere i file di intestazione seguenti:
- 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;
}
Requisiti
| Client minimo supportato | Windows 7 [solo app desktop] |
| Server minimo supportato | Windows Server 2008 R2 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winbio.h (include Winbio.h) |
| Libreria | Winbio.lib |
| DLL | Winbio.dll |