Fungsi WinBioAsyncOpenSession (winbio.h)

Secara asinkron terhubung ke penyedia layanan biometrik dan satu atau beberapa unit biometrik. Dimulai dengan Windows 10, build 1607, fungsi ini tersedia untuk digunakan dengan gambar seluler. Jika berhasil, fungsi mengembalikan handel sesi biometrik. Setiap operasi yang dilakukan dengan menggunakan handel ini akan diselesaikan secara asinkron, termasuk WinBioCloseSession, dan hasilnya akan dikembalikan ke aplikasi klien dengan menggunakan metode yang ditentukan dalam parameter NotificationMethod .

Untuk versi sinkron fungsi ini, lihat WinBioOpenSession.

Sintaks

HRESULT WinBioAsyncOpenSession(
  [in]            WINBIO_BIOMETRIC_TYPE             Factor,
  [in]            WINBIO_POOL_TYPE                  PoolType,
  [in]            WINBIO_SESSION_FLAGS              Flags,
  [in, optional]  WINBIO_UNIT_ID                    *UnitArray,
  [in, optional]  SIZE_T                            UnitCount,
  [in, optional]  GUID                              *DatabaseId,
  [in]            WINBIO_ASYNC_NOTIFICATION_METHOD  NotificationMethod,
  [in, optional]  HWND                              TargetWindow,
  [in, optional]  UINT                              MessageCode,
  [in, optional]  PWINBIO_ASYNC_COMPLETION_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                             UserData,
  [in]            BOOL                              AsynchronousOpen,
  [out, optional] WINBIO_SESSION_HANDLE             *SessionHandle
);

Parameter

[in] Factor

Bitmask bendera WINBIO_BIOMETRIC_TYPE yang menentukan jenis unit biometrik yang akan dijumlahkan. Hanya WINBIO_TYPE_FINGERPRINT yang saat ini didukung.

[in] PoolType

Nilai ULONG yang menentukan jenis unit biometrik yang akan digunakan dalam sesi. Ini bisa menjadi salah satu nilai berikut:

Nilai	Makna
WINBIO_POOL_SYSTEM	Sesi ini terhubung ke kumpulan unit biometrik bersama yang dikelola oleh penyedia layanan.
WINBIO_POOL_PRIVATE	Sesi ini terhubung ke kumpulan unit biometrik yang dikelola oleh pemanggil.

[in] Flags

Nilai ULONG yang menentukan konfigurasi unit biometrik dan karakteristik akses untuk sesi baru. Bendera konfigurasi menentukan konfigurasi umum unit dalam sesi. Bendera akses menentukan bagaimana aplikasi akan menggunakan unit biometrik. Anda harus menentukan satu bendera konfigurasi tetapi Anda dapat menggabungkan bendera tersebut dengan bendera akses apa pun.

Nilai	Makna
WINBIO_FLAG_DEFAULT	Grup: konfigurasi Unit biometrik beroperasi dengan cara yang ditentukan selama penginstalan. Anda harus menggunakan nilai ini saat parameter PoolTypeWINBIO_POOL_SYSTEM.
WINBIO_FLAG_BASIC	Grup: konfigurasi Unit biometrik hanya beroperasi sebagai perangkat tangkapan dasar. Semua operasi pemrosesan, pencocokan, dan penyimpanan dilakukan oleh plug-in perangkat lunak.
WINBIO_FLAG_ADVANCED	Grup: konfigurasi Unit biometrik menggunakan kemampuan pemrosesan dan penyimpanan internal.
WINBIO_FLAG_RAW	Grup: akses Aplikasi klien menangkap data biometrik mentah menggunakan WinBioCaptureSample.
WINBIO_FLAG_MAINTENANCE	Grup: akses Klien melakukan operasi kontrol yang ditentukan vendor pada unit biometrik dengan memanggil WinBioControlUnitPrivileged.

[in, optional] UnitArray

Penunjuk ke array pengidentifikasi unit biometrik yang akan disertakan dalam sesi. Anda dapat memanggil WinBioEnumBiometricUnits untuk menghitung unit biometrik. Atur nilai ini ke NULL jika parameter PoolTypeWINBIO_POOL_SYSTEM.

[in, optional] UnitCount

Nilai yang menentukan jumlah elemen dalam array yang diarahkan oleh parameter UnitArray . Atur nilai ini ke nol jika parameter PoolTypeWINBIO_POOL_SYSTEM.

[in, optional] DatabaseId

Nilai yang menentukan database yang akan digunakan oleh sesi. Jika parameter PoolTypeWINBIO_POOL_PRIVATE, Anda harus menentukan GUID database yang diinstal. Jika parameter PoolType tidak WINBIO_POOL_PRIVATE, Anda dapat menentukan salah satu nilai umum berikut.

