PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN

エンジンアダプターがサポートするハッシュアルゴリズムを表すオブジェクト識別子 (OID) の配列を取得するために、Windows Biometric Framework から呼び出されます。

関数が成功すると、S_OK を返します。関数が失敗した場合は、エラーを示す次のいずれかの HRESULT 値を返す必要があります。

Windows Biometric Framework が使用するハッシュアルゴリズムは 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.2.26") を最初に含めていますが、含める順序は重要ではありません。値が "1.3.14.3.2.15" である別のアルゴリズム szOID_OIWSEC_shaRSA も含めています。各 OID 文字列の終わりは 1 つの NULL 値で示され、最後の文字列の末尾にもう 1 つ NULL 値を追加することでバッファーの終わりを示す点に注意してください。

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

この関数が成功する場合は、このバッファーの先頭アドレスを AlgorithmBuffer 引数で返します。バッファーはエンジンアダプターが所有します。Windows Biometric Framework がこのバッファーを読み取るため、エンジンアダプターがバイオメトリックユニットにアタッチされている間、このアドレスは有効なままである必要があります。

通常、OID 文字列のテーブルは静的データブロックとしてエンジンアダプターにコンパイルします。

例

次の擬似コードは、この関数の実装例の 1 つを示しています。この例はそのままではコンパイルできません。目的に合わせて適宜変更してください。

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