Fungsi WinBioEnrollBegin (winbio.h)
Memulai urutan pendaftaran biometrik dan membuat templat biometrik kosong. Dimulai dengan Windows 10, build 1607, fungsi ini tersedia untuk digunakan dengan gambar seluler.
Sintaks
HRESULT WinBioEnrollBegin(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[in] WINBIO_UNIT_ID UnitId
);
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] SubFactor
Nilai WINBIO_BIOMETRIC_SUBTYPE yang menyediakan informasi tambahan tentang pendaftaran. Ini harus menjadi salah satu nilai berikut:
- 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
[in] UnitId
Nilai WINBIO_UNIT_ID yang mengidentifikasi unit biometrik. Nilai ini tidak boleh nol. Anda dapat menemukan ID unit dengan memanggil fungsi WinBioEnumBiometricUnits atau WinBioLocateSensor .
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 |
---|---|
|
Pemanggil tidak memiliki izin untuk mendaftar. |
|
Handel sesi tidak valid. |
|
Parameter SubFactor tidak dapat sama dengan WINBIO_SUBTYPE_NO_INFORMATION atau WINBIO_SUBTYPE_ANY, dan parameter UnitId tidak boleh sama dengan nol. |
|
Operasi pendaftaran sudah berlangsung, dan hanya satu pendaftaran yang dapat terjadi pada waktu tertentu. |
|
Unit biometrik sedang digunakan dan dikunci. |
Keterangan
Satu pendaftaran biometrik memerlukan pengumpulan beberapa sampel dari pengguna. Hanya satu operasi pendaftaran yang dapat dilakukan kapan saja, dan semua sampel biometrik yang berlaku untuk satu pendaftaran harus dihasilkan oleh sensor yang sama. Sensor ini ditentukan oleh parameter UnitId .
Aplikasi apa pun yang mendaftar dengan menggunakan unit biometrik di kumpulan sistem harus memiliki fokus jendela saat memanggil WinBioEnrollBegin. Jika tidak, panggilan memblokir hingga aplikasi memperoleh fokus jendela dan pengguna telah memberikan sampel biometrik. Oleh karena itu, kami menyarankan agar aplikasi Anda tidak memanggil WinBioEnrollBegin 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 WinBioEnrollBegin secara sinkron, panggil fungsi dengan handel sesi yang dibuat dengan memanggil WinBioOpenSession. Fungsi memblokir hingga operasi selesai atau terjadi kesalahan.
Untuk menggunakan WinBioEnrollBegin 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 informasi WINBIO_BIOMETRIC_SUBTYPE dalam struktur EnrollBegin berlapis. Jika operasi tidak berhasil, kerangka kerja mengembalikan informasi kesalahan. 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.
Contoh
Fungsi berikut mendaftarkan templat biometrik di kumpulan sistem. Ini memanggil WinBioEnrollBegin untuk memulai urutan pendaftaran. Tautkan ke pustaka statis Winbio.lib dan sertakan file header berikut:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT EnrollSysPool(
BOOL discardEnrollment,
WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
HRESULT hr = S_OK;
WINBIO_IDENTITY identity = {0};
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
WINBIO_REJECT_DETAIL rejectDetail = 0;
BOOLEAN isNewTemplate = TRUE;
// 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. ");
wprintf_s(L"hr = 0x%x\n", hr);
goto e_Exit;
}
// Locate a sensor.
wprintf_s(L"\n Swipe your finger on the sensor...\n");
hr = WinBioLocateSensor( sessionHandle, &unitId);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Begin the enrollment sequence.
wprintf_s(L"\n Starting enrollment sequence...\n");
hr = WinBioEnrollBegin(
sessionHandle, // Handle to open biometric session
subFactor, // Finger to create template for
unitId // Biometric unit ID
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnrollBegin failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Capture enrollment information by swiping the sensor with
// the finger identified by the subFactor argument in the
// WinBioEnrollBegin function.
for (int swipeCount = 1;; ++swipeCount)
{
wprintf_s(L"\n Swipe the sensor to capture %s sample.",
(swipeCount == 1)?L"the first":L"another");
hr = WinBioEnrollCapture(
sessionHandle, // Handle to open biometric session
&rejectDetail // [out] Failure information
);
wprintf_s(L"\n Sample %d captured from unit number %d.",
swipeCount,
unitId);
if (hr == WINBIO_I_MORE_DATA)
{
wprintf_s(L"\n More data required.\n");
continue;
}
if (FAILED(hr))
{
if (hr == WINBIO_E_BAD_CAPTURE)
{
wprintf_s(L"\n Error: Bad capture; reason: %d",
rejectDetail);
continue;
}
else
{
wprintf_s(L"\n WinBioEnrollCapture failed. hr = 0x%x", hr);
goto e_Exit;
}
}
else
{
wprintf_s(L"\n Template completed.\n");
break;
}
}
// Discard the enrollment if the appropriate flag is set.
// Commit the enrollment if it is not discarded.
if (discardEnrollment == TRUE)
{
wprintf_s(L"\n Discarding enrollment...\n\n");
hr = WinBioEnrollDiscard( sessionHandle );
if (FAILED(hr))
{
wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
}
goto e_Exit;
}
else
{
wprintf_s(L"\n Committing enrollment...\n");
hr = WinBioEnrollCommit(
sessionHandle, // Handle to open biometric session
&identity, // WINBIO_IDENTITY object for the user
&isNewTemplate); // Is this a new template
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnrollCommit failed. hr = 0x%x\n", hr);
goto e_Exit;
}
}
e_Exit:
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L" Press any key to continue...");
_getch();
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 |