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 值，以指出錯誤。

備註

Windows 生物特徵辨識架構只會使用 SHA1 哈希演算法。 因此，這個 OID 必須包含在緩衝區中。 其他 OID 字串是選擇性的，而且未來 Windows 版本可以包含。 在 Wincrypt.h 中，隨附於 Windows SDK，SHA1 演算法的符號會szOID_OIWSEC_sha1，且相關聯的字串值為 “1.3.14.3.2.26”。 這個字串值必須位於緩衝區中。 如需其他 OID 值，請參閱 Wincrypt.h。

下列範例示範如何建立 OID 緩衝區。 SHA1 演演算法 (「1.3.14.3.2.26」) 先包含，不過包含的順序並不重要。 另一個演算法，也會包含值為 “1.3.14.3.2.15” szOID_OIWSEC_shaRSA。 請注意，單一 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;
}

規格需求

另請參閱

EngineAdapterSetHashAlgorithm

外掛程式函式