PIBIO_STORAGE_QUERY_BY_SUBJECT_FN fonction de rappel (winbio_adapter.h)

Article
08/27/2023

Appelé par l’infrastructure biométrique Windows ou par l’adaptateur du moteur pour localiser les modèles qui correspondent à une identité et un sous-facteur spécifiés.

Syntaxe

PIBIO_STORAGE_QUERY_BY_SUBJECT_FN PibioStorageQueryBySubjectFn;

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

Paramètres

[in, out] Pipeline

Pointeur vers la structure WINBIO_PIPELINE associée à l’unité biométrique effectuant l’opération.

[in] Identity

Pointeur vers une structure WINBIO_IDENTITY qui contient le GUID ou le SID à trouver. Si le champ Type de cette structure contient WINBIO_IDENTITY_TYPE_WILDCARD, la requête retourne chaque modèle correspondant au paramètre SubFactor .

[in] SubFactor

Valeur WINBIO_BIOMETRIC_SUBTYPE qui spécifie le sous-facteur à localiser. Si cette valeur est WINBIO_SUBTYPE_ANY, la requête retourne chaque modèle qui correspond au paramètre Identity .

Valeur retournée

Si la fonction réussit, elle retourne S_OK. Si la fonction échoue, elle doit retourner l’une des valeurs HRESULT suivantes pour indiquer l’erreur.

Code de retour	Description
E_INVALIDARG	L’argument spécifié par le paramètre SubFactor n’est pas valide ou un membre de la structure spécifiée par le paramètre Identity n’est pas valide.
E_POINTER	Un argument pointeur obligatoire est NULL.
WINBIO_E_DATABASE_NO_RESULTS	La requête a réussi, mais aucun enregistrement correspondant n’a pu être trouvé.
WINBIO_E_DATABASE_LOCKED	La base de données est verrouillée.
WINBIO_E_DATABASE_READ_ERROR	Un problème non spécifié s’est produit.
WINBIO_E_INVALID_DEVICE_STATE	Le membre StorageContext de l’objet pipeline est NULL ou le membre FileHandle n’est pas valide.

Remarques

Si cette méthode retourne correctement, le jeu de résultats dans le pipeline est remplacé par les résultats de la requête, même si la requête retourne un jeu vide.

Les appelants de cette fonction doivent pouvoir récupérer tous les enregistrements en procédant comme suit :

Passage d’une structure WINBIO_IDENTITY dans le paramètre Identity avec le champ Type défini sur WINBIO_IDENTITY_TYPE_WILDCARD.
Passage WINBIO_SUBTYPE_ANY dans le paramètre SubFactor .

Après un appel réussi à cette fonction, le curseur du jeu de résultats doit être positionné sur le premier enregistrement du jeu.

Important

N’essayez pas de valider la valeur fournie pour le paramètre SubFactor . Le service de biométrie Windows valide la valeur fournie avant de la transmettre à votre implémentation. Si la valeur est WINBIO_SUBTYPE_NO_INFORMATION ou WINBIO_SUBTYPE_ANY, validez le cas échéant.

Exemples

Le pseudo-code suivant montre une implémentation possible de cette fonction. L’exemple ne se compile pas. Vous devez l’adapter à votre objectif.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winbio_adapter.h (include Winbio_adapter.h)