PIBIO_STORAGE_QUERY_BY_SUBJECT_FN funzione di callback (winbio_adapter.h)

Articolo
08/27/2023

Chiamato da Windows Biometric Framework o dall'adattatore motore per individuare i modelli che corrispondono a un'identità e un sottofatto specificati.

Sintassi

PIBIO_STORAGE_QUERY_BY_SUBJECT_FN PibioStorageQueryBySubjectFn;

HRESULT PibioStorageQueryBySubjectFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_IDENTITY Identity,
  [in]      WINBIO_BIOMETRIC_SUBTYPE SubFactor
)
{...}

Parametri

[in, out] Pipeline

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

[in] Identity

Puntatore a una struttura WINBIO_IDENTITY contenente il GUID o IL SID da individuare. Se il campo Type di questa struttura contiene WINBIO_IDENTITY_TYPE_WILDCARD, la query restituisce ogni modello corrispondente al parametro SubFactor .

[in] SubFactor

Valore WINBIO_BIOMETRIC_SUBTYPE che specifica il sotto-fattore da individuare. Se questo valore è WINBIO_SUBTYPE_ANY, la query restituisce ogni modello corrispondente al parametro Identity .

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.

Codice restituito	Descrizione
E_INVALIDARG	L'argomento specificato dal parametro SubFactor non è valido o un membro della struttura specificata dal parametro Identity non è valido.
E_POINTER	Un argomento puntatore obbligatorio è NULL.
WINBIO_E_DATABASE_NO_RESULTS	La query ha avuto esito positivo, ma non è stato possibile trovare record corrispondenti.
WINBIO_E_DATABASE_LOCKED	Il database è bloccato.
WINBIO_E_DATABASE_READ_ERROR	Si è verificato un problema non specificato.
WINBIO_E_INVALID_DEVICE_STATE	Il membro StorageContext dell'oggetto pipeline è NULL o il membro FileHandle non è valido.

Commenti

Se questo metodo viene restituito correttamente, il set di risultati nella pipeline viene sostituito dai risultati della query anche se la query restituisce un set vuoto.

I chiamanti di questa funzione devono essere in grado di recuperare tutti i record tramite:

Passaggio di una struttura WINBIO_IDENTITY nel parametro Identity con il campo Type impostato su WINBIO_IDENTITY_TYPE_WILDCARD.
Passaggio di WINBIO_SUBTYPE_ANY nel parametro SubFactor .

Dopo la corretta chiamata a questa funzione, il cursore del set di risultati deve essere posizionato sul primo record del set.

Importante

Non tentare di convalidare il valore fornito per il parametro SubFactor . Il servizio Windows Biometrics convaliderà il valore fornito prima di passarlo all'implementazione. Se il valore è WINBIO_SUBTYPE_NO_INFORMATION o WINBIO_SUBTYPE_ANY, convalidare la posizione appropriata.

Esempio

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

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterQueryBySubject
//
// Purpose:
//      Locates templates that match a specified identity and sub-factor.
//
// Parameters:
//      Pipeline  -  Pointer to a WINBIO_PIPELINE structure associated with 
//                   the biometric unit performing the operation.
//      Identity  -  Pointer to a WINBIO_IDENTITY structure that contains the GUID 
//                   or SID to be located.
//      SubFactor -  A WINBIO_BIOMETRIC_SUBTYPE value that specifies the sub-factor 
//                   to be located.
//
static HRESULT
WINAPI
StorageAdapterQueryBySubject(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor
    )
{
    HRESULT hr = S_OK;
    SIZE_T recordCount = 0;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(Identity))
    {
        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;
    }

    // Verify the Identity argument.
    if (Identity->Type != WINBIO_ID_TYPE_GUID &&
        Identity->Type != WINBIO_ID_TYPE_SID &&
        Identity->Type != WINBIO_ID_TYPE_WILDCARD)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    if (Identity->Type == WINBIO_ID_TYPE_WILDCARD &&
        Identity->Value.Wildcard != WINBIO_IDENTITY_WILDCARD)
    {
        hr = E_INVALIDARG;
        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;
    }

    // Call a custom function (_FindAllMatchingRecords) that compares the 
    // identity and sub-factor values from the caller to the identity and
    // sub-factor values of every record in the database and adds the matching
    // database records to the result set in the pipeline.
    hr = _FindAllMatchingRecords( 
            Pipeline,
            Identity,
            SubFactor,
            &recordCount
            );
    if (FAILED(hr))
    {
        goto cleanup;
    }
    if (recordCount == 0)
    {
        hr = WINBIO_E_DATABASE_NO_RESULTS;
        goto cleanup;
    }

cleanup:

    return hr;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbio_adapter.h (includere Winbio_adapter.h)