PIBIO_STORAGE_QUERY_BY_SUBJECT_FN コールバック関数 (winbio_adapter.h)

[アーティクル]
08/27/2023

Windows 生体認証フレームワークまたはエンジンアダプターによって呼び出され、指定された ID とサブ要素に一致するテンプレートを検索します。

構文

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 値を返してエラーを示す必要があります。

リターンコード	説明
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構造体を渡し、Type フィールドを WINBIO_IDENTITY_TYPE_WILDCARD に設定します。
SubFactor パラメーターでWINBIO_SUBTYPE_ANYを渡す。

この関数の呼び出しが成功すると、結果セットカーソルはセット内の最初のレコードに配置されます。

重要

SubFactor パラメーターに指定された値を検証しないでください。 Windows 生体認証サービスは、指定された値を検証してから実装に渡します。値が WINBIO_SUBTYPE_NO_INFORMATION または WINBIO_SUBTYPE_ANY場合は、必要に応じて検証します。

例

次の擬似コードは、この関数の 1 つの可能な実装を示しています。この例はコンパイルされません。目的に合わせて調整する必要があります。

/////////////////////////////////////////////////////////////////////////////////////////
//
// 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 を含む)