Bagikan melalui

Fungsi WinBioVerify (winbio.h)

  • Artikel

Mengambil sampel biometrik dan menentukan apakah sampel sesuai dengan identitas pengguna yang ditentukan. Dimulai dengan Windows 10, build 1607, fungsi ini tersedia untuk digunakan dengan gambar seluler.

Sintaks

HRESULT WinBioVerify(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_IDENTITY          *Identity,
  [in]            WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [out, optional] WINBIO_UNIT_ID           *UnitId,
  [out, optional] BOOLEAN                  *Match,
  [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] Identity

Arahkan ke struktur WINBIO_IDENTITY yang berisi GUID atau SID pengguna yang menyediakan sampel biometrik.

[in] SubFactor

Nilai WINBIO_BIOMETRIC_SUBTYPE yang menentukan subfaktor yang terkait dengan sampel biometrik. Windows Biometric Framework (WBF) saat ini hanya mendukung pengambilan sidik jari dan dapat menggunakan konstanta berikut untuk mewakili informasi subtipe.

  • 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
  • WINBIO_SUBTYPE_ANY

[out, optional] UnitId

Penunjuk ke nilai WINBIO_UNIT_ID yang menentukan unit biometrik yang melakukan verifikasi.

[out, optional] Match

Penunjuk ke nilai Boolean yang menentukan apakah sampel yang diambil cocok dengan identitas pengguna yang ditentukan oleh parameter Identitas .

[out, optional] RejectDetail

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

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 tidak valid.
E_INVALIDARG
 Argumen SubFactor salah.
E_POINTER
 Penunjuk yang ditentukan oleh parameter UnitId, Identity, SubFactor, atau RejectDetail tidak boleh NULL.
WINBIO_E_BAD_CAPTURE
 Sampel biometrik tidak dapat ditangkap. Gunakan nilai RejectDetail untuk informasi selengkapnya.
WINBIO_E_ENROLLMENT_IN_PROGRESS
 Operasi tidak dapat diselesaikan karena unit biometrik yang ditentukan saat ini sedang digunakan untuk transaksi pendaftaran (hanya kumpulan sistem).
WINBIO_E_NO_MATCH
 Sampel biometrik tidak sesuai dengan kombinasi Identitas dan SubFactor yang ditentukan.

Keterangan

Jika pengambilan sampel biometrik gagal, parameter UnitId akan berisi nomor unit sensor yang mencoba melakukan penangkapan.

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

Untuk menggunakan WinBioVerify 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 nilai kecocokan BOOLEAN dalam struktur Verifikasi berlapis. Jika operasi tidak berhasil, kerangka kerja mengembalikan informasi WINBIO_REJECT_DETAIL dalam struktur Verifikasi . 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 WinBioVerifyWithCallback . 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_VERIFY_CALLBACK yang diterapkan oleh aplikasi Anda.

Contoh

Fungsi berikut memanggil WinBioVerify untuk menentukan apakah sampel biometrik cocok dengan identitas pengguna saat ini yang masuk. Fungsi pembantu GetCurrentUserIdentity juga disertakan. Tautkan ke pustaka statis Winbio.lib dan sertakan file header berikut:

  • Windows.h
  • Stdio.h
  • Conio.h
  • Winbio.h
HRESULT Verify(WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_IDENTITY identity = {0};
    BOOLEAN match = FALSE;

    // Find the identity of the user.
    hr = GetCurrentUserIdentity( &identity );
    if (FAILED(hr))
    {
        wprintf_s(L"\n User identity not found. hr = 0x%x\n", hr);
        goto e_Exit;
    }

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

    // Verify a biometric sample.
    wprintf_s(L"\n Calling WinBioVerify - Swipe finger on sensor...\n");
    hr = WinBioVerify( 
            sessionHandle, 
            &identity, 
            subFactor, 
            &unitId, 
            &match,
            &rejectDetail
            );
    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_NO_MATCH)
        {
            wprintf_s(L"\n- NO MATCH - identity verification failed.\n");
        }
        else if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n- Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
        wprintf_s(L"\n WinBioVerify failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }
    wprintf_s(L"\n Fingerprint verified:\n", unitId);


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

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

    return hr;
}

//------------------------------------------------------------------------
// The following function retrieves the identity of the current user.
// This is a helper function and is not part of the Windows Biometric
// Framework API.
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
    // Declare variables.
    HRESULT hr = S_OK;
    HANDLE tokenHandle = NULL;
    DWORD bytesReturned = 0;
    struct{
        TOKEN_USER tokenUser;
        BYTE buffer[SECURITY_MAX_SID_SIZE];
    } tokenInfoBuffer;

    // Zero the input identity and specify the type.
    ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
    Identity->Type = WINBIO_ID_TYPE_NULL;

    // Open the access token associated with the
    // current process
    if (!OpenProcessToken(
            GetCurrentProcess(),            // Process handle
            TOKEN_READ,                     // Read access only
            &tokenHandle))                  // Access token handle
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot open token handle: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // Zero the tokenInfoBuffer structure.
    ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));

    // Retrieve information about the access token. In this case,
    // retrieve a SID.
    if (!GetTokenInformation(
            tokenHandle,                    // Access token handle
            TokenUser,                      // User for the token
            &tokenInfoBuffer.tokenUser,     // Buffer to fill
            sizeof(tokenInfoBuffer),        // Size of the buffer
            &bytesReturned))                // Size needed
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot query token information: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // Copy the SID from the tokenInfoBuffer structure to the
    // WINBIO_IDENTITY structure. 
    CopySid(
        SECURITY_MAX_SID_SIZE,
        Identity->Value.AccountSid.Data,
        tokenInfoBuffer.tokenUser.User.Sid
        );

    // Specify the size of the SID and assign WINBIO_ID_TYPE_SID
    // to the type member of the WINBIO_IDENTITY structure.
    Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
    Identity->Type = WINBIO_ID_TYPE_SID;

e_Exit:

    if (tokenHandle != NULL)
    {
        CloseHandle(tokenHandle);
    }

    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

WinBioVerifyWithCallback