Fungsi WinBioCaptureSample (winbio.h)

  • Artikel

Mengambil sampel biometrik dan mengisi rekaman informasi biometrik (BIR) dengan data mentah atau yang diproses.

Sintaks

HRESULT WinBioCaptureSample(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_BIR_PURPOSE    Purpose,
  [in]            WINBIO_BIR_DATA_FLAGS Flags,
  [out, optional] WINBIO_UNIT_ID        *UnitId,
                  PWINBIO_BIR           *Sample,
  [out, optional] SIZE_T                *SampleSize,
  [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] Purpose

Bitmask WINBIO_BIR_PURPOSE yang menentukan penggunaan sampel yang dimaksudkan. Ini bisa menjadi bitwise ATAU dari nilai berikut:

  • WINBIO_PURPOSE_VERIFY
  • WINBIO_PURPOSE_IDENTIFY
  • WINBIO_PURPOSE_ENROLL
  • WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
  • WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

Nilai yang menentukan jenis pemrosesan yang akan diterapkan ke sampel yang diambil. Ini bisa menjadi bitwise ATAU dari bendera tingkat keamanan dan pemrosesan berikut:

  • WINBIO_DATA_FLAG_PRIVACY

Enkripsi sampel.

  • WINBIO_DATA_FLAG_INTEGRITY

Menandatangani sampel atau melindunginya dengan menggunakan kode autentikasi pesan (MAC)

  • WINBIO_DATA_FLAG_SIGNED

Jika bendera ini dan bendera WINBIO_DATA_FLAG_INTEGRITY diatur, tanda tangani sampel. Jika bendera ini tidak diatur tetapi bendera WINBIO_DATA_FLAG_INTEGRITY diatur, komputasi MAC.

  • WINBIO_DATA_FLAG_RAW

Kembalikan sampel persis seperti yang ditangkap oleh sensor.

  • WINBIO_DATA_FLAG_INTERMEDIATE

Kembalikan sampel setelah dibersihkan dan difilter.

  • WINBIO_DATA_FLAG_PROCESSED

Kembalikan sampel setelah siap digunakan untuk tujuan yang ditentukan oleh parameter Tujuan.

[out, optional] UnitId

Pointer ke nilai WINBIO_UNIT_ID yang berisi ID unit biometrik yang menghasilkan sampel.

Sample

Alamat variabel yang menerima penunjuk ke struktur WINBIO_BIR yang berisi sampel. Setelah selesai menggunakan struktur, Anda harus meneruskan pointer ke WinBioFree untuk merilis memori yang dialokasikan untuk sampel.

[out, optional] SampleSize

Penunjuk ke nilai SIZE_T yang berisi ukuran, dalam byte, dari struktur WINBIO_BIR yang dikembalikan dalam parameter Sampel .

[out, optional] RejectDetail

Penunjuk ke nilai WINBIO_REJECT_DETAIL 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

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_ACCESSDENIED
 Pemanggil tidak memiliki izin untuk mengambil sampel mentah, atau sesi tidak dibuka dengan menggunakan bendera WINBIO_FLAG_RAW .
E_HANDLE
 Handel sesi tidak valid.
E_NOTIMPL
 Unit biometrik tidak mendukung operasi yang diminta.
E_POINTER
 Pointer UnitId, Sample, SampleSize, dan RejectDetail 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).
WINBIO_E_INVALID_OPERATION
 Operasi tidak dapat diselesaikan karena sensor aman ada di kumpulan sensor.

Keterangan

Untuk berhasil memanggil fungsi ini, Anda harus membuka handel sesi dengan menentukan WINBIO_FLAG_RAW dalam parameter Bendera fungsi WinBioOpenSession atau WinBioAsyncOpenSession . Saat ini, hanya aplikasi yang berjalan di bawah Administrator dan akun Sistem Lokal yang memiliki hak istimewa yang diperlukan.

Kombinasi parameter Tujuan dan Bendera yang valid bergantung pada kemampuan unit biometrik yang digunakan. Lihat dokumentasi sensor vendor untuk menentukan kombinasi nilai Tujuan dan Bendera yang valid mana yang didukung dan pengaruhnya terhadap data yang diambil. Setelah Anda selesai menggunakan sampel, aplikasi Anda harus memanggil WinBioFree untuk merilis memori yang dialokasikan untuk itu oleh fungsi WinBioCaptureSample .

Untuk menggunakan WinBioCaptureSample secara sinkron, panggil fungsi dengan handel sesi yang dibuat dengan memanggil WinBioOpenSession. Fungsi memblokir hingga sampel diambil atau terjadi kesalahan. Panggilan ke WinBioCaptureSample menggunakan kumpulan sistem akan memblokir hingga aplikasi panggilan memiliki fokus jendela dan pengguna memberikan sampel ke salah satu sensor di kumpulan. Jika sensor yang dipilih oleh pengguna sudah digunakan untuk transaksi pendaftaran, fungsi gagal dan mengembalikan WINBIO_E_ENROLLMENT_IN_PROGRESS.

Untuk menggunakan WinBioCaptureSample 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 pengambilan berhasil, kerangka kerja mengembalikan informasi tentang sampel dalam struktur CaptureSample 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.
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 WinBioCaptureSampleWithCallback . 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_CAPTURE_CALLBACK yang diterapkan oleh aplikasi Anda.

Contoh

Fungsi berikut memanggil WinBioCaptureSample untuk mengambil sampel biometrik dari pengguna. Tautkan ke pustaka statis Winbio.lib dan sertakan file header berikut:

  • Windows.h
  • Stdio.h
  • Conio.h
  • Winbio.h
HRESULT CaptureSample()
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    PWINBIO_BIR sample = NULL;
    SIZE_T sampleSize = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Access: Capture raw data
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            WINBIO_DB_DEFAULT,          // Default database
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture a biometric sample.
    wprintf_s(L"\n Calling WinBioCaptureSample - Swipe sensor...\n");
    hr = WinBioCaptureSample(
            sessionHandle,
            WINBIO_NO_PURPOSE_AVAILABLE,
            WINBIO_DATA_FLAG_RAW,
            &unitId,
            &sample,
            &sampleSize,
            &rejectDetail
            );
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioCaptureSample failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    wprintf_s(L"\n Captured %d bytes.\n", sampleSize);


e_Exit:
    if (sample != NULL)
    {
        WinBioFree(sample);
        sample = NULL;
    }

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

    wprintf_s(L"\n Press 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

WinBioCaptureSampleWithCallback