PIBIO_ENGINE_COMMIT_ENROLLMENT_FN fungsi panggilan balik (winbio_adapter.h)

Artikel
03/08/2023

Dipanggil oleh Windows Biometric Framework untuk menyelesaikan objek pendaftaran, mengonversinya menjadi templat, dan menyimpan templat dalam database.

Sintaks

PIBIO_ENGINE_COMMIT_ENROLLMENT_FN PibioEngineCommitEnrollmentFn;

HRESULT PibioEngineCommitEnrollmentFn(
  [in, out]      PWINBIO_PIPELINE Pipeline,
  [in]           PWINBIO_IDENTITY Identity,
  [in]           WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [in, optional] PUCHAR PayloadBlob,
  [in]           SIZE_T PayloadBlobSize
)
{...}

Parameter

[in, out] Pipeline

Penunjuk ke struktur WINBIO_PIPELINE yang terkait dengan unit biometrik yang melakukan operasi.

[in] Identity

Penunjuk ke struktur WINBIO_IDENTITY yang berisi GUID atau SID templat yang akan disimpan dalam database.

[in] SubFactor

Nilai WINBIO_BIOMETRIC_SUBTYPE yang menentukan subfaktor yang terkait dengan templat yang akan disimpan dalam database.

[in, optional] PayloadBlob

Penunjuk opsional ke array byte yang berisi tanda tangan verifikasi yang dihasilkan oleh Windows Biometric Framework.

[in] PayloadBlobSize

Ukuran, dalam byte, dari array karakter yang ditujukkan oleh parameter PayloadBlob . Nilai ini harus nol jika parameter PayloadBlob adalah NULL.

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika fungsi gagal, fungsi harus mengembalikan salah satu nilai HRESULT berikut atau nilai apa pun yang dikembalikan oleh adaptor penyimpanan.

Menampilkan kode	Deskripsi
E_POINTER	Argumen pointer wajib adalah NULL.
E_INVALIDARG	Nilai yang ditentukan oleh parameter Identitas atau parameter SubFactor tidak valid.
WINBIO_E_DUPLICATE_ENROLLMENT	Templat yang ditentukan oleh parameter Identitas dan SubFactor sudah disimpan dalam database.
WINBIO_E_INVALID_DEVICE_STATE	Tidak ada templat yang dilampirkan ke alur.

Keterangan

Jika fungsi ini berhasil, itu harus menghapus templat pendaftaran dari alur. Hasil dari tindakan ini harus setara dengan memanggil EngineAdapterClearContext.

Jika fungsi ini gagal, fungsi ini tidak boleh mengubah status konteks mesin. Secara khusus, jika ada templat lengkap yang dilampirkan ke alur, mungkin untuk memanggil fungsi ini lagi (setelah alasan kegagalan apa pun telah ditangani) untuk menerapkan templat ke database.

Adaptor mesin yang mendukung autentikasi pra-boot harus menerapkan pendaftaran tidak hanya ke adaptor penyimpanan yang terpasang pada alur, tetapi juga ke area penyimpanan pra-boot. Detail tentang bagaimana hal ini harus dicapai diserahkan kepada vendor.

Penting

Jangan mencoba memvalidasi nilai yang disediakan untuk parameter SubFactor . Layanan Biometrik Windows akan memvalidasi nilai yang disediakan sebelum meneruskannya ke implementasi Anda. Jika nilainya WINBIO_SUBTYPE_NO_INFORMATION atau WINBIO_SUBTYPE_ANY, maka validasi jika sesuai.

Contoh

Pseudocode berikut menunjukkan salah satu kemungkinan implementasi fungsi ini. Contoh tidak dikompilasi. Kau harus menyesuaikannya sesuai dengan tujuanmu.

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterCommitEnrollment
//
// Purpose:
//      Finalizes the enrollment object, converts it to a template, and saves 
//      the template in the database.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Identity        - GUID or SID of the template to be stored in the 
//                        database
//      SubFactor       - Sub-factor associated with the template to be stored
//                        in the database
//      PayloadBlob     - Optional pointer to an array of bytes that contain a 
//                        verification signature generated by the Windows Biometric
//                        Framework
//      PayloadBlobSize - Size, in bytes, of the character array pointed to by 
//                        the PayloadBlob parameter
//

static HRESULT
WINAPI
EngineAdapterCommitEnrollment(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in PUCHAR PayloadBlob,
    __in SIZE_T PayloadBlobSize
    )
{
    HRESULT hr = S_OK;
    DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_STORAGE_RECORD newTemplate = {0};

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(Identity))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    if (ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }
    
    if (!ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize > 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // TODO: Verify that the SubFactor and Identity arguments are valid.

    // Retrieve the context from the pipeline.
    PWINIBIO_ENGINE_CONTEXT context = 
        (PWINIBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

    // Return if an enrollment is not in progress. This example assumes that 
    // an enrollment object is part of your engine context structure.
    if (context->Enrollment.InProgress != TRUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // If your adapter supports index vectors to place templates into buckets,
    // call a custom function (_AdapterCreateIndexVector) to create an index 
    // vector from the template data in the enrollment object.
    hr = _AdapterCreateIndexVector(
                context, 
                context->Enrollment.Template, 
                context->Enrollment.TemplateSize,
                indexVector, 
                NUMBER_OF_TEMPLATE_BINS, 
                &rejectDetail
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    newTemplate.Identity = Identity;
    newTemplate.SubFactor = SubFactor;
    newTemplate.IndexVector = indexVector;
    newTemplate.IndexElementCount = NUMBER_OF_TEMPLATE_BINS;
    newTemplate.TemplateBlob = context->Enrollment.Template;
    newTemplate.TemplateBlobSize = context->Enrollment.TemplateSize;
    newTemplate.PayloadBlob = PayloadBlob;
    newTemplate.PayloadBlobSize = PayloadBlobSize;

    hr = WbioStorageAddRecord(
                Pipeline,
                &newTemplate
                );

    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Call a custom function (_AdapterDestroyEnrollmentTemplate) to release
    // any resources held by the enrollment object.
    _AdapterDestroyEnrollmentTemplate(
        context,
        &context->Enrollment
        );

    // Specify that the enrollment process has been completed.
    context->Enrollment.InProgress = FALSE;

cleanup:

    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_adapter.h (termasuk Winbio_adapter.h)

Lihat juga

EngineAdapterClearContext

Fungsi Plug-in

Bagikan melalui