Fungsi WinBioVerifyWithCallback (winbio.h)
Secara asinkron menangkap sampel biometrik dan menentukan apakah sampel sesuai dengan identitas pengguna yang ditentukan. Fungsi ini segera kembali ke pemanggil, melakukan penangkapan dan verifikasi pada utas terpisah, dan memanggil ke fungsi panggilan balik yang ditentukan aplikasi untuk memperbarui status operasi.
Kami menyarankan agar, dimulai dengan Windows 8, Anda tidak lagi menggunakan fungsi ini untuk memulai operasi asinkron. Sebagai gantinya, lakukan hal berikut:
- Terapkan fungsi PWINBIO_ASYNC_COMPLETION_CALLBACK untuk menerima pemberitahuan ketika operasi selesai.
- Panggil fungsi WinBioAsyncOpenSession . Berikan alamat panggilan balik Anda di parameter CallbackRoutine . Teruskan WINBIO_ASYNC_NOTIFY_CALLBACK di parameter NotificationMethod . Ambil handel sesi asinkron.
- Gunakan handel sesi asinkron untuk memanggil WinBioVerify. Ketika operasi selesai, Windows Biometric Framework akan mengalokasikan dan menginisialisasi struktur WINBIO_ASYNC_RESULT dengan hasil dan memanggil panggilan balik Anda dengan penunjuk ke struktur hasil.
- Panggil WinBioFree dari implementasi panggilan balik Anda untuk merilis struktur WINBIO_ASYNC_RESULT setelah Anda selesai menggunakannya.
Sintaks
HRESULT WinBioVerifyWithCallback(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_IDENTITY *Identity,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[in] PWINBIO_VERIFY_CALLBACK VerifyCallback,
[in, optional] PVOID VerifyCallbackContext
);
Parameter
[in] SessionHandle
Nilai WINBIO_SESSION_HANDLE yang mengidentifikasi sesi biometrik terbuka.
[in] Identity
Penunjuk ke struktur WINBIO_IDENTITY yang berisi GUID atau SID pengguna yang menyediakan sampel biometrik.
[in] SubFactor
Nilai WINBIO_BIOMETRIC_SUBTYPE yang menentukan subfaktor yang terkait dengan sampel biometrik. Lihat bagian Keterangan untuk detail selengkapnya.
[in] VerifyCallback
Alamat fungsi panggilan balik yang akan dipanggil oleh fungsi WinBioVerifyWithCallback saat verifikasi berhasil atau gagal. Anda harus membuat panggilan balik.
[in, optional] VerifyCallbackContext
Struktur opsional yang ditentukan aplikasi yang dikembalikan dalam parameter VerifyCallbackContext dari fungsi panggilan balik. Struktur ini dapat berisi data apa pun yang dirancang untuk ditangani oleh fungsi panggilan balik kustom.
Mengembalikan nilai
Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika fungsi gagal, fungsi mengembalikan nilai HRESULT yang menunjukkan kesalahan. Nilai yang mungkin termasuk, tetapi tidak terbatas pada, yang ada dalam tabel berikut. Untuk daftar kode kesalahan umum, lihat Nilai HRESULT Umum.
| Menampilkan kode | Deskripsi |
|---|---|
|
Handel sesi tidak valid. |
|
Argumen SubFaktor salah. |
|
Penunjuk yang ditentukan oleh parameter Identity dan VerifyCallback tidak boleh NULL. |
Keterangan
Parameter SubFactor menentukan subfaktor yang terkait dengan sampel biometrik. Windows Biometric Framework (WBF) saat ini hanya mendukung pengambilan sidik jari dan menggunakan konstanta berikut untuk mewakili informasi subtipe.
- 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
Fungsi WinBioVerifyWithCallback segera kembali dan meneruskan S_OK ke pemanggil. Untuk menentukan status proses penangkapan dan verifikasi, Anda harus memeriksa parameter OperationStatus dalam fungsi panggilan balik Anda.
Anda dapat memanggil fungsi WinBioCancel untuk membatalkan operasi panggilan balik yang tertunda. Menutup sesi juga secara implisit membatalkan panggilan balik untuk sesi tersebut.
Rutinitas panggilan balik harus memiliki tanda tangan berikut:
VOID CALLBACK VerifyCallback(
__in_opt PVOID VerifyCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in BOOLEAN Match,
__in WINBIO_REJECT_DETAIL RejectDetail
);
Contoh
Fungsi berikut memanggil WinBioVerifyWithCallback untuk menentukan secara asinkron apakah sampel biometrik cocok dengan identitas pengguna saat ini yang masuk. Rutinitas panggilan balik, VerifyCallback, dan fungsi pembantu, GetCurrentUserIdentity, juga disertakan. Tautkan ke pustaka statis Winbio.lib dan sertakan file header berikut:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT VerifyWithCallback(BOOL bCancel, WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
// Declare variables.
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
WINBIO_REJECT_DETAIL rejectDetail = 0;
WINBIO_IDENTITY identity = {0};
// 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 asynchronously.
wprintf_s(L"\n Calling WinBioVerifyWithCallback.\n");
hr = WinBioVerifyWithCallback(
sessionHandle, // Open session handle
&identity, // User SID or GUID
subFactor, // Sample sub-factor
VerifyCallback, // Callback function
NULL // Optional context
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioVerifyWithCallback failed. hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Swipe the sensor ...\n");
// Cancel the identification if the bCancel flag is set.
if (bCancel)
{
wprintf_s(L"\n Starting CANCEL timer...\n");
Sleep( 7000 );
wprintf_s(L"\n Calling WinBioCancel\n");
hr = WinBioCancel( sessionHandle );
if (FAILED(hr))
{
wprintf_s(L"\n WinBioCancel failed. hr = 0x%x\n", hr);
goto e_Exit;
}
}
// Wait for the asynchronous identification process to complete
// or be canceled.
hr = WinBioWait( sessionHandle );
if (FAILED(hr))
{
wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
}
e_Exit:
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L"\n Hit any key to continue...");
_getch();
return hr;
}
//------------------------------------------------------------------------
// The following function is the callback for WinBioVerifyWithCallback.
// The function filters the response from the biometric subsystem and
// writes a result to the console window.
//
VOID CALLBACK VerifyCallback(
__in_opt PVOID VerifyCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in BOOLEAN Match,
__in WINBIO_REJECT_DETAIL RejectDetail
)
{
UNREFERENCED_PARAMETER(VerifyCallbackContext);
UNREFERENCED_PARAMETER(Match);
wprintf_s(L"\n VerifyCallback executing");
wprintf_s(L"\n Swipe processed for unit ID %d\n", UnitId);
// The identity could not be verified.
if (FAILED(OperationStatus))
{
wprintf_s(L"\n Verification failed for the following reason:");
if (OperationStatus == WINBIO_E_NO_MATCH)
{
wprintf_s(L"\n No match.\n");
}
else if (OperationStatus == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n Bad capture.\n ");
wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
}
else
{
wprintf_s(L"VerifyCallback failed.");
wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus);
}
goto e_Exit;
}
// The user identity was verified.
wprintf_s(L"\n Fingerprint verified:\n");
e_Exit:
return;
}
//------------------------------------------------------------------------
// 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;
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 7 [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 R2 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winbio.h (termasuk Winbio.h) |
| Pustaka | Winbio.lib |
| DLL | Winbio.dll |