Fungsi WinBioEnrollCommit (winbio.h)

  • Artikel

Menyelesaikan templat biometrik yang tertunda dan menyimpannya ke database yang terkait dengan unit biometrik yang digunakan untuk pendaftaran. Dimulai dengan Windows 10, build 1607, fungsi ini tersedia untuk digunakan dengan gambar seluler.

Sintaks

HRESULT WinBioEnrollCommit(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [out, optional] WINBIO_IDENTITY       *Identity,
  [out, optional] BOOLEAN               *IsNewTemplate
);

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

Penunjuk ke struktur WINBIO_IDENTITY yang menerima pengidentifikasi (GUID atau SID) templat.

[out, optional] IsNewTemplate

Penunjuk ke nilai Boolean yang menentukan apakah templat yang ditambahkan ke database baru.

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_HANDLE
 Handel sesi tidak valid.
E_POINTER
 Penunjuk yang ditentukan oleh parameter Identitas dan IsNewTemplate tidak boleh NULL.
WINBIO_E_DATABASE_FULL
 Tidak ada ruang yang tersedia dalam database untuk templat.
WINBIO_E_DUPLICATE_TEMPLATE
 Templat cocok dengan yang sudah disimpan dalam database dengan identitas atau subfaktor yang berbeda (hanya kumpulan sistem).
WINBIO_E_LOCK_VIOLATION
 Unit biometrik sedang digunakan dan dikunci.

Keterangan

Jika templat yang tertunda adalah duplikat dari templat yang sudah ada dalam database, parameter Identitas akan menunjuk ke templat yang ada dan nilai yang ditunjukkan oleh parameter IsNewTemplate akan FALSE.

Jika fungsi WinBioEnrollCommit berhasil, nilai registri berikut diatur ke 0x01.

HKEY_LOCAL_MACHINE
   System
      CurrentControlSet
         Services
            WbioSrvc
               Parameters
                  EnrollmentCommitted
Catatan Nilai registri ini tidak pernah dihapus oleh Windows Biometric Framework (WBF).
 
Untuk menggunakan WinBioEnrollCommit secara sinkron, panggil fungsi dengan handel sesi yang dibuat dengan memanggil WinBioOpenSession. Fungsi memblokir hingga operasi selesai atau terjadi kesalahan.

Untuk menggunakan WinBioEnrollCommit 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 WINBIO_IDENTITY dan bendera yang menunjukkan apakah templat baru dalam struktur EnrollCommit 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 dari pesan jendela.
Untuk mencegah kebocoran memori, Anda harus memanggil WinBioFree untuk merilis struktur WINBIO_ASYNC_RESULT setelah Anda selesai menggunakannya.

Contoh

Fungsi berikut memanggil WinBioEnrollCommit untuk melakukan pendaftaran biometrik ke kumpulan sistem. Tautkan ke pustaka statis Winbio.lib dan sertakan file header berikut:

  • Windows.h
  • Stdio.h
  • Conio.h
  • Winbio.h
HRESULT EnrollSysPool(
                      BOOL discardEnrollment, 
                      WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    BOOLEAN isNewTemplate = TRUE;

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

    // Locate a sensor.
    wprintf_s(L"\n Swipe your finger on the sensor...\n");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Begin the enrollment sequence. 
    wprintf_s(L"\n Starting enrollment sequence...\n");
    hr = WinBioEnrollBegin(
            sessionHandle,      // Handle to open biometric session
            subFactor,          // Finger to create template for
            unitId              // Biometric unit ID
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnrollBegin failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture enrollment information by swiping the sensor with
    // the finger identified by the subFactor argument in the 
    // WinBioEnrollBegin function.
    for (int swipeCount = 1;; ++swipeCount)
    {
        wprintf_s(L"\n Swipe the sensor to capture %s sample.",
                 (swipeCount == 1)?L"the first":L"another");

        hr = WinBioEnrollCapture(
                sessionHandle,  // Handle to open biometric session
                &rejectDetail   // [out] Failure information
                );

        wprintf_s(L"\n Sample %d captured from unit number %d.", 
                  swipeCount, 
                  unitId);

        if (hr == WINBIO_I_MORE_DATA)
        {
            wprintf_s(L"\n    More data required.\n");
            continue;
        }
        if (FAILED(hr))
        {
            if (hr == WINBIO_E_BAD_CAPTURE)
            {
                wprintf_s(L"\n  Error: Bad capture; reason: %d", 
                          rejectDetail);
                continue;
            }
            else
            {
                wprintf_s(L"\n WinBioEnrollCapture failed. hr = 0x%x", hr);
                goto e_Exit;
            }
        }
        else
        {
            wprintf_s(L"\n    Template completed.\n");
            break;
        }
    }

    // Discard the enrollment if the appropriate flag is set.
    // Commit the enrollment if it is not discarded.
    if (discardEnrollment == TRUE)
    {
        wprintf_s(L"\n Discarding enrollment...\n\n");
        hr = WinBioEnrollDiscard( sessionHandle );
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;    
    }
    else
    {
        wprintf_s(L"\n Committing enrollment...\n");
        hr = WinBioEnrollCommit( 
                sessionHandle,      // Handle to open biometric session
                &identity,          // WINBIO_IDENTITY object for the user
                &isNewTemplate);    // Is this a new template

        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioEnrollCommit failed. hr = 0x%x\n", hr);
            goto e_Exit;
        }
    }


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

    wprintf_s(L" Press any key to continue...");
    _getch();

    return hr;
}

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

WinBioEnrollBegin

WinBioEnrollCapture

WinBioEnrollCaptureWithCallback

WinBioEnrollDiscard