fungsi panggilan balik PIBIO_SENSOR_ATTACH_FN (winbio_adapter.h)

Artikel
03/13/2024

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

Sintaks

PIBIO_SENSOR_ATTACH_FN PibioSensorAttachFn;

HRESULT PibioSensorAttachFn(
  [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 SensorContext dari struktur WINBIO_PIPELINE yang diacu oleh argumen Alur bukan NULL.

Keterangan

Fungsi ini dipanggil sebelum adaptor mesin dan penyimpanan telah diinisialisasi untuk unit biometrik. Oleh karena itu, fungsi ini tidak boleh memanggil fungsi apa pun yang direferensikan oleh WINBIO_ENGINE_INTERFACE atau struktur WINBIO_STORAGE_INTERFACE yang ditujukkan oleh anggota EngineInterface dan StorageInterface dari objek alur.

Karena anggota SensorHandle dari struktur WINBIO_PIPELINE akan berisi handel yang valid sebelum metode ini dipanggil, implementasi SensorAdapterAttach Anda dapat menggunakan handel untuk mengakses perangkat sensor jika perlu.

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_SENSOR_CONTEXT privat pada tumpukan, inisialisasi, dan atur alamatnya di anggota SensorContext 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 SensorContext bukan NULL ketika fungsi ini dipanggil, alur tidak diatur ulang dengan benar oleh panggilan sebelumnya ke SensorAdapterDetach dan Anda harus mengembalikan WINBIO_E_INVALID_DEVICE_STATE untuk memberi tahu Windows Biometric Framework tentang masalah tersebut.

Contoh

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterAttach
//
// 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
SensorAdapterAttach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;
    PWINBIO_SENSOR_CONTEXT newContext = NULL;

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

    // Validate the current sensor state.
    if (Pipeline->SensorContext != NULL)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Use a custom function (_AdapterAlloc) to allocate memory for the 
    // sensor adapter context.
    newContext = (PWINBIO_SENSOR_CONTEXT)_AdapterAlloc(sizeof(WINBIO_SENSOR_CONTEXT));
    if (newContext == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }

    // Create a manual reset event to monitor overlapped I/O.
    newContext->Overlapped.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
    if (newContext->Overlapped.hEvent == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }

    // Initialize any required context fields. This example assumes that your
    // sensor context points to a capture buffer and an attributes buffer.
    newContext->CaptureBuffer = NULL;
    newContext->CaptureBufferSize = 0;

    newContext->AttributesBuffer = NULL;
    newContext->AttributesBufferSize = sizeof (WINBIO_SENSOR_ATTRIBUTES);

    // Transfer ownership of the new sensor context structure to the 
    // pipeline.
    Pipeline->SensorContext = newContext;
    newContext = NULL;

cleanup:

    if (FAILED(hr) && newContext != NULL)
    {
        CloseHandle( newContext->Overlapped.hEvent;
        _AdapterRelease( newContext );
        newContext = NULL;
    }
    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)