PIBIO_STORAGE_QUERY_BY_CONTENT_FN回调函数 (winbio_adapter.h)

项目
08/27/2023

由引擎适配器调用以查找与指定索引向量匹配的模板。

语法

PIBIO_STORAGE_QUERY_BY_CONTENT_FN PibioStorageQueryByContentFn;

HRESULT PibioStorageQueryByContentFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      WINBIO_BIOMETRIC_SUBTYPE SubFactor,
            ULONG IndexVector[],
  [in]      SIZE_T IndexElementCount
)
{...}

参数

[in, out] Pipeline

指向与执行操作的生物识别单元关联的 WINBIO_PIPELINE 结构的指针。

[in] SubFactor

一个WINBIO_BIOMETRIC_SUBTYPE值，该值指定与模板关联的子因子。

IndexVector[]

[in] IndexElementCount

一个值，该值包含索引向量数组中的元素数。这必须与创建数据库时指定的大小匹配。如果数据库是使用零长度索引创建的，则此参数必须为零。

返回值

如果函数成功，则返回S_OK。如果函数失败，则必须返回以下 HRESULT 值之一来指示错误。

返回代码	说明
E_INVALIDARG	SubFactor 参数指定的参数无效。
E_POINTER	强制指针参数为 NULL。
E_OUTOFMEMORY	无法为记录标头分配内存。
WINBIO_E_DATABASE_BAD_INDEX_VECTOR	索引向量的大小与创建数据库时指定的索引大小不匹配。
WINBIO_E_DATABASE_NO_RESULTS	查询成功，但找不到匹配的记录。
WINBIO_E_DATABASE_LOCKED	数据库已锁定。
WINBIO_E_DATABASE_READ_ERROR	出现未指定的问题。
WINBIO_E_INVALID_DEVICE_STATE	管道对象的 StorageContext 成员为 NULL 或 FileHandle 成员无效。

注解

如果此方法成功返回，即使查询返回空集，管道中的结果集也会替换为查询的结果。

如果数据库是使用零长度索引向量创建的，则结果集将包含模板子因子与 SubFactor 参数匹配的每条记录。在这种情况下，如果调用方为 SubFactor 参数传递WINBIO_SUBTYPE_ANY，此函数将返回数据库中的所有记录。

成功调用此函数后，结果集游标应位于集中的第一条记录上。

重要说明

不要尝试验证为 SubFactor 参数提供的值。 Windows 生物识别服务将验证提供的值，然后再将其传递给实现。如果该值 WINBIO_SUBTYPE_NO_INFORMATION 或 WINBIO_SUBTYPE_ANY，则根据需要进行验证。

