PWINBIO_CAPTURE_CALLBACK fonction de rappel (winbio.h)

Article
08/27/2023

Appelée par l’infrastructure biométrique Windows pour retourner les résultats de la fonction asynchrone WinBioCaptureSampleWithCallback . L’application cliente doit implémenter cette fonction.

Important À compter de Windows 8, nous vous recommandons de ne plus utiliser la combinaison PWINBIO_CAPTURE_CALLBACK/WinBioCaptureSampleWithCallback. Au lieu de cela, procédez comme suit :

Implémentez une fonction PWINBIO_ASYNC_COMPLETION_CALLBACK pour recevoir une notification à la fin de l’opération.
Appelez la fonction WinBioAsyncOpenSession . Transmettez l’adresse de votre rappel dans le paramètre CallbackRoutine . Passez WINBIO_ASYNC_NOTIFY_CALLBACK dans le paramètre NotificationMethod . Récupérer un handle de session asynchrone.
Utilisez le handle de session asynchrone pour appeler WinBioCaptureSample. Une fois l’opération terminée, l’infrastructure biométrique Windows alloue et initialise une structure WINBIO_ASYNC_RESULT avec les résultats et appelle votre rappel avec un pointeur vers la structure des résultats.
Appelez WinBioFree à partir de votre implémentation de rappel pour libérer la structure WINBIO_ASYNC_RESULT une fois que vous avez terminé de l’utiliser.

Syntaxe

PWINBIO_CAPTURE_CALLBACK PwinbioCaptureCallback;

void PwinbioCaptureCallback(
  [in, optional] PVOID CaptureCallbackContext,
  [in]           HRESULT OperationStatus,
  [in]           WINBIO_UNIT_ID UnitId,
  [in]           PWINBIO_BIR Sample,
  [in]           SIZE_T SampleSize,
  [in]           WINBIO_REJECT_DETAIL RejectDetail
)
{...}

Paramètres

[in, optional] CaptureCallbackContext

Pointeur vers une mémoire tampon définie par l’application et passée au paramètre CaptureCallbackContext de la fonction WinBioCaptureSampleWithCallback . La mémoire tampon n’est pas modifiée par l’infrastructure ou l’unité biométrique. Votre application peut utiliser les données pour l’aider à déterminer les actions à effectuer ou pour conserver des informations supplémentaires sur la capture biométrique.

[in] OperationStatus

Code d’erreur retourné par l’opération de capture.

[in] UnitId

Numéro d’identification de l’unité biométrique.

[in] Sample

Pointeur vers les exemples de données.

[in] SampleSize

Taille, en octets, des exemples de données pointées par le paramètre Sample .

[in] RejectDetail

Informations supplémentaires sur l’échec, le cas échéant, d’effectuer l’opération. Pour plus d'informations, consultez la section Notes.

Valeur de retour

None

Remarques

Actuellement, l’infrastructure biométrique Windows ne prend en charge que les lecteurs d’empreintes digitales. Par conséquent, si une opération échoue et retourne des informations supplémentaires dans une constante WINBIO_REJECT_DETAIL , il s’agit de l’une des valeurs suivantes :

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

Exemples

L’exemple de code suivant capture un exemple de manière asynchrone en appelant WinBioCaptureSampleWithCallback et en passant un pointeur vers une fonction de rappel personnalisée, CaptureSampleCallback. 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 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;
    }
}

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.h

Voir aussi

constantes WINBIO_REJECT_DETAIL

WinBioCaptureSampleWithCallback

Partager via