PIBIO_STORAGE_QUERY_BY_SUBJECT_FN回呼函式 (winbio_adapter.h)

發行項
03/03/2024

由 Windows 生物特徵辨識架構或引擎配接器呼叫，以找出符合指定身分識別和子因素的範本。

語法

PIBIO_STORAGE_QUERY_BY_SUBJECT_FN PibioStorageQueryBySubjectFn;

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

參數

[in, out] Pipeline

與執行作業之生物特徵辨識單位相關聯的 WINBIO_PIPELINE 結構的指標。

[in] Identity

包含要尋找之 GUID 或 SID 之WINBIO_IDENTITY 結構的指標。如果這個結構的 Type 字段包含 WINBIO_IDENTITY_TYPE_WILDCARD，查詢會傳回符合 SubFactor 參數的每個範本。

[in] SubFactor

WINBIO_BIOMETRIC_SUBTYPE值，指定要尋找的子因素。如果此值 WINBIO_SUBTYPE_ANY，查詢會傳回符合 Identity 參數的每個範本。

傳回值

如果函式成功，它會傳回S_OK。如果函式失敗，它必須傳回下列其中一個 HRESULT 值，以指出錯誤。

傳回碼	Description
E_INVALIDARG	SubFactor 參數指定的自變數無效，或 Identity 參數所指定的結構成員無效。
E_POINTER	強制指標自變數為 NULL。
WINBIO_E_DATABASE_NO_RESULTS	查詢成功，但找不到相符的記錄。
WINBIO_E_DATABASE_LOCKED	資料庫已鎖定。
WINBIO_E_DATABASE_READ_ERROR	發生未指定的問題。
WINBIO_E_INVALID_DEVICE_STATE	管線物件的 StorageContext 成員為 NULL 或 FileHandle 成員無效。

備註

如果這個方法成功傳回，即使查詢傳回空集，管線中的結果集也會由查詢的結果取代。

此函式的呼叫端應該能夠藉由下列方式擷取所有記錄：

在 Identity 參數中傳遞WINBIO_IDENTITY結構，並將 [類型] 字段設定為 WINBIO_IDENTITY_TYPE_WILDCARD。
在 SubFactor 參數中傳遞WINBIO_SUBTYPE_ANY。

成功呼叫此函式之後，結果集數據指標應該位於集合中的第一筆記錄上。

重要

請勿嘗試驗證 為 SubFactor 參數提供的值。 Windows 生物特徵辨識服務會先驗證所提供的值，再將它傳遞至您的實作。如果此值 WINBIO_SUBTYPE_NO_INFORMATION 或 WINBIO_SUBTYPE_ANY，請視需要驗證。

範例

下列虛擬程式代碼顯示此函式的一個可能實作。此範例不會編譯。您必須調整它以符合您的用途。

/////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}

規格需求

需求	值
最低支援的用戶端	Windows 7 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 R2 [僅限傳統型應用程式]
目標平台	Windows
標頭	winbio_adapter.h (包含 Winbio_adapter.h)