Fonction WinBioCancel (winbio.h)

Article
08/27/2023

Annule toutes les opérations biométriques en attente pour une session spécifiée. À compter de Windows 10, build 1607, cette fonction peut être utilisée avec une image mobile.

Syntaxe

HRESULT WinBioCancel(
  [in] WINBIO_SESSION_HANDLE SessionHandle
);

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.

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_HANDLE	Le handle de session n’est pas valide.

Remarques

Pour utiliser WinBioCancel de manière synchrone, appelez la fonction avec un handle de session créé en appelant WinBioOpenSession. Lorsque vous appelez la fonction à l’aide d’un handle de session synchrone :

S’il n’y a aucune opération en attente, la fonction retourne S_OK et n’effectue aucune autre action.
Les opérations asynchrones en attente reçoivent une notification de rappel pour laquelle le paramètre OperationStatus est défini sur WINBIO_E_CANCELED.
Les opérations asynchrones bloquées démarrées par d’autres threads dans le processus retournent WINBIO_E_CANCELED.

Pour utiliser WinBioCancel de manière asynchrone, appelez la fonction avec un handle de session créé en appelant WinBioAsyncOpenSession. Lorsque vous appelez la fonction avec un handle de session asynchrone :

La fonction vérifie le paramètre d’entrée et retourne immédiatement avec S_OK ou un code d’erreur.
Les opérations asynchrones en attente reçoivent une notification d’achèvement qui définit le membre ApiStatus de leurs structures WINBIO_ASYNC_RESULT respectives sur WINBIO_E_CANCELED.

L’infrastructure alloue également une structure de WINBIO_ASYNC_RESULT pour WinBioCancel et l’utilise pour retourner des informations sur la réussite ou l’échec de l’annulation. 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.

Exemples

L’exemple de code suivant capture un exemple de façon asynchrone en appelant WinBioCaptureSampleWithCallback. Vous pouvez passer une valeur booléenne à la fonction qui, si elle est définie sur TRUE, annule l’opération de capture. 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 operation 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 (inclure Winbio.h)
Bibliothèque	Winbio.lib
DLL	Winbio.dll

Partager via