fungsi panggilan balik PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN (winbio_adapter.h)

Artikel
03/03/2024

Dipanggil oleh fungsi SensorAdapterPushDataToEngine yang diimplementasikan oleh adaptor sensor untuk memberi tahu adaptor mesin untuk menerima sampel biometrik mentah dan mengekstrak set fitur. Set fitur dapat digunakan untuk pencocokan atau pendaftaran.

Sintaks

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN PibioEngineAcceptSampleDataFn;

HRESULT PibioEngineAcceptSampleDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_BIR SampleBuffer,
  [in]      SIZE_T SampleSize,
  [in]      WINBIO_BIR_PURPOSE Purpose,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

Parameter

[in, out] Pipeline

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

[in] SampleBuffer

Arahkan ke struktur WINBIO_BIR yang berisi sampel biometrik yang akan diproses.

[in] SampleSize

Nilai SIZE_T yang berisi ukuran struktur WINBIO_BIR yang dikembalikan dalam parameter SampleBuffer .

[in] Purpose

Bitmask WINBIO_BIR_PURPOSE yang menentukan penggunaan sampel yang dimaksudkan. Struktur WINBIO_BIR_PURPOSE menentukan tujuan data tangkapan mana yang akan digunakan, dan (akibatnya) bagaimana data tersebut harus dioptimalkan. Ini bisa menjadi bitwise ATAU dari nilai berikut:

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[out] RejectDetail

Pointer ke nilai WINBIO_REJECT_DETAIL yang menerima informasi tambahan tentang kegagalan untuk memproses sampel biometrik. Jika operasi berhasil, parameter ini diatur ke nol. Nilai berikut didefinisikan untuk sampel 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 harus mengembalikan salah satu nilai HRESULT berikut untuk menunjukkan kesalahan.

Menampilkan kode	Deskripsi
E_INVALIDARG	Argumen SampleSize tidak boleh nol. Argumen Tujuan harus berupa bitwise OR dari nilai yang tercantum dalam deskripsi parameter.
E_POINTER	Argumen Pipeline, SampleBuffer, dan RejectDetail tidak boleh NULL.
E_OUTOFMEMORY	Operasi tidak dapat diselesaikan karena memori tidak mencukuum.
WINBIO_E_BAD_CAPTURE	Data tidak dapat diproses untuk membuat kumpulan fitur yang diperlukan. RejectDetail berisi informasi tambahan tentang kegagalan tersebut.

Keterangan

Set fitur yang dibuat dengan memanggil fungsi ini dipertahankan dalam alur unit biometrik setelah fungsi kembali. Ini menggantikan set fitur sebelumnya.

Implementasi adaptor sensor dari fungsi SensorAdapterPushDataToEngine harus menggunakan fungsi pembungkus berikut (ditentukan dalam Winbio_adapter.h) untuk memanggil EngineAdapterAcceptSampleData:

HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);

Struktur WINBIO_BIR yang diteruskan dalam parameter SampleBuffer adalah properti adaptor sensor. Karena adaptor sensor mengontrol masa pakai objek WINBIO_BIR , fungsi EngineAdapterAcceptSampleData tidak boleh mencoba untuk membatalkan alokasi struktur atau menyimpan penunjuk ke dalamnya. Dengan tidak menyimpan pointer, Anda mencegah bagian lain dari adaptor mesin mencoba menggunakan struktur WINBIO_BIR setelah fungsi EngineAdapterAcceptSampleData kembali.

Jika bidang Offset anggota StandardDataBlock dari struktur WINBIO_BIR lebih besar dari nol (menunjukkan bahwa BIR berisi sampel biometrik dalam format data standar), bidang BiometricDataFormat anggota HeaderBlock harus diatur sebagai berikut:

Bidang Pemilik harus WINBIO_ ANSI_381_FORMAT_OWNER.
Bidang Jenis harus WINBIO_ANSI_381_FORMAT_TYPE.

Ini adalah satu-satunya format data standar yang didukung oleh Windows Biometric Framework.

Windows Biometric Framework juga mengasumsikan bahwa anggota HeaderBlock (struktur WINBIO_BIR_HEADER ) berisi nilai DataFlags dan Purpose yang digunakan oleh adaptor sensor untuk mengambil sampel.

Sensor sidik jari yang memproses sampel sidik jari dan menolak gesekan buruk di Adaptor Mesin juga harus menggunakan nilai yang valid untuk WINBIO_BIR_PURPOSE.

Contoh

Pseudocode berikut menunjukkan satu kemungkinan implementasi fungsi ini. Contoh tidak dikompilasi. Anda harus menyesuaikannya agar sesuai dengan tujuan Anda.

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAcceptSampleData
//
// Purpose:
//      Notifies the engine adapter to accept a raw biometric sample and 
//      extract a feature set.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation. 
//      SampleBuffer    - Contains the biometric sample to be processed.
//      SampleSize      - Size of the structure returned in the SampleBuffer 
//                        parameter.
//      Purpose         - Specifies the intended use of the sample.
//      RejectDetail    - Receives additional information about the failure, 
//                        if any, to process a biometric sample.
//
static HRESULT
WINAPI
EngineAdapterAcceptSampleData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_BIR SampleBuffer,
    __in SIZE_T SampleSize,
    __in WINBIO_BIR_PURPOSE Purpose,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    PUCHAR featureSet = NULL;

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

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

    // Verify that input arguments are valid.
    if (SampleSize == 0 ||
        Purpose == WINBIO_NO_PURPOSE_AVAILABLE)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Release any feature set currently attached to the pipeline before
    // creating a new feature set.
    if (context->FeatureSet != NULL)
    {
        _AdapterRelease(context->FeatureSet);
        context->FeatureSet = NULL;
        context->FeatureSetSize = 0;
    }

    // An actual engine adapter would here process the contents of the sample 
    // buffer, generate a feature set suitable for the purpose(s) specified 
    // by the Purpose parameter, and attach the feature set to the pipeline. 
    // The following trivial example, however, creates a feature set simply
    // by making an exact copy of the raw sample.
    // If the sample data cannot be processed, return an HRESULT error code
    // of WINBIO_E_BAD_CAPTURE and set extended error information in the 
    // RejectDetail parameter.
    featureSet = (PUCHAR)_AdapterAlloc(SampleSize);
    if (featureSet == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }
    RtlCopyMemory(featureSet, SampleBuffer, SampleSize);
    context->FeatureSet = featureSet;
    featureSet = NULL;
    context->FeatureSetSize = SampleSize;

cleanup:

    if (FAILED(hr))
    {
        if (featureSet != NULL)
        {
            _AdapterRelease(featureSet);
        }
    }

    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

EngineAdapterExportEngineData

Fungsi Plug-in

Bagikan melalui