Fungsi WinBioGetProperty (winbio.h)

Artikel
03/08/2023

Mengambil properti sesi, unit, atau templat. Dimulai dengan Windows 10, build 1607, fungsi ini tersedia untuk digunakan dengan gambar seluler.

Sintaks

HRESULT WinBioGetProperty(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_PROPERTY_TYPE     PropertyType,
  [in]            WINBIO_PROPERTY_ID       PropertyId,
  [in, optional]  WINBIO_UNIT_ID           UnitId,
  [in, optional]  WINBIO_IDENTITY          *Identity,
  [in, optional]  WINBIO_BIOMETRIC_SUBTYPE SubFactor,
                  PVOID                    *PropertyBuffer,
  [out, optional] SIZE_T                   *PropertyBufferSize
);

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] PropertyType

Nilai WINBIO_PROPERTY_TYPE yang menentukan sumber informasi properti. Saat ini harus WINBIO_PROPERTY_TYPE_UNIT atau WINBIO_PROPERTY_TYPE_ACCOUNT. Untuk informasi selengkapnya tentang jenis properti, lihat konstanta WINBIO_PROPERTY_TYPE.

Nilai WINBIO_PROPERTY_TYPE_ACCOUNT didukung mulai dari Windows 10.

[in] PropertyId

Nilai WINBIO_PROPERTY_ID yang menentukan properti yang ingin Anda kueri. Nilai berikut dimungkinkan.

Nilai	Makna
WINBIO_PROPERTY_SAMPLE_HINT	Memperkirakan jumlah maksimum sampel biometrik yang baik yang diperlukan untuk menyelesaikan templat pendaftaran. Hasil kueri properti dikembalikan dalam buffer tempat parameter PropertyBuffer menunjuk sebagai nilai ULONG yang berisi petunjuk.
WINBIO_PROPERTY_EXTENDED_SENSOR_INFO	Berisi informasi yang diperluas tentang kemampuan dan atribut komponen sensor yang terhubung ke unit biometrik tertentu. Hasil kueri properti dikembalikan dalam buffer tempat parameter PropertyBuffer menunjuk sebagai struktur WINBIO_EXTENDED_SENSOR_INFO . Nilai ini didukung mulai dari Windows 10.
WINBIO_PROPERTY_EXTENDED_ENGINE_INFO	Berisi informasi yang diperluas tentang kemampuan dan atribut komponen mesin yang terhubung ke unit biometrik tertentu. Hasil kueri properti dikembalikan dalam buffer tempat parameter PropertyBuffer menunjuk sebagai struktur WINBIO_EXTENDED_ENGINE_INFO . Nilai ini didukung mulai dari Windows 10.
WINBIO_PROPERTY_EXTENDED_STORAGE_INFO	Berisi informasi yang diperluas tentang kemampuan dan atribut komponen penyimpanan yang terhubung ke unit biometrik tertentu. Hasil kueri properti dikembalikan dalam buffer tempat parameter PropertyBuffer menunjuk sebagai struktur WINBIO_EXTENDED_STORAGE_INFO . Nilai ini didukung mulai dari Windows 10.
WINBIO_PROPERTY_EXTENDED_ENROLLMENT_STATUS	Berisi informasi yang diperluas tentang status pendaftaran yang sedang berlangsung pada unit biometrik tertentu. Hasil kueri properti dikembalikan dalam buffer tempat parameter PropertyBuffer menunjuk sebagai struktur WINBIO_EXTENDED_ENROLLMENT_STATUS . Jika tidak ada pendaftaran yang sedang berlangsung pada unit biometrik, anggota TemplateStatus dari struktur yang dikembalikan memiliki nilai WINBIO_E_INVALID_OPERATION. Nilai ini didukung mulai dari Windows 10.
WINBIO_PROPERTY_ANTI_SPOOF_POLICY	Berisi nilai kebijakan antispoofing untuk akun pengguna tertentu. Operasi properti dikembalikan dalam buffer tempat parameter PropertyBuffer menunjuk sebagai struktur WINBIO_ANTI_SPOOF_POLICY . Nilai ini didukung mulai dari Windows 10.

