Share via

PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN回调函数 (winbio_adapter.h)

  • 项目

由 Windows 生物识别框架调用，用于检索表示引擎适配器支持的哈希算法 (OID) 的对象标识符数组。

语法

PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN PibioEngineQueryHashAlgorithmsFn;

HRESULT PibioEngineQueryHashAlgorithmsFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [out]     PSIZE_T AlgorithmCount,
  [out]     PSIZE_T AlgorithmBufferSize,
  [out]     PUCHAR *AlgorithmBuffer
)
{...}

参数

[in, out] Pipeline

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

[out] AlgorithmCount

指向一个值的指针，该值接收 AlgorithmBuffer 参数指定的缓冲区中的算法 OID 字符串数。

[out] AlgorithmBufferSize

指向一个值的指针，该值包含 AlgorithmBuffer 参数指定的缓冲区的大小（以字节为单位）。 大小包括终止缓冲区的两个 NULL 值。

[out] AlgorithmBuffer

变量的地址，该变量接收指向包含已打包的 、以 NULL 结尾的 ANSI 字符串的缓冲区的指针。 每个字符串表示哈希算法的 OID。 缓冲区中的最后一个字符串必须由两个连续 的 NULL 值终止。

返回值

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

返回代码 说明
E_POINTER
 强制指针参数为 NULL。
E_NOTIMPL
 引擎适配器不支持模板哈希生成。

注解

Windows 生物识别框架仅使用 SHA1 哈希算法。 因此，此 OID 必须包含在缓冲区中。 其他 OID 字符串是可选的，可以包含在将来的 Windows 版本中。 在Windows SDK随附的 Wincrypt.h 中，SHA1 算法的符号szOID_OIWSEC_sha1，关联的字符串值为“1.3.14.3.2.26”。 此字符串值必须位于缓冲区中。 有关其他 OID 值，请参阅 Wincrypt.h。

以下示例演示如何创建 OID 缓冲区。 SHA1 算法 (“1.3.14.3.26”) 首先包括在内，尽管包含顺序并不重要。 还包括另一种算法，szOID_OIWSEC_shaRSA值为“1.3.14.3.2.15”。 请注意，单个 NULL 值标识每个 OID 字符串的结尾，最后一个字符串末尾之后的附加 NULL 值标识缓冲区的末尾。

char OidBuffer[] = 
{
    '1','.','3','.','1','4','.','3','.','2','.','2','6','\0',
    '1','.','3','.','1','4','.','3','.','2','.','1','5','\0','\0'
};

如果此函数成功，请在 AlgorithmBuffer 参数中返回此缓冲区的起始地址。 引擎适配器拥有缓冲区。 由于 Windows 生物识别框架读取缓冲区，因此只要引擎适配器连接到生物识别单元，地址必须保持有效。

通常，将 OID 字符串表作为静态数据块编译到引擎适配器中。

示例

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterQueryHashAlgorithms
// 
//      Retrieves an array of object identifiers (OIDs) that represent the 
//      hash algorithms supported by the engine adapter.
//
// Parameters:
//      Pipeline            - Pointer to a WINBIO_PIPELINE structure associated 
//                            with the biometric unit performing the operation.
//      AlgorithmCount      - Pointer to a value that receives the number of 
//                            algorithm OID strings specified by the 
//                            AlgorithmBuffer parameter.
//      AlgorithmBufferSize - Pointer to a value that contains the size, 
//                            in bytes, of the buffer specified by the 
//                            AlgorithmBuffer parameter.
//      AlgorithmBuffer     - Address of a variable that receives a pointer to 
//                            a buffer that contains packed, NULL-terminated ANSI 
//                            strings. Each string represents an OID for a hash 
//                            algorithm. The final string in the buffer must be 
//                            terminated by two successive NULL values.
//
// Note:
//      The following algorithm table contains the SHA1 OID. Only 
//      the SHA1 hash algorithm is supported by the Windows Biometric Framework.
//      The algorithm table must be defined in global scope for the engine adapter.
//

static char g_HashAlgorithmOidTable[] = 
{
    '1','.','3','.','1','4','.','3','.','2','.','2','6','\0','\0'
};

static HRESULT
WINAPI
EngineAdapterQueryHashAlgorithms(
    __inout PWINBIO_PIPELINE Pipeline,
    __out PSIZE_T AlgorithmCount,
    __out PSIZE_T AlgorithmBufferSize,
    __out PUCHAR *AlgorithmBuffer
    )
{
    ////////////////////////////////////////////////////////////////////////////
    // Return E_NOTIMPL here if your adapter does not support template hashing.
    ////////////////////////////////////////////////////////////////////////////

    HRESULT hr = S_OK;

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

    // Pass the address and size of the static algorithm table and the number
    // of algorithms to the caller. If your adapter does not support template
    // hashing, return E_NOTIMPL.
    *AlgorithmCount = 1;
    *AlgorithmBufferSize = sizeof(g_HashAlgorithmOidTable);
    *AlgorithmBuffer = g_HashAlgorithmOidTable;

cleanup:

    return hr;
}

要求

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

另请参阅

EngineAdapterSetHashAlgorithm

插件函数