WinBioCaptureSampleWithCallback 関数 (winbio.h)

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

生体認証サンプルを非同期的にキャプチャし、生体認証情報レコード (BIR) 内の生データまたは処理されたデータを返します。関数は、呼び出し元に直ちに戻り、別のスレッドでサンプルをキャプチャし、アプリケーション定義のコールバック関数を呼び出して操作の状態を更新します。

重要

Windows 8 以降では、この関数を使用して非同期操作を開始しなくなったことをお勧めします。代わりに、次の操作を行います。

操作が完了したときに通知を受け取る PWINBIO_ASYNC_COMPLETION_CALLBACK 関数を実装します。
WinBioAsyncOpenSession 関数を呼び出します。 CallbackRoutine パラメーターでコールバックのアドレスを渡します。 NotificationMethod パラメーターにWINBIO_ASYNC_NOTIFY_CALLBACKを渡します。非同期セッションハンドルを取得します。
非同期セッションハンドルを使用して WinBioCaptureSample を呼び出します。操作が完了すると、Windows 生体認証フレームワークは、結果を使用してWINBIO_ASYNC_RESULT 構造体を割り当てて初期化し、結果構造へのポインターを使用してコールバックを呼び出します。
コールバック実装から WinBioFree を呼び出して、 WINBIO_ASYNC_RESULT 構造体の使用が完了した後で解放します。

構文

HRESULT WinBioCaptureSampleWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_BIR_PURPOSE       Purpose,
  [in]           WINBIO_BIR_DATA_FLAGS    Flags,
  [in]           PWINBIO_CAPTURE_CALLBACK CaptureCallback,
  [in, optional] PVOID                    CaptureCallbackContext
);

パラメーター

[in] SessionHandle

開いている生体認証セッションを識別する WINBIO_SESSION_HANDLE 値。

[in] Purpose

サンプルの使用目的を指定するWINBIO_BIR_PURPOSEビットマスク。これには、次の値のビットごとの OR を指定できます。

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

キャプチャしたサンプルに適用する処理の種類を指定する値。これは、次のセキュリティおよび処理レベルフラグのビットごとの OR にすることができます。

WINBIO_DATA_FLAG_PRIVACY

サンプルを暗号化します。

WINBIO_DATA_FLAG_INTEGRITY

サンプルに署名するか、メッセージ認証コード (MAC) を使用して保護します。

WINBIO_DATA_FLAG_SIGNED

このフラグとWINBIO_DATA_FLAG_INTEGRITYflagが設定されている場合は、サンプルに署名します。このフラグが設定されていないが、WINBIO_DATA_FLAG_INTEGRITY フラグが設定されている場合は、MAC を計算します。

WINBIO_DATA_FLAG_RAW

センサーによってキャプチャされたのとまったく同じサンプルを返します。

WINBIO_DATA_FLAG_INTERMEDIATE

サンプルがクリーンアップされ、フィルター処理された後に返されます。

WINBIO_DATA_FLAG_PROCESSED

Purpose パラメーターで指定された目的に使用する準備ができたら、サンプルを返します。

[in] CaptureCallback

キャプチャ操作が成功または失敗したときに WinBioCaptureSampleWithCallback 関数によって呼び出されるコールバック関数のアドレス。コールバックを作成する必要があります。

[in, optional] CaptureCallbackContext

CaptureCallbackContext パラメーターでコールバック関数に渡されるアプリケーション定義データ構造のアドレス。この構造体には、カスタムコールバック関数が処理するように設計されている任意のデータを含めることができます。

戻り値

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

リターンコード	説明
E_ACCESSDENIED	呼び出し元に生のサンプルをキャプチャするアクセス許可がないか、 WINBIO_FLAG_RAW フラグを使用してセッションが開かれていました。
E_HANDLE	セッションハンドルが無効です。
E_NOTIMPL	生体認証ユニットは、要求された操作をサポートしていません。
E_POINTER	UnitId、Sample、SampleSize、RejectDetail の各ポインターを NULL にすることはできません。
WINBIO_E_ENROLLMENT_IN_PROGRESS	生体認証ユニットが現在登録トランザクションに使用されているため、操作を完了できませんでした (システムプールのみ)。

注釈

WinBioCaptureSampleWithCallback 関数は、サンプルを非同期的にキャプチャします。この関数を正常に呼び出すには、 WINBIO_FLAG_RAWを指定してセッションハンドルを開いている必要があります。必要な特権を持つのは、管理者アカウントとローカルシステムアカウントのみです。

Purpose パラメーターと Flags パラメーターの有効な組み合わせは、使用されている生体認証ユニットの機能によって異なります。サポートされている組み合わせと、それらがキャプチャされたデータにどのような影響を与えるかについては、ベンダーセンサーのドキュメントを参照してください。

呼び出し元は、Sample パラメーターによって返されるWINBIO_BIR構造体を解放する必要があります。

コールバックルーチンには、次のシグネチャが必要です。

VOID CALLBACK CaptureCallback(
__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
);

例

次のコード例では、 WinBioCaptureSampleWithCallback を呼び出し、カスタムコールバック関数へのポインターを渡すことによって、サンプルを非同期的にキャプチャします。コールバック関数 CaptureSampleCallback も表示されます。 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 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;
    }
}

要件

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

こちらもご覧ください

WinBioCaptureSample

WinBioCaptureSampleWithCallback 関数 (winbio.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース