fungsi panggilan balik PIBIO_STORAGE_QUERY_BY_SUBJECT_FN (winbio_adapter.h)

Artikel
03/03/2024

Dipanggil oleh Windows Biometric Framework atau oleh adaptor mesin untuk menemukan templat yang cocok dengan identitas dan subfaktor tertentu.

Sintaks

PIBIO_STORAGE_QUERY_BY_SUBJECT_FN PibioStorageQueryBySubjectFn;

HRESULT PibioStorageQueryBySubjectFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_IDENTITY Identity,
  [in]      WINBIO_BIOMETRIC_SUBTYPE SubFactor
)
{...}

Parameter

[in, out] Pipeline

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

[in] Identity

Penunjuk ke struktur WINBIO_IDENTITY yang berisi GUID atau SID yang akan ditemukan. Jika bidang Jenis struktur ini berisi WINBIO_IDENTITY_TYPE_WILDCARD, kueri mengembalikan setiap templat yang cocok dengan parameter SubFactor .

[in] SubFactor

Nilai WINBIO_BIOMETRIC_SUBTYPE yang menentukan subfaktor yang akan ditemukan. Jika nilai ini WINBIO_SUBTYPE_ANY, kueri mengembalikan setiap templat yang cocok dengan parameter Identitas .

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_INVALIDARG	Argumen yang ditentukan oleh parameter SubFactor tidak valid atau anggota struktur yang ditentukan oleh parameter Identitas tidak valid.
E_POINTER	Argumen pointer wajib adalah NULL.
WINBIO_E_DATABASE_NO_RESULTS	Kueri berhasil, tetapi tidak ada rekaman yang cocok yang dapat ditemukan.
WINBIO_E_DATABASE_LOCKED	Database dikunci.
WINBIO_E_DATABASE_READ_ERROR	Terjadi masalah yang tidak ditentukan.
WINBIO_E_INVALID_DEVICE_STATE	Anggota StorageContext dari objek alur adalah NULL atau anggota FileHandle tidak valid.

Keterangan

Jika metode ini berhasil dikembalikan, tataan hasil dalam alur digantikan oleh hasil kueri meskipun kueri mengembalikan set kosong.

Penelepon fungsi ini harus dapat mengambil semua rekaman dengan:

Meneruskan struktur WINBIO_IDENTITY dalam parameter Identitas dengan bidang Jenis diatur ke WINBIO_IDENTITY_TYPE_WILDCARD.
Meneruskan WINBIO_SUBTYPE_ANY dalam parameter SubFactor .

Setelah panggilan berhasil ke fungsi ini, kursor tataan hasil harus diposisikan pada rekaman pertama dalam set.

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, validasi jika sesuai.

Contoh

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

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterQueryBySubject
//
// Purpose:
//      Locates templates that match a specified identity and sub-factor.
//
// Parameters:
//      Pipeline  -  Pointer to a WINBIO_PIPELINE structure associated with 
//                   the biometric unit performing the operation.
//      Identity  -  Pointer to a WINBIO_IDENTITY structure that contains the GUID 
//                   or SID to be located.
//      SubFactor -  A WINBIO_BIOMETRIC_SUBTYPE value that specifies the sub-factor 
//                   to be located.
//
static HRESULT
WINAPI
StorageAdapterQueryBySubject(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor
    )
{
    HRESULT hr = S_OK;
    SIZE_T recordCount = 0;

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

    // Retrieve the context from the pipeline.
    PWINBIO_STORAGE_CONTEXT storageContext = (PWINBIO_STORAGE_CONTEXT)Pipeline->StorageContext;

    // Verify the pipeline state.
    if (storageContext == NULL || storageContext->FileHandle == INVALID_HANDLE_VALUE)
    {
        hr =  WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Verify the Identity argument.
    if (Identity->Type != WINBIO_ID_TYPE_GUID &&
        Identity->Type != WINBIO_ID_TYPE_SID &&
        Identity->Type != WINBIO_ID_TYPE_WILDCARD)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    if (Identity->Type == WINBIO_ID_TYPE_WILDCARD &&
        Identity->Value.Wildcard != WINBIO_IDENTITY_WILDCARD)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // WINBIO_SUBTYPE_ANY is a valid sub-factor.
    // WINBIO_SUBTYPE_NO_INFORMATION is not a valid sub-factor.
    if (SubFactor == WINBIO_SUBTYPE_NO_INFORMATION)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Call a custom function (_FindAllMatchingRecords) that compares the 
    // identity and sub-factor values from the caller to the identity and
    // sub-factor values of every record in the database and adds the matching
    // database records to the result set in the pipeline.
    hr = _FindAllMatchingRecords( 
            Pipeline,
            Identity,
            SubFactor,
            &recordCount
            );
    if (FAILED(hr))
    {
        goto cleanup;
    }
    if (recordCount == 0)
    {
        hr = WINBIO_E_DATABASE_NO_RESULTS;
        goto cleanup;
    }

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)