Fungsi WinBioLocateSensor (winbio.h)

Artikel
08/27/2023

Mengambil nomor ID unit biometrik yang dipilih secara interaktif oleh pengguna.

Sintaks

HRESULT WinBioLocateSensor(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [out, optional] 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.

[out, optional] UnitId

Penunjuk ke nilai ULONG yang menentukan unit biometrik.

Menampilkan 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_HANDLE	Handel sesi tidak valid.
E_POINTER	Penunjuk yang ditentukan oleh parameter UnitId tidak boleh NULL.
WINBIO_E_ENROLLMENT_IN_PROGRESS	Operasi tidak dapat diselesaikan karena unit biometrik saat ini sedang digunakan untuk transaksi pendaftaran (hanya kumpulan sistem).

Keterangan

Anda dapat menggunakan fungsi ini pada sistem dengan beberapa sensor untuk menentukan sensor mana yang lebih disukai untuk pendaftaran oleh pengguna. Tidak ada informasi identifikasi yang dikembalikan oleh fungsi ini. Ini disediakan hanya untuk menunjukkan pemilihan sensor pengguna.

Panggilan ke fungsi ini menggunakan kumpulan sistem akan memblokir sampai aplikasi memperoleh fokus jendela dan pengguna telah memberikan sampel biometrik. Oleh karena itu, kami menyarankan agar aplikasi Anda tidak memanggil WinBioLocateSensor sampai 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 WinBioLocateSensor secara sinkron, panggil fungsi dengan handel sesi yang dibuat dengan memanggil WinBioOpenSession. Fungsi memblokir hingga operasi selesai atau terjadi kesalahan.

Untuk menggunakan WinBioLocateSensor 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. 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, Anda harus memanggil WinBioFree untuk merilis struktur WINBIO_ASYNC_RESULT setelah Anda selesai menggunakannya.

Windows 7: Anda dapat melakukan operasi ini secara asinkron dengan menggunakan fungsi WinBioLocateSensorWithCallback . 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_LOCATE_SENSOR_CALLBACK yang diterapkan oleh aplikasi Anda.

Contoh

Fungsi berikut memanggil WinBioLocateSensor untuk menemukan sensor biometrik yang terpasang. Tautkan ke pustaka statis Winbio.lib dan sertakan file header berikut:

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT LocateSensor( )
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;

    // 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 WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate the sensor.
    wprintf_s(L"\n Tap the sensor once...\n");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Sensor located successfully. ");
    wprintf_s(L"\n Unit ID = %d \n", unitId);

e_Exit:
    if (sessionHandle != NULL)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

    wprintf_s(L"\n Hit any key to exit...");
    _getch();

    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

WinBioLocateSensorWithCallback

Bagikan melalui