Fungsi WinBioVerify (winbio.h)
Mengambil sampel biometrik dan menentukan apakah sampel sesuai dengan identitas pengguna yang ditentukan. Dimulai dengan Windows 10, build 1607, fungsi ini tersedia untuk digunakan dengan gambar seluler.
Sintaks
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
);
Parameter
[in] SessionHandle
Nilai WINBIO_SESSION_HANDLE yang mengidentifikasi sesi biometrik terbuka. Buka handel sesi sinkron dengan memanggil WinBioOpenSession. Buka handel sesi asinkron dengan memanggil WinBioAsyncOpenSession.
[in] Identity
Arahkan 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. Windows Biometric Framework (WBF) saat ini hanya mendukung pengambilan sidik jari dan dapat 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
- WINBIO_SUBTYPE_ANY
[out, optional] UnitId
Penunjuk ke nilai WINBIO_UNIT_ID yang menentukan unit biometrik yang melakukan verifikasi.
[out, optional] Match
Penunjuk ke nilai Boolean yang menentukan apakah sampel yang diambil cocok dengan identitas pengguna yang ditentukan oleh parameter Identitas .
[out, optional] RejectDetail
Penunjuk ke nilai ULONG yang berisi informasi tambahan tentang kegagalan untuk mengambil sampel biometrik. Jika pengambilan berhasil, parameter ini diatur ke nol. Nilai berikut didefinisikan untuk pengambilan sidik jari:
- 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
Nilai kembali
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 SubFactor salah. |
|
Penunjuk yang ditentukan oleh parameter UnitId, Identity, SubFactor, atau RejectDetail tidak boleh NULL. |
|
Sampel biometrik tidak dapat ditangkap. Gunakan nilai RejectDetail untuk informasi selengkapnya. |
|
Operasi tidak dapat diselesaikan karena unit biometrik yang ditentukan saat ini sedang digunakan untuk transaksi pendaftaran (hanya kumpulan sistem). |
|
Sampel biometrik tidak sesuai dengan kombinasi Identitas dan SubFactor yang ditentukan. |
Keterangan
Jika pengambilan sampel biometrik gagal, parameter UnitId akan berisi nomor unit sensor yang mencoba melakukan penangkapan.
Panggilan ke fungsi ini menggunakan kumpulan sistem akan memblokir hingga aplikasi memperoleh fokus jendela dan pengguna telah memberikan sampel biometrik. Oleh karena itu, kami menyarankan agar aplikasi Anda tidak memanggil WinBioVerify hingga memperoleh fokus. Cara Anda memperoleh fokus tergantung pada jenis aplikasi yang Anda tulis. Misalnya, jika Anda membuat aplikasi GUI, Anda dapat mengimplementasikan penangan pesan yang menangkap WM_ACTIVATE, WM_SETFOCUS, atau pesan lain yang sesuai. Jika Anda menulis aplikasi CUI, panggil GetConsoleWindow untuk mengambil handel ke jendela konsol dan meneruskan handel tersebut ke fungsi SetForegroundWindow untuk memaksa jendela konsol ke latar depan dan menetapkan fokusnya. Jika aplikasi Anda berjalan dalam proses yang dilepas dan tidak memiliki jendela atau merupakan layanan Windows, gunakan WinBioAcquireFocus dan WinBioReleaseFocus untuk mengontrol fokus secara manual.
Untuk menggunakan WinBioVerify secara sinkron, panggil fungsi dengan handel sesi yang dibuat dengan memanggil WinBiopenSession. Fungsi memblokir hingga operasi selesai atau terjadi kesalahan.
Untuk menggunakan WinBioVerify secara asinkron, panggil fungsi dengan handel sesi yang dibuat dengan memanggil WinBioAsyncOpenSession. Kerangka kerja mengalokasikan struktur WINBIO_ASYNC_RESULT dan menggunakannya untuk mengembalikan informasi tentang keberhasilan atau kegagalan operasi. Jika operasi berhasil, kerangka kerja mengembalikan nilai kecocokan BOOLEAN dalam struktur Verifikasi berlapis. Jika operasi tidak berhasil, kerangka kerja mengembalikan informasi WINBIO_REJECT_DETAIL dalam struktur Verifikasi . Struktur WINBIO_ASYNC_RESULT dikembalikan ke panggilan balik aplikasi atau ke antrean pesan aplikasi, tergantung pada nilai yang Anda tetapkan dalam parameter NotificationMethod dari fungsi WinBioAsyncOpenSession :
- Jika Anda memilih untuk menerima pemberitahuan penyelesaian dengan menggunakan panggilan balik, Anda harus menerapkan fungsi PWINBIO_ASYNC_COMPLETION_CALLBACK dan mengatur parameter NotificationMethod ke WINBIO_ASYNC_NOTIFY_CALLBACK.
- Jika Anda memilih untuk menerima pemberitahuan penyelesaian dengan menggunakan antrean pesan aplikasi, Anda harus mengatur parameter NotificationMethod ke WINBIO_ASYNC_NOTIFY_MESSAGE. Kerangka kerja mengembalikan penunjuk WINBIO_ASYNC_RESULT ke bidang LPARAM pesan jendela.
Windows 7: Anda dapat melakukan operasi ini secara asinkron dengan menggunakan fungsi WinBioVerifyWithCallback . Fungsi memverifikasi argumen input dan segera kembali. Jika argumen input tidak valid, fungsi mengembalikan kode kesalahan. Jika tidak, kerangka kerja memulai operasi pada utas lain. Ketika operasi asinkron selesai atau mengalami kesalahan, kerangka kerja mengirimkan hasilnya ke fungsi PWINBIO_VERIFY_CALLBACK yang diterapkan oleh aplikasi Anda.
Contoh
Fungsi berikut memanggil WinBioVerify untuk menentukan apakah sampel biometrik cocok dengan identitas pengguna saat ini yang masuk. 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 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;
}
Persyaratan
| 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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk