Funzione WinBioIdentify (winbio.h)
Acquisisce un campione biometrico e determina se corrisponde a un modello biometrico esistente. A partire da Windows 10, build 1607, questa funzione è disponibile per l'uso con un'immagine per dispositivi mobili.
Sintassi
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
);
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.
[out, optional] UnitId
Puntatore a un valore ULONG che specifica l'unità biometrica usata per eseguire l'identificazione.
[out, optional] Identity
Puntatore a una struttura WINBIO_IDENTITY che riceve il GUID o il SID dell'utente che fornisce l'esempio biometrico.
[out, optional] SubFactor
Puntatore a un valore WINBIO_BIOMETRIC_SUBTYPE che riceve il sotto-fattore associato al campione biometrico. Per altre informazioni, vedere le sezione Osservazioni.
[out, optional] RejectDetail
Puntatore a un valore ULONG che contiene informazioni aggiuntive sull'errore, se presente, per acquisire 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. |
|
Il puntatore specificato dai parametri UnitId, Identity, SubFactor o RejectDetail non può essere NULL. |
|
Impossibile acquisire l'esempio. Usare il valore RejectDetail per altre informazioni. |
|
Impossibile completare l'operazione perché l'unità biometrica è attualmente usata per una transazione di registrazione (solo pool di sistema). |
|
L'esempio biometrico non corrisponde a alcun salvataggio nel database. |
Commenti
Il valore restituito nel parametro SubFactor specifica il sotto-fattore associato all'esempio biometrico. Windows Biometric Framework (WBF) supporta attualmente solo l'acquisizione delle impronte digitali e usa 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
Per usare WinBioIdentify 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 WINBIO_IDENTITY e WINBIO_BIOMETRIC_SUBTYPE informazioni in una struttura Di identificazione annidata. Se l'operazione ha esito negativo, il framework restituisce WINBIO_REJECT_DETAIL informazioni nella struttura Identifica . 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 WinBioIdentifyWithCallback . 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_IDENTIFY_CALLBACK implementata dall'applicazione.
Esempio
La funzione seguente chiama WinBioEnumEnrollments per enumerare i sotto-fattori biometrici registrati per un modello e chiama WinBioIdentify per recuperare un oggetto WINBIO_IDENTITY che identifica l'utente. Collegare alla libreria statica Winbio.lib e includere i file di intestazione seguenti:
- 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;
}
Requisiti
| Requisito | Valore |
|---|---|
| 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 |