WinBioCaptureSampleWithCallback, fonction (winbio.h)

Capture un échantillon biométrique de manière asynchrone et retourne les données brutes ou traitées dans un enregistrement d’informations biométriques (BIR). La fonction retourne immédiatement à l’appelant, capture l’exemple sur un thread distinct et appelle une fonction de rappel définie par l’application pour mettre à jour l’état de l’opération.

Syntaxe

HRESULT WinBioCaptureSampleWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_BIR_PURPOSE       Purpose,
  [in]           WINBIO_BIR_DATA_FLAGS    Flags,
  [in]           PWINBIO_CAPTURE_CALLBACK CaptureCallback,
  [in, optional] PVOID                    CaptureCallbackContext
);

Paramètres

[in] SessionHandle

Valeur WINBIO_SESSION_HANDLE qui identifie une session biométrique ouverte.

[in] Purpose

Masque de bits WINBIO_BIR_PURPOSE qui spécifie l’utilisation prévue de l’exemple. Il peut s’agir d’une 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’une 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 le WINBIO_DATA_FLAG_INTEGRITYflag 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

Retournez l’exemple exactement tel qu’il a été capturé par le capteur.

• WINBIO_DATA_FLAG_INTERMEDIATE

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

• WINBIO_DATA_FLAG_PROCESSED

Retournez l’exemple une fois qu’il est prêt à être utilisé à des fins spécifiées par le <>paramètre Mark Purpose</Mark>.

[in] CaptureCallback

Adresse d’une fonction de rappel qui sera appelée par la fonction WinBioCaptureSampleWithCallback lorsque l’opération de capture réussit ou échoue. Vous devez créer le rappel.

[in, optional] CaptureCallbackContext

Adresse d’une structure de données définie par l’application transmise à la fonction de rappel dans son paramètre CaptureCallbackContext . Cette structure peut contenir toutes les données que la fonction de rappel personnalisée est conçue pour gérer.

Valeur de retour

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 incluent, mais ne sont pas limitées à celles du tableau suivant. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.

Remarques

La fonction WinBioCaptureSampleWithCallback capture des exemples de manière asynchrone. Pour appeler cette fonction, le handle de session doit avoir été ouvert en spécifiant WINBIO_FLAG_RAW. Seuls les comptes Administrateurs et Système local disposent des privilèges nécessaires.

Les combinaisons valides des paramètres Usage et Indicateurs dépendent des fonctionnalités de l’unité biométrique utilisée. Consultez la documentation du capteur fournisseur pour déterminer quelles combinaisons sont prises en charge et comment elles affectent les données capturées.

Les appelants sont chargés de libérer la structure WINBIO_BIR retournée par le paramètre Sample .

La routine de rappel doit avoir la signature suivante :

VOID CALLBACK CaptureCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
);

Examples

L’exemple de code suivant capture un exemple de manière asynchrone en appelant WinBioCaptureSampleWithCallback et en passant un pointeur à une fonction de rappel personnalisée. La fonction de rappel, CaptureSampleCallback, est également affichée. 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 CaptureSampleWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Raw access
            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 asynchronously.
    wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
    hr = WinBioCaptureSampleWithCallback(
            sessionHandle,                  // Open session handle
            WINBIO_NO_PURPOSE_AVAILABLE,    // Intended use of the sample
            WINBIO_DATA_FLAG_RAW,           // Sample format
            CaptureSampleCallback,          // Callback function
            NULL                            // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the capture process if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...");
        Sleep( 7000 );

        wprintf_s(L"\n Calling WinBioCancel\n");
        hr = WinBioCancel( sessionHandle );
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioCancel failed. hr = 0x%x\n", hr);
            goto e_Exit;
        }
    }

    // Wait for the asynchronous capture process to complete 
    // or be canceled.
    hr = WinBioWait( sessionHandle );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
    }

e_Exit:

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

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

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
    __in_opt PVOID CaptureCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in_bcount(SampleSize) PWINBIO_BIR Sample,
    __in SIZE_T SampleSize,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(CaptureCallbackContext);

    wprintf_s(L"\n CaptureSampleCallback executing");
    wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);

    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
         }
        else
        {
            wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
            wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Captured %d bytes.\n", SampleSize);

e_Exit:

    if (Sample != NULL)
    {
        WinBioFree(Sample);
        Sample = NULL;
    }
}

Spécifications

Voir aussi

WinBioCaptureSample