Untuk informasi selengkapnya tentang properti ini, lihat konstanta WINBIO_PROPERTY.

[in, optional] UnitId

Nilai WINBIO_UNIT_ID yang mengidentifikasi unit biometrik. Anda dapat menemukan pengidentifikasi unit dengan memanggil fungsi WinBioEnumBiometricUnits atau WinBioLocateSensor .

Jika Anda menentukan WINBIO_PROPERTY_ANTI_SPOOF_POLICY sebagai nilai untuk parameter PropertyId , tentukan 0 untuk parameter UnitId . Jika Anda menentukan properti lain dengan parameter PropertyId , Anda tidak dapat menentukan 0 untuk parameter UnitId .

[in, optional] Identity

Struktur WINBIO_IDENTITY yang menyediakan SID akun yang ingin Anda dapatkan kebijakan antispoofingnya, jika Anda menentukan WINBIO_PROPERTY_ANTI_SPOOF_POLICY sebagai nilai parameter PropertyId .

Jika Anda menentukan nilai lain untuk parameter PropertyId , parameter Identitas harus NULL.

[in, optional] SubFactor

Dicadangkan. Ini harus WINBIO_SUBTYPE_NO_INFORMATION.

PropertyBuffer

Alamat penunjuk ke buffer yang menerima nilai properti. Untuk informasi tentang konten buffer ini untuk properti yang berbeda, lihat deskripsi nilai properti untuk parameter PropertyId .

[out, optional] PropertyBufferSize

Penunjuk ke variabel yang menerima ukuran, dalam byte, dari buffer yang diacu oleh parameter PropertyBuffer .

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
E_HANDLE	Handel sesi yang ditentukan oleh parameter SessionHandle tidak valid.
E_POINTER	Argumen Identity, PropertyBuffer, atau PropertyBufferSize tidak boleh NULL.
E_INVALIDARG	Argumen UnitId, Identity, atau SubFactor salah.
WINBIO_E_INVALID_PROPERTY_TYPE	Nilai argumen PropertyType salah.
WINBIO_E_INVALID_PROPERTY_ID	Nilai argumen PropertyId salah.
WINBIO_E_LOCK_VIOLATION	Pemanggil mencoba mengkueri properti yang berada di dalam wilayah terkunci.
WINBIO_E_UNSUPPORTED_PROPERTY	Objek yang sedang dikueri tidak mendukung properti yang ditentukan.
WINBIO_E_ENROLLMENT_IN_PROGRESS	Operasi tidak dapat diselesaikan karena unit biometrik yang ditentukan saat ini sedang digunakan untuk transaksi pendaftaran (hanya kumpulan sistem).

Keterangan

Untuk menggunakan WinBioGetProperty secara sinkron, panggil fungsi dengan handel sesi yang dibuat dengan memanggil WinBioOpenSession. Fungsi memblokir hingga operasi selesai atau terjadi kesalahan. Untuk mencegah kebocoran memori saat Anda menggunakan WinBioGetProperty secara sinkron, Anda harus memanggil WinBioFree untuk merilis memori yang ditunjukkan oleh parameter PropertyBuffer ketika Anda selesai menggunakan data yang terkandung dalam buffer.

Untuk menggunakan WinBioGetProperty 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 dalam struktur GetProperty berlapis. 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 dari pesan jendela.

Untuk mencegah kebocoran memori ketika Anda menggunakan WinBioGetProperty secara asinkron, Anda harus memanggil WinBioFree untuk merilis struktur WINBIO_ASYNC_RESULT setelah Anda selesai menggunakannya. Struktur WINBIO_ASYNC_RESULT dan buffer properti menempati satu blok memori, sehingga aplikasi Anda hanya perlu meneruskan alamat struktur WINBIO_ASYNC_RESULT ke WinBioFree. Ketika Anda memanggil WinBioFree dengan cara ini, WinBioFree secara otomatis merilis struktur WINBIO_ASYNC_RESULT dan buffer properti. Jika Anda mencoba merilis buffer properti secara terpisah dalam hal ini, aplikasi berhenti merespons.

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

Lihat juga

WinBioFree

WinBioSetProperty

Bagikan melalui