WinBioCancel-Funktion (winbio.h)

Artikel
03/03/2024

Bricht alle ausstehenden biometrischen Vorgänge für eine angegebene Sitzung ab. Ab Windows 10, Build 1607, ist diese Funktion für die Verwendung mit einem mobilen Image verfügbar.

Syntax

HRESULT WinBioCancel(
  [in] WINBIO_SESSION_HANDLE SessionHandle
);

Parameter

[in] SessionHandle

Ein WINBIO_SESSION_HANDLE Wert, der eine offene biometrische Sitzung identifiziert. Öffnen Sie ein synchrones Sitzungshandle, indem Sie WinBioOpenSession aufrufen. Öffnen Sie ein asynchrones Sitzungshandle, indem Sie WinBioAsyncOpenSession aufrufen.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie S_OK zurück. Wenn die Funktion fehlschlägt, gibt sie einen HRESULT-Wert zurück, der den Fehler angibt. Mögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle. Eine Liste allgemeiner Fehlercodes finden Sie unter Allgemeine HRESULT-Werte.

Rückgabecode	Beschreibung
E_HANDLE	Das Sitzungshandle ist ungültig.

Hinweise

Um WinBioCancel synchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioOpenSession erstellt wird. Wenn Sie die Funktion mithilfe eines synchronen Sitzungshandles aufrufen:

Wenn keine ausstehenden Vorgänge vorhanden sind, gibt die Funktion S_OK zurück und führt keine anderen Aktionen aus.
Ausstehende asynchrone Vorgänge erhalten eine Rückrufbenachrichtigung, für die der Parameter OperationStatus auf WINBIO_E_CANCELED festgelegt ist.
Blockierte asynchrone Vorgänge, die von anderen Threads im Prozess gestartet werden, geben WINBIO_E_CANCELED zurück.

Um WinBioCancel asynchron zu verwenden, rufen Sie die Funktion mit einem Sitzungshandle auf, das durch Aufrufen von WinBioAsyncOpenSession erstellt wurde. Wenn Sie die Funktion mit einem asynchronen Sitzungshandle aufrufen:

Die Funktion überprüft den Eingabeparameter und gibt sofort mit S_OK oder einem Fehlercode zurück.
Ausstehende asynchrone Vorgänge erhalten eine Vervollständigungsbenachrichtigung, die das ApiStatus-Element ihrer jeweiligen WINBIO_ASYNC_RESULT-Strukturen auf WINBIO_E_CANCELED festlegt.

Das Framework weist auch eine WINBIO_ASYNC_RESULT-Struktur für WinBioCancel zu und verwendet sie, um Informationen zum Erfolg oder Fehler des Abbruchs zurückzugeben. Die WINBIO_ASYNC_RESULT Struktur wird an den Anwendungsrückruf oder an die Anwendungsmeldungswarteschlange zurückgegeben, abhängig vom Wert, den Sie im NotificationMethod-Parameter der WinBioAsyncOpenSession-Funktion festgelegt haben:

Wenn Sie sich dafür entscheiden, Vervollständigungsbenachrichtigungen mithilfe eines Rückrufs zu erhalten, müssen Sie eine PWINBIO_ASYNC_COMPLETION_CALLBACK-Funktion implementieren und den NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_CALLBACK festlegen.
Wenn Sie sich dafür entscheiden, Vervollständigungsbenachrichtigungen mithilfe der Anwendungsnachrichtenwarteschlange zu erhalten, müssen Sie den NotificationMethod-Parameter auf WINBIO_ASYNC_NOTIFY_MESSAGE festlegen. Das Framework gibt einen WINBIO_ASYNC_RESULT-Zeiger auf das LPARAM-Feld der Fensternachricht zurück.

Um Speicherverluste zu verhindern, müssen Sie WinBioFree aufrufen, um die WINBIO_ASYNC_RESULT-Struktur freizugeben, nachdem Sie sie verwendet haben.

Beispiele

Im folgenden Codebeispiel wird ein Beispiel asynchron erfasst, indem WinBioCaptureSampleWithCallback aufgerufen wird. Sie können einen booleschen Wert an die Funktion übergeben, die den Erfassungsvorgang abbrechen wird, wenn sie auf TRUE festgelegt ist. Verknüpfen Sie die statische Bibliothek Winbio.lib, und fügen Sie die folgenden Headerdateien ein:

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbio.h (einschließlich Winbio.h)
Bibliothek	Winbio.lib
DLL	Winbio.dll

Share via