Función WinBioCancel (winbio.h)

Artículo
03/08/2023

Cancela todas las operaciones biométricas pendientes para una sesión especificada. A partir de Windows 10, compilación 1607, esta función está disponible para su uso con una imagen móvil.

Sintaxis

HRESULT WinBioCancel(
  [in] WINBIO_SESSION_HANDLE SessionHandle
);

Parámetros

[in] SessionHandle

Valor WINBIO_SESSION_HANDLE que identifica una sesión biométrica abierta. Abra un identificador de sesión sincrónico llamando a WinBioOpenSession. Abra un identificador de sesión asincrónico llamando a WinBioAsyncOpenSession.

Valor devuelto

Si la función se realiza correctamente, devuelve S_OK. Si se produce un error en la función, devuelve un valor HRESULT que indica el error. Entre los valores posibles se incluyen los que se indican en la tabla siguiente, entre otros. Para obtener una lista de códigos de error comunes, consulte Valores HRESULT comunes.

Código devuelto	Descripción
E_HANDLE	El identificador de sesión no es válido.

Comentarios

Para usar WinBioCancel de forma sincrónica, llame a la función con un identificador de sesión creado mediante una llamada a WinBioOpenSession. Cuando se llama a la función mediante un identificador de sesión sincrónico:

Si no hay ninguna operación pendiente, la función devuelve S_OK y no realiza ninguna otra acción.
Las operaciones asincrónicas pendientes reciben una notificación de devolución de llamada para la que el parámetro OperationStatus está establecido en WINBIO_E_CANCELED.
Las operaciones asincrónicas bloqueadas iniciadas por otros subprocesos del proceso devuelven WINBIO_E_CANCELED.

Para usar WinBioCancel de forma asincrónica, llame a la función con un identificador de sesión creado mediante una llamada a WinBioAsyncOpenSession. Al llamar a la función con un identificador de sesión asincrónico:

La función comprueba el parámetro de entrada y devuelve inmediatamente con S_OK o un código de error.
Las operaciones asincrónicas pendientes reciben una notificación de finalización que establece el miembro ApiStatus de sus respectivas estructuras de WINBIO_ASYNC_RESULTen WINBIO_E_CANCELED.

El marco también asigna una estructura de WINBIO_ASYNC_RESULT para WinBioCancel y la usa para devolver información sobre el éxito o el error de cancelación. La estructura WINBIO_ASYNC_RESULT se devuelve a la devolución de llamada de la aplicación o a la cola de mensajes de la aplicación, según el valor establecido en el parámetro NotificationMethod de la función WinBioAsyncOpenSession :

Si decide recibir avisos de finalización mediante una devolución de llamada, debe implementar una función de PWINBIO_ASYNC_COMPLETION_CALLBACK y establecer el parámetro NotificationMethod en WINBIO_ASYNC_NOTIFY_CALLBACK.
Si decide recibir notificaciones de finalización mediante la cola de mensajes de la aplicación, debe establecer el parámetro NotificationMethoden WINBIO_ASYNC_NOTIFY_MESSAGE. El marco devuelve un puntero WINBIO_ASYNC_RESULT al campo LPARAM del mensaje de ventana.

Para evitar pérdidas de memoria, debes llamar a WinBioFree para liberar la estructura WINBIO_ASYNC_RESULT después de haber terminado de usarlo.

Ejemplos

En el ejemplo de código siguiente se captura un ejemplo de forma asincrónica mediante una llamada a WinBioCaptureSampleWithCallback. Puede pasar un valor booleano a la función que, si se establece en TRUE, cancele la operación de captura. Vincule a la biblioteca estática Winbio.lib e incluya los siguientes archivos de encabezado:

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbio.h (incluye Winbio.h)
Library	Winbio.lib
Archivo DLL	Winbio.dll

Compartir a través de

Función WinBioCancel (winbio.h)

Sintaxis

Parámetros

Valor devuelto

Comentarios

Ejemplos

Requisitos

Comentarios

Recursos adicionales