fungsi panggilan balik PIBIO_ENGINE_ATTACH_FN (winbio_adapter.h)

Artikel
08/27/2023

Dipanggil oleh Windows Biometric Framework ketika adaptor mesin ditambahkan ke alur pemrosesan unit biometrik. Tujuan dari fungsi ini adalah untuk melakukan inisialisasi apa pun yang diperlukan untuk operasi biometrik nanti.

Sintaks

PIBIO_ENGINE_ATTACH_FN PibioEngineAttachFn;

HRESULT PibioEngineAttachFn(
  [in, out] PWINBIO_PIPELINE Pipeline
)
{...}

Parameter

[in, out] Pipeline

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

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan S_OK. Jika fungsi gagal, fungsi harus mengembalikan salah satu nilai HRESULT berikut untuk menunjukkan kesalahan.

Menampilkan kode	Deskripsi
E_POINTER	Argumen Alur tidak boleh NULL.
E_OUTOFMEMORY	Operasi tidak dapat diselesaikan karena memori tidak cukup.
WINBIO_E_INVALID_DEVICE_STATE	Anggota EngineContext dari struktur WINBIO_PIPELINE yang diacu oleh argumen Alur bukan NULL atau anggota EngineHandle tidak diatur ke INVALID_HANDLE_VALUE.

Keterangan

Fungsi ini dipanggil sebelum adaptor penyimpanan diinisialisasi untuk unit biometrik. Oleh karena itu, fungsi ini tidak boleh memanggil fungsi apa pun yang direferensikan oleh struktur WINBIO_STORAGE_INTERFACE yang diacu oleh anggota StorageInterface dari objek alur.

Saat menerapkan fungsi ini, Anda harus mengalokasikan dan mengelola sumber daya apa pun yang diperlukan oleh adaptor dan melampirkan ini ke alur unit biometrik. Untuk melakukan ini, alokasikan struktur WINBIO_ENGINE_CONTEXT privat pada tumpukan, inisialisasi, dan atur alamatnya di anggota EngineContext dari objek alur.

Jika ada kesalahan selama pembuatan dan inisialisasi sumber daya adaptor mesin yang digunakan oleh fungsi ini, Anda harus melakukan pembersihan yang diperlukan sebelum mengembalikan.

Jika bidang EngineContext bukan NULL ketika fungsi ini dipanggil, alur tidak diinisialisasi dengan benar dan Anda harus mengembalikan WINBIO_E_INVALID_DEVICE_STATE untuk memberi tahu Windows Biometric Framework tentang masalah tersebut.

Demikian pula, jika bidang EngineHandle tidak berisi INVALID_HANDLE_VALUE ketika fungsi ini dipanggil, Anda harus mengembalikan WINBIO_E_INVALID_DEVICE_STATE.

Contoh

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAttach
//
// Purpose:
//      Performs any initialization required for later biometric operations.
//
// Parameters:
//      Pipeline -  Pointer to a WINBIO_PIPELINE structure associated with 
//                  the biometric unit performing the operation.
//
static HRESULT
WINAPI
EngineAdapterAttach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;

    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_ENGINE_CONTEXT newContext = NULL;

    // Call a custom function (_AdapterAlloc) to allocate memory to hold the 
    // engine adapter context.
    newContext = (PWINBIO_ENGINE_CONTEXT)_AdapterAlloc(sizeof(WINBIO_ENGINE_CONTEXT));
    if (newContext == NULL)
    {
        E_OUTOFMEMORY;
        goto cleanup;
    }

    // Clear the context memory.
    ZeroMemory(newContext, sizeof(WINBIO_ENGINE_CONTEXT));

    // Initialize any required context fields.
    newContext->SomeField = SomeSpecialValue;

    newContext->SomePointerField = _AdapterAlloc(sizeof(SOME_STRUCTURE));
    if (newContext->SomePointerField == NULL)
    {
        E_OUTOFMEMORY;
        goto cleanup;
    }

    // If your adapter supports software-based template hashing, implement the 
    // following custom function to open a SHA1 hash object handle and store 
    // the handle in the adapter context. Use Cryptography Next Generation (CNG) 
    // functions to create the SHA1 hash object.
    hr = _AdapterInitializeCrypto(newContext);
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // If initialization completes successfully, attach the engine context to the 
    // processing pipeline of the biometric unit.
    Pipeline->EngineContext = newContext;
    newContext = NULL;

cleanup:
    if (FAILED(hr))
    {
        // If a new context has been created, release any memory 
        // pointed to by various data members in the context and 
        // then release the context. The following example assumes 
        // that your adapter contains a handle
        // for a hash object and a pointer to another object.
        if (newContext != NULL)
        {
            // Close any open CNG handles and release the hash object memory.
            _AdapterCleanupCrypto(newContext);

            // Release any other object pointed to by the context.
            if (newContext->SomePointerField != NULL)
            {
                _AdapterRelease(newContext->SomePointerField);
            }

            // Release the context
            _AdapterRelease(newContext);
        }
    }
    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_adapter.h (termasuk Winbio_adapter.h)