Nilai	Makna
WINBIO_DB_DEFAULT	Setiap unit biometrik di kumpulan sensor menggunakan database default yang ditentukan dalam konfigurasi unit biometrik default. Anda harus menentukan nilai ini jika parameter PoolTypeWINBIO_POOL_SYSTEM. Anda tidak dapat menggunakan nilai ini jika parameter PoolTypeWINBIO_POOL_PRIVATE
WINBIO_DB_BOOTSTRAP	Anda dapat menentukan nilai ini yang akan digunakan untuk skenario sebelum memulai Windows. Biasanya, database adalah bagian dari chip sensor atau merupakan bagian dari BIOS dan hanya dapat digunakan untuk pendaftaran dan penghapusan templat.
WINBIO_DB_ONCHIP	Database ada di chip sensor dan tersedia untuk pendaftaran dan pencocokan.

[in] NotificationMethod

Menentukan bagaimana pemberitahuan penyelesaian untuk operasi asinkron dalam sesi biometrik ini akan dikirimkan ke aplikasi klien. Ini harus menjadi salah satu nilai berikut.

Nilai	Makna
WINBIO_ASYNC_NOTIFY_CALLBACK	Sesi memanggil fungsi panggilan balik yang ditentukan oleh aplikasi.
WINBIO_ASYNC_NOTIFY_MESSAGE	Sesi memposting pesan jendela ke antrean pesan aplikasi.

[in, optional] TargetWindow

Tangani jendela yang akan menerima pemberitahuan penyelesaian. Nilai ini diabaikan kecuali parameter NotificationMethod diatur ke WINBIO_ASYNC_NOTIFY_MESSAGE.

[in, optional] MessageCode

Kode pesan jendela yang harus dikirim kerangka kerja untuk menandakan pemberitahuan penyelesaian. Nilai ini diabaikan kecuali parameter NotificationMethod diatur ke WINBIO_ASYNC_NOTIFY_MESSAGE. Nilai harus berada dalam rentang WM_APP(0x8000) hingga 0xBFFF.

Windows Biometric Framework menetapkan nilai LPARAM pesan ke alamat struktur WINBIO_ASYNC_RESULT yang berisi hasil operasi. Anda harus memanggil WinBioFree untuk merilis struktur setelah Anda selesai menggunakannya.

[in, optional] CallbackRoutine

Alamat rutinitas panggilan balik yang akan dipanggil ketika operasi dimulai dengan menggunakan handel sesi selesai. Nilai ini diabaikan kecuali parameter NotificationMethod diatur ke WINBIO_ASYNC_NOTIFY_CALLBACK.

[in, optional] UserData

Alamat buffer yang disediakan oleh pemanggil. Buffer tidak dimodifikasi oleh kerangka kerja atau unit biometrik. Ini dikembalikan dalam struktur WINBIO_ASYNC_RESULT . Aplikasi Anda dapat menggunakan data untuk membantunya menentukan tindakan apa yang harus dilakukan setelah menerima pemberitahuan penyelesaian atau untuk mempertahankan informasi tambahan tentang operasi yang diminta.

[in] AsynchronousOpen

Menentukan apakah akan memblokir hingga sesi kerangka kerja dibuka. Menentukan FALSE menyebabkan proses diblokir. Menentukan TRUE menyebabkan sesi dibuka secara asinkron.

Jika Anda menentukan FALSE untuk membuka sesi kerangka kerja secara sinkron, keberhasilan atau kegagalan dikembalikan ke pemanggil secara langsung oleh fungsi ini dalam nilai pengembalian HRESULT . Jika sesi berhasil dibuka, peristiwa penyelesaian asinkron pertama yang diterima aplikasi Anda akan untuk operasi asinkron yang diminta setelah kerangka kerja terbuka.

Jika Anda menentukan TRUE untuk membuka sesi kerangka kerja secara asinkron, pemberitahuan penyelesaian asinkron pertama yang diterima adalah untuk membuka kerangka kerja. Jika parameter NotificationMethod diatur ke WINBIO_ASYNC_NOTIFY_CALLBACK, hasil operasi dikirimkan ke struktur WINBIO_ASYNC_RESULT dalam fungsi panggilan balik yang ditentukan oleh parameter CallbackRoutine . Jika parameter NotificationMethod diatur ke WINBIO_ASYNC_NOTIFY_MESSAGE, hasil operasi dikirimkan ke struktur WINBIO_ASYNC_RESULT yang diacu oleh bidang LPARAM dari pesan jendela.

[out, optional] SessionHandle