示例

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

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterQueryByContent
//
// Purpose:
//      Locates templates that match a specified index vector.
//
// Parameters:
//      Pipeline          - Pointer to a WINBIO_PIPELINE structure associated with 
//                          the biometric unit performing the operation.
//      SubFactor         - A WINBIO_BIOMETRIC_SUBTYPE value that specifies the sub-factor 
//                          associated with the template.
//      IndexVector       - Pointer to an array of ULONG index values.
//      IndexElementCount - A value that contains the number of elements in the index 
//                          vector array.
//
static HRESULT
WINAPI
StorageAdapterQueryByContent(
    __inout PWINBIO_PIPELINE Pipeline,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in ULONG IndexVector[],
    __in SIZE_T IndexElementCount
    )
{
    HRESULT hr = S_OK;
    BOOL lockAcquired = FALSE;
    struct _MY_ADAPTER_FILE_HEADER fileHeader = {0};
    SIZE_T remainingRecords = 0;
    LARGE_INTEGER currentRecordOffset = {0};
    struct _MY_ADAPTER_RECORD_HEADER *recordHeader = NULL;
    SIZE_T recordHeaderSize = 0;

    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(IndexVector))
    {
        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;
    }

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

    // Validate the IndexElementCount argument.
    if (IndexElementCount != storageContext->IndexElementCount)
    {
        hr = WINBIO_E_DATABASE_BAD_INDEX_VECTOR;
        goto cleanup;
    }
    if (storageContext->IndexElementCount > 0 &&
        !ARGUMENT_PRESENT(IndexVector))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Clear the result set.
    hr = StorageAdapterClearContext(Pipeline);
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Lock the database for reading.
    hr = _LockDatabase( Pipeline->StorageHandle, FALSE);
    if (FAILED(hr))
    {
        goto cleanup;
    }
    lockAcquired = TRUE;

    // Read the header block.
    hr = _ReadFileHeader( Pipeline->StorageHandle, &fileHeader );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Scan through all records looking for index vector matches.
    recordHeaderSize = 
        sizeof(struct _MY_ADAPTER_RECORD_HEADER) +
        (SIZE_T)fileHeader.IndexElementCount * sizeof(ULONG);

    currentRecordOffset = _MY_ADAPTER_FIRST_RECORD_OFFSET;
    remainingRecords = fileHeader.TotalRecordCount;

    while (remainingRecords > 0)
    {
        SIZE_T recordSize = 0;
        BOOLEAN match = FALSE;
        LARGE_INTEGER dataOffset = {0};

        // If you did not give up the current header during the previous 
        // iteration of the loop, reuse it.
        if (recordHeader == NULL)
        {
            recordHeader = (struct _MY_ADAPTER_RECORD_HEADER*)_AdapterAlloc( recordHeaderSize );
            if (recordHeader == NULL)
            {
                hr = E_OUTOFMEMORY;
                goto cleanup;
            }
        }
        else
        {
            ZeroMemory(recordHeader, recordHeaderSize);
        }

        hr = _ReadRecordHeader(
                Pipeline->StorageHandle,
                currentRecordOffset,
                recordHeader,
                recordHeaderSize
                );
        if (FAILED(hr))
        {
            goto cleanup;
        }

        recordSize = recordHeader->RecordSize;

        // Skip records marked for deletion.
        if ((recordHeader->Flags & _MY_ADAPTER_FLAG_RECORD_DELETED) == 0)
        {
            // Call a custom function (_MatchIndexVector) that compares the index
            // vector of the current record with the input index vector.
            hr = _MatchIndexVector(
                    SubFactor,
                    IndexVector,
                    IndexElementCount,
                    recordHeader->SubFactor,
                    _GetIndexVector(recordHeader),
                    storageContext->IndexElementCount,
                    &match
                    );
            if (FAILED(hr))
            {
                goto cleanup;
            }

            if (match == TRUE)
            {
                // Calculate the file offset of this record's data area.
                dataOffset.QuadPart = 
                    currentRecordOffset.QuadPart + 
                    recordHeader->RecordHeaderSize;

                // Add the matching record to the result set in the pipeline.
                hr = _ResultSetAddElement( 
                        &storageContext->ResultSet, 
                        recordHeader, 
                        dataOffset
                        );
                if (FAILED(hr))
                {
                    goto cleanup;
                }
                // The result set now owns the record header. Set the pointer
                // to NULL.
                recordHeader = NULL;
            }
        }

        currentRecordOffset.QuadPart += recordSize;
        --remainingRecords;
    }

    // If the search was successful, but the result set is empty, return 
    // WINBIO_E_DATABASE_NO_RESULTS
    if (SUCCEEDED(hr))
    {
        SIZE_T elementCount = 0;
        hr = _ResultSetGetCount(&storageContext->ResultSet, &elementCount);
    }

cleanup:

    if (recordHeader != NULL)
    {
        _AdapterRelease(recordHeader);
        recordHeader = NULL;
    }

    if (lockAcquired == TRUE)
    {
        _UnlockDatabase( Pipeline->StorageHandle);
        lockAcquired = FALSE;
    }

    if (FAILED(hr))
    {
        // Clear any partial result set from the pipeline.
        StorageAdapterClearContext(Pipeline);
    }

    return hr;
}

要求


最低受支持的客户端	Windows 7 [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 R2 [仅限桌面应用]
目标平台	Windows
标头	winbio_adapter.h (包括 Winbio_adapter.h)