PIBIO_ENGINE_QUERY_HASH_ALGORITHMS_FN funzione di callback (winbio_adapter.h)

Chiamato da Windows Biometric Framework per recuperare una matrice di identificatori di oggetti (OID) che rappresentano gli algoritmi hash supportati dall'adattatore del motore.

Sintassi

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
)
{...}

Parametri

[in, out] Pipeline

Puntatore a una struttura WINBIO_PIPELINE associata all'unità biometrica che esegue l'operazione.

[out] AlgorithmCount

Puntatore a un valore che riceve il numero di stringhe OID dell'algoritmo nel buffer specificato dal parametro AlgorithmBuffer .

[out] AlgorithmBufferSize

Puntatore a un valore contenente le dimensioni, in byte, del buffer specificato dal parametro AlgorithmBuffer . Le dimensioni includono i due valori NULL che terminano il buffer.

[out] AlgorithmBuffer

Indirizzo di una variabile che riceve un puntatore a un buffer contenente stringhe ANSI con chiusura NULL. Ogni stringa rappresenta un OID per un algoritmo hash. La stringa finale nel buffer deve essere terminata da due valori NULL successivi.

Valore restituito

Se la funzione ha esito positivo, restituisce S_OK. Se la funzione ha esito negativo, deve restituire uno dei valori HRESULT seguenti per indicare l'errore.

Commenti

Solo l'algoritmo hash SHA1 viene usato da Windows Biometric Framework. Pertanto, questo OID deve essere incluso nel buffer. Altre stringhe OID sono facoltative e possono essere incluse per le versioni future di Windows. In Wincrypt.h, incluso nel Windows SDK, il simbolo per l'algoritmo SHA1 è szOID_OIWSEC_sha1 e il valore stringa associato è "1.3.14.3.2.26". Questo valore stringa deve trovarsi nel buffer. Per altri valori OID, vedere Wincrypt.h.

Nell'esempio seguente viene illustrato come creare un buffer OID. L'algoritmo SHA1 ("1.3.14.3.2.26") è incluso prima anche se l'ordine di inclusione non è importante. È incluso anche un altro algoritmo, szOID_OIWSEC_shaRSA con un valore "1.3.14.3.2.15". Si noti che un singolo valore NULL identifica la fine di ogni stringa OID e che un valore NULL aggiuntivo dopo la fine dell'ultima stringa identifica la fine del buffer.

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

Se questa funzione ha esito positivo, restituire l'indirizzo dell'inizio di questo buffer nell'argomento AlgorithmBuffer . L'adattatore del motore possiede il buffer. Poiché Windows Biometric Framework legge il buffer, l'indirizzo deve rimanere valido finché l'adattatore del motore è collegato all'unità biometrica.

In genere, si compila la tabella delle stringhe OID nell'adattatore del motore come blocco dati statico.

Esempio

Lo pseudocode seguente mostra una possibile implementazione di questa funzione. L'esempio non viene compilato. Devi adattarla per adattarti al tuo scopo.

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

Requisiti

Vedi anche

EngineAdapterSetHashAlgorithm

Funzioni plug-in