Jika fungsi tidak berhasil, parameter ini akan menjadi NULL.

Jika sesi dibuka secara sinkron dan berhasil, parameter ini akan berisi penunjuk ke handel sesi.

Jika Anda menentukan bahwa sesi dibuka secara asinkron, metode ini segera kembali, handel sesi akan null, dan Anda harus memeriksa struktur WINBIO_ASYNC_RESULT untuk menentukan apakah sesi berhasil dibuka.

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
E_OUTOFMEMORY	Tidak tersedia cukup memori untuk membuat sesi biometrik.
E_INVALIDARG	Jika Anda mengatur metode pemberitahuan ke WINBIO_ASYNC_NOTIFY_MESSAGE, parameter TargetWindow tidak boleh NULL atau HWND_BROADCAST dan parameter MessageCode tidak boleh nol (0).
E_POINTER	Parameter SessionHandle dan parameter AsynchronousOpen harus diatur. Jika Anda mengatur metode pemberitahuan ke WINBIO_ASYNC_NOTIFY_CALLBACK, Anda juga harus menentukan alamat fungsi panggilan balik dalam parameter CallbackRoutine .
E_ACCESSDENIED	Parameter Bendera berisi WINBIO_FLAG_RAW atau bendera WINBIO_FLAG_MAINTENANCE dan pemanggil belum diberikan izin akses.
WINBIO_E_INVALID_UNIT	Satu atau beberapa nomor unit biometrik yang ditentukan dalam parameter UnitArray tidak valid.
WINBIO_E_NOT_ACTIVE_CONSOLE	Aplikasi klien berjalan pada klien desktop jarak jauh dan mencoba membuka sesi kumpulan sistem.
WINBIO_E_SENSOR_UNAVAILABLE	Parameter PoolType diatur ke WINBIO_POOL_PRIVATE dan satu atau beberapa sensor yang diminta di kumpulan tersebut tidak tersedia.
WINBIO_E_DISABLED	Kebijakan administratif saat ini melarang penggunaan Windows Biometric Framework API.

Keterangan

Handel sesi yang dikembalikan oleh fungsi WinBioAsyncOpenSession dapat digunakan untuk menghasilkan pemberitahuan penyelesaian asinkron untuk salah satu fungsi berikut:

• WinBioCancel
• WinBioCaptureSample
• WinBioCloseSession
• WinBioControlUnit
• WinBioControlUnitPrivileged
• WinBioDeleteTemplate
• WinBioEnrollBegin
• WinBioEnrollCapture
• WinBioEnrollCommit
• WinBioEnrollDiscard
• WinBioEnumEnrollments
• WinBioGetProperty
• WinBioIdentify
• WinBioLocateSensor
• WinBioLockUnit
• WinBioLogonIdentifiedUser
• WinBioRegisterEventMonitor
• WinBioUnlockUnit
• WinBioUnregisterEventMonitor
• WinBioVerify
• WinBioWait

Handel sesi yang dikembalikan oleh WinBioAsyncOpenSession tidak dapat digunakan dengan fungsi berikut:

• WinBioCaptureSampleWithCallback
• WinBioEnrollCaptureWithCallback
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

Fungsi-fungsi ini, pertama kali tersedia di Windows 7, memiliki tanda tangan panggilan balik yang tidak kompatibel, dan penggunaannya dalam aplikasi baru tidak disarankan. Pengembang yang menginginkan panggilan balik asinkron harus menggunakan WinBioAsyncOpenSession dengan NotificationMethodWINBIO_ASYNC_NOTIFY_CALLBACK.

Parameter AsynchronousOpen hanya menentukan apakah operasi terbuka akan diblokir. Parameter ini tidak berpengaruh pada perilaku penyelesaian panggilan berikutnya yang menggunakan handel sesi.

Jika Anda mengatur parameter AsynchronousOpen ke TRUE, fungsi ini akan mengembalikan S_OK segera setelah melakukan validasi awal argumen. Setiap kesalahan yang terdeteksi di luar titik tersebut akan dilaporkan ke pemanggil menggunakan metode yang ditentukan oleh parameter NotificationMethod . Artinya, nilai pengembalian yang berhasil hanya menunjukkan bahwa parameter WinBioAsyncOpenSession baik-baik saja dan bukan bahwa operasi terbuka berhasil. Untuk menentukan apakah operasi terbuka berhasil, Anda harus memeriksa struktur WINBIO_ASYNC_RESULT .

Persyaratan

Klien minimum yang didukung	Windows 8 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 [hanya aplikasi desktop]
Target Platform	Windows
Header	winbio.h (termasuk Winbio.h)
Pustaka	Winbio.lib
DLL	Winbio.dll

Lihat juga

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession