WinBioCaptureSample, fonction (winbio.h)

Article
08/27/2023

Capture un échantillon biométrique et remplit un enregistrement d’informations biométriques (BIR) avec les données brutes ou traitées.

Syntaxe

HRESULT WinBioCaptureSample(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_BIR_PURPOSE    Purpose,
  [in]            WINBIO_BIR_DATA_FLAGS Flags,
  [out, optional] WINBIO_UNIT_ID        *UnitId,
                  PWINBIO_BIR           *Sample,
  [out, optional] SIZE_T                *SampleSize,
  [out, optional] WINBIO_REJECT_DETAIL  *RejectDetail
);

Paramètres

[in] SessionHandle

Valeur WINBIO_SESSION_HANDLE qui identifie une session biométrique ouverte. Ouvrez un handle de session synchrone en appelant WinBioOpenSession. Ouvrez un handle de session asynchrone en appelant WinBioAsyncOpenSession.

[in] Purpose

Masque de bits WINBIO_BIR_PURPOSE qui spécifie l’utilisation prévue de l’exemple. Il peut s’agir d’un or au niveau du bit des valeurs suivantes :

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

Valeur qui spécifie le type de traitement à appliquer à l’exemple capturé. Il peut s’agir d’un OR au niveau du bit des indicateurs de niveau de sécurité et de traitement suivants :

WINBIO_DATA_FLAG_PRIVACY

Chiffrez l’exemple.

WINBIO_DATA_FLAG_INTEGRITY

Signez l’exemple ou protégez-le à l’aide d’un code d’authentification de message (MAC)

WINBIO_DATA_FLAG_SIGNED

Si cet indicateur et l’indicateur WINBIO_DATA_FLAG_INTEGRITY sont définis, signez l’exemple. Si cet indicateur n’est pas défini, mais que l’indicateur WINBIO_DATA_FLAG_INTEGRITY est défini, calculez un MAC.

WINBIO_DATA_FLAG_RAW

Retourne l’échantillon exactement tel qu’il a été capturé par le capteur.

WINBIO_DATA_FLAG_INTERMEDIATE

Retourne l’exemple une fois qu’il a été nettoyé et filtré.

WINBIO_DATA_FLAG_PROCESSED

Retourne l’exemple une fois qu’il est prêt à être utilisé pour l’objectif spécifié par le paramètre Purpose.

[out, optional] UnitId

Pointeur vers une valeur WINBIO_UNIT_ID qui contient l’ID de l’unité biométrique qui a généré l’échantillon.

Sample

Adresse d’une variable qui reçoit un pointeur vers une structure WINBIO_BIR qui contient l’exemple. Une fois que vous avez terminé d’utiliser la structure, vous devez passer le pointeur vers WinBioFree pour libérer la mémoire allouée à l’exemple.

[out, optional] SampleSize

Pointeur vers une valeur SIZE_T qui contient la taille, en octets, de la structure WINBIO_BIR retournée dans le paramètre Sample .

[out, optional] RejectDetail

Pointeur vers une valeur de WINBIO_REJECT_DETAIL qui contient des informations supplémentaires sur l’échec de la capture d’un échantillon biométrique. Si la capture a réussi, ce paramètre est défini sur zéro. Les valeurs suivantes sont définies pour la capture d’empreintes digitales :

WINBIO_FP_TOO_HIGH
WINBIO_FP_TOO_LOW
WINBIO_FP_TOO_LEFT
WINBIO_FP_TOO_RIGHT
WINBIO_FP_TOO_FAST
WINBIO_FP_TOO_SLOW
WINBIO_FP_POOR_QUALITY
WINBIO_FP_TOO_SKEWED
WINBIO_FP_TOO_SHORT
WINBIO_FP_MERGE_FAILURE

Valeur retournée

Si la fonction réussit, elle retourne S_OK. Si la fonction échoue, elle retourne une valeur HRESULT qui indique l’erreur. Les valeurs possibles sont notamment celles figurant dans le tableau suivant. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.

Code de retour	Description
E_ACCESSDENIED	L’appelant n’est pas autorisé à capturer des échantillons bruts, ou la session n’a pas été ouverte à l’aide de l’indicateur WINBIO_FLAG_RAW .
E_HANDLE	Le handle de session n’est pas valide.
E_NOTIMPL	L’unité biométrique ne prend pas en charge l’opération demandée.
E_POINTER	Les pointeurs UnitId, Sample, SampleSize et RejectDetail ne peuvent pas être NULL.
WINBIO_E_ENROLLMENT_IN_PROGRESS	L’opération n’a pas pu être effectuée, car l’unité biométrique est actuellement utilisée pour une transaction d’inscription (pool système uniquement).
WINBIO_E_INVALID_OPERATION	L’opération n’a pas pu être effectuée, car un capteur sécurisé est présent dans le pool de capteurs.

Remarques

