WinBioCancel 関数 (winbio.h)

[アーティクル]
08/27/2023

指定したセッションに対して保留中のすべての生体認証操作を取り消します。 Windows 10 ビルド 1607 以降では、この関数をモバイルイメージで使用できます。

構文

HRESULT WinBioCancel(
  [in] WINBIO_SESSION_HANDLE SessionHandle
);

パラメーター

[in] SessionHandle

開いている生体認証セッションを識別する WINBIO_SESSION_HANDLE 値。 WinBioOpenSession を呼び出して同期セッションハンドルを開きます。 WinBioAsyncOpenSession を呼び出して非同期セッションハンドルを開きます。

戻り値

関数が成功した場合は、S_OK を返します。関数が失敗した場合は、エラーを示す HRESULT 値を返します。有効な値を次の表に示しますが、これ以外にもあります。一般的なエラーコードの一覧については、「共通の HRESULT 値」を参照してください。

リターンコード	説明
E_HANDLE	セッションハンドルが無効です。

注釈

WinBioCancel を同期的に使用するには、WinBioOpenSession を呼び出して作成されたセッションハンドルで関数を呼び出します。同期セッションハンドルを使用して関数を呼び出す場合:

保留中の操作がない場合、関数はS_OKを返し、他のアクションは実行しません。
保留中の非同期操作は、 OperationStatus パラメーターが WINBIO_E_CANCELED に設定されているコールバック通知を受け取ります。
プロセス内の他のスレッドによって開始されたブロックされた非同期操作は 、WINBIO_E_CANCELEDを返します。

WinBioCancel を非同期的に使用するには、WinBioAsyncOpenSession を呼び出して作成されたセッションハンドルで関数を呼び出します。非同期セッションハンドルを使用して関数を呼び出す場合:

関数は入力パラメーターを検証し、S_OKまたはエラーコードを使用してすぐにを返します。
保留中の非同期操作は、それぞれのWINBIO_ASYNC_RESULT構造体の ApiStatus メンバーをWINBIO_E_CANCELEDに設定する完了通知を受け取ります。

また、フレームワークは WinBioCancelにWINBIO_ASYNC_RESULT構造体を割り当て、それを使用してキャンセルの成功または失敗に関する情報を返します。 WINBIO_ASYNC_RESULT構造体は、WinBioAsyncOpenSession 関数の NotificationMethod パラメーターで設定した値に応じて、アプリケーションコールバックまたはアプリケーションメッセージキューに返されます。

コールバックを使用して完了通知を受け取る場合は、 PWINBIO_ASYNC_COMPLETION_CALLBACK 関数を実装し、 NotificationMethod パラメーターを WINBIO_ASYNC_NOTIFY_CALLBACK に設定する必要があります。
アプリケーションメッセージキューを使用して完了通知を受け取る場合は、 NotificationMethod パラメーターを WINBIO_ASYNC_NOTIFY_MESSAGE に設定する必要があります。フレームワークは、ウィンドウメッセージの LPARAM フィールドへのWINBIO_ASYNC_RESULT ポインターを返します。

メモリリークを防ぐには、 WinBioFree を呼び出して、WINBIO_ASYNC_RESULT 構造体の使用が完了した後で解放する必要があります。

例

次のコード例では、 WinBioCaptureSampleWithCallback を呼び出して、サンプルを非同期的にキャプチャします。ブール値を関数に渡すことができます。 TRUE に設定すると、キャプチャ操作を取り消すことができます。 Winbio.lib 静的ライブラリにリンクし、次のヘッダーファイルを含めます。

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

要件

要件	値
サポートされている最小のクライアント	Windows 7 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 R2 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	winbio.h (Winbio.h を含む)
Library	Winbio.lib
[DLL]	Winbio.dll

WinBioCancel 関数 (winbio.h)

構文

パラメーター

戻り値

注釈

例

要件

フィードバック

フィードバック

その他のリソース