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 值之一来指示错误。

返回代码	说明
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，则根据需要进行验证。

示例

以下伪代码显示了此函数的一种可能实现。该示例不编译。必须根据自己的目的调整它。

/////////////////////////////////////////////////////////////////////////////////////////
//
// 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)