Pour appeler correctement cette fonction, vous devez ouvrir le handle de session en spécifiant WINBIO_FLAG_RAW dans le paramètre Flags des fonctions WinBioOpenSession ou WinBioAsyncOpenSession . Actuellement, seules les applications exécutées sous les comptes Administrateurs et Système local disposent des privilèges nécessaires.

Les combinaisons valides des paramètres Purpose et Flags dépendent des fonctionnalités de l’unité biométrique utilisée. Consultez la documentation du capteur du fournisseur pour déterminer quelles combinaisons de valeurs d’objet et d’indicateurs valides sont prises en charge et comment elles affectent les données capturées. Une fois l’exemple terminé, votre application doit appeler WinBioFree pour libérer la mémoire allouée par la fonction WinBioCaptureSample .

Pour utiliser WinBioCaptureSample de manière synchrone, appelez la fonction avec un handle de session créé en appelant WinBioOpenSession. La fonction se bloque jusqu’à ce qu’un exemple ait été capturé ou qu’une erreur se produise. Les appels à WinBioCaptureSample à l’aide du pool système se bloquent jusqu’à ce que l’application appelante ait le focus de fenêtre et que l’utilisateur fournisse un exemple à l’un des capteurs du pool. Si le capteur choisi par l’utilisateur est déjà utilisé pour une transaction d’inscription, la fonction échoue et retourne WINBIO_E_ENROLLMENT_IN_PROGRESS.

Pour utiliser WinBioCaptureSample de manière asynchrone, appelez la fonction avec un handle de session créé en appelant WinBioAsyncOpenSession. L’infrastructure alloue une structure WINBIO_ASYNC_RESULT et l’utilise pour retourner des informations sur la réussite ou l’échec de l’opération. Si l’opération de capture réussit, l’infrastructure retourne des informations sur l’exemple dans une structure CaptureSample imbriquée. Si l’opération échoue, l’infrastructure retourne des informations d’erreur. La structure WINBIO_ASYNC_RESULT est retournée au rappel d’application ou à la file d’attente de messages d’application, selon la valeur que vous avez définie dans le paramètre NotificationMethod de la fonction WinBioAsyncOpenSession :

Si vous choisissez de recevoir des notifications d’achèvement à l’aide d’un rappel, vous devez implémenter une fonction PWINBIO_ASYNC_COMPLETION_CALLBACK et définir le paramètre NotificationMethod sur WINBIO_ASYNC_NOTIFY_CALLBACK.
Si vous choisissez de recevoir des notifications d’achèvement à l’aide de la file d’attente de messages d’application, vous devez définir le paramètre NotificationMethodsur WINBIO_ASYNC_NOTIFY_MESSAGE. L’infrastructure retourne un pointeur WINBIO_ASYNC_RESULT vers le champ LPARAM du message de fenêtre.

Pour éviter les fuites de mémoire, vous devez appeler WinBioFree pour libérer la structure WINBIO_ASYNC_RESULT une fois que vous avez terminé de l’utiliser.

Windows 7 : Vous pouvez effectuer cette opération de manière asynchrone à l’aide de la fonction WinBioCaptureSampleWithCallback . La fonction vérifie les arguments d’entrée et retourne immédiatement. Si les arguments d’entrée ne sont pas valides, la fonction retourne un code d’erreur. Sinon, l’infrastructure démarre l’opération sur un autre thread. Lorsque l’opération asynchrone se termine ou rencontre une erreur, l’infrastructure envoie les résultats à la fonction PWINBIO_CAPTURE_CALLBACK implémentée par votre application.

Exemples

La fonction suivante appelle WinBioCaptureSample pour capturer un exemple biométrique à partir d’un utilisateur. Créez un lien vers la bibliothèque statique Winbio.lib et incluez les fichiers d’en-tête suivants :

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT CaptureSample()
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    PWINBIO_BIR sample = NULL;
    SIZE_T sampleSize = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Access: Capture raw data
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            WINBIO_DB_DEFAULT,          // Default database
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture a biometric sample.
    wprintf_s(L"\n Calling WinBioCaptureSample - Swipe sensor...\n");
    hr = WinBioCaptureSample(
            sessionHandle,
            WINBIO_NO_PURPOSE_AVAILABLE,
            WINBIO_DATA_FLAG_RAW,
            &unitId,
            &sample,
            &sampleSize,
            &rejectDetail
            );
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioCaptureSample failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    wprintf_s(L"\n Captured %d bytes.\n", sampleSize);


e_Exit:
    if (sample != NULL)
    {
        WinBioFree(sample);
        sample = NULL;
    }

    if (sessionHandle != NULL)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

    wprintf_s(L"\n Press any key to exit...");
    _getch();

    return hr;
}

Configuration requise


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.h (inclure Winbio.h)
Bibliothèque	Winbio.lib
DLL	Winbio.dll

Voir aussi

WinBioCaptureSampleWithCallback

Partager via