WinBioCaptureSample 関数 (winbio.h)

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

生体認証サンプルをキャプチャし、生データまたは処理されたデータを生体認証情報レコード (BIR) に入力します。

構文

HRESULT WinBioCaptureSample(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_BIR_PURPOSE    Purpose,
  [in]            WINBIO_BIR_DATA_FLAGS Flags,
  [out, optional] WINBIO_UNIT_ID        *UnitId,
                  PWINBIO_BIR           *Sample,
  [out, optional] SIZE_T                *SampleSize,
  [out, optional] WINBIO_REJECT_DETAIL  *RejectDetail
);

パラメーター

[in] SessionHandle

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

[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_INTEGRITY フラグが設定されている場合は、サンプルに署名します。このフラグが設定されていないが、WINBIO_DATA_FLAG_INTEGRITY フラグが設定されている場合は、MAC を計算します。

WINBIO_DATA_FLAG_RAW

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

WINBIO_DATA_FLAG_INTERMEDIATE

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

WINBIO_DATA_FLAG_PROCESSED

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

[out, optional] UnitId

サンプルを生成した生体認証ユニットの ID を含む WINBIO_UNIT_ID 値へのポインター。

Sample

サンプルを含む WINBIO_BIR 構造体へのポインターを受け取る変数のアドレス。構造体の使用が完了したら、 WinBioFree へのポインターを渡して、サンプルに割り当てられたメモリを解放する必要があります。

[out, optional] SampleSize

Sample パラメーターで返されるWINBIO_BIR構造体のサイズ (バイト単位) を含むSIZE_T値へのポインター。

[out, optional] RejectDetail

生体認証 サンプルのキャプチャ 失敗に関する追加情報を含むWINBIO_REJECT_DETAIL値へのポインター。キャプチャが成功した場合、このパラメーターは 0 に設定されます。指紋キャプチャには、次の値が定義されています。

WINBIO_FP_TOO_HIGH
WINBIO_FP_TOO_LOW
WINBIO_FP_TOO_LEFT
WINBIO_FP_TOO_RIGHT
WINBIO_FP_TOO_FAST
WINBIO_FP_TOO_SLOW
WINBIO_FP_POOR_QUALITY
WINBIO_FP_TOO_SKEWED
WINBIO_FP_TOO_SHORT
WINBIO_FP_MERGE_FAILURE

戻り値

関数が成功した場合は、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	生体認証ユニットが現在登録トランザクションに使用されているため、操作を完了できませんでした (システムプールのみ)。
WINBIO_E_INVALID_OPERATION	セキュリティで保護されたセンサーがセンサープールに存在するため、操作を完了できませんでした。

解説

この関数を正常に呼び出すには、WinBioOpenSession 関数または WinBioAsyncOpenSession 関数の Flags パラメーターに WINBIO_FLAG_RAW を指定して、セッションハンドルを開く必要があります。現時点では、管理者アカウントとローカルシステムアカウントで実行されているアプリケーションにのみ、必要な特権があります。

Purpose パラメーターと Flags パラメーターの有効な組み合わせは、使用されている生体認証ユニットの機能によって異なります。サポートされている有効な Purpose 値と Flags 値の組み合わせと、それらがキャプチャされたデータに与える影響を判断するには、ベンダーのセンサードキュメントを参照してください。サンプルの使用が完了したら、アプリケーションで WinBioFree を呼び出して、 WinBioCaptureSample 関数によって割り当てられたメモリを解放する必要があります。

WinBioCaptureSample を同期的に使用するには、WinBioOpenSession を呼び出して作成されたセッションハンドルで関数を呼び出します。関数は、サンプルがキャプチャされるか、エラーが発生するまでブロックします。システムプールを使用して WinBioCaptureSample を呼び出すと、呼び出し元のアプリケーションにウィンドウフォーカスが設定され、ユーザーがプール内のいずれかのセンサーにサンプルを提供するまでブロックされます。ユーザーが選択したセンサーが登録トランザクションに既に使用されている場合、関数は失敗し 、WINBIO_E_ENROLLMENT_IN_PROGRESSを返します。

WinBioCaptureSample を非同期的に使用するには、WinBioAsyncOpenSession を呼び出して作成されたセッションハンドルで関数を呼び出します。フレームワークは、WINBIO_ASYNC_RESULT 構造体を割り当て、それを使用して操作の成功または失敗に関する情報を返します。キャプチャ操作が成功した場合、フレームワークは入れ子になった CaptureSample 構造体のサンプルに関する情報を返します。操作が失敗した場合、フレームワークはエラー情報を返します。 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構造体を解放する必要があります。

Windows 7: この操作は、 WinBioCaptureSampleWithCallback 関数を使用して非同期的に実行できます。関数は入力引数を検証し、すぐにを返します。入力引数が無効な場合、関数はエラーコードを返します。それ以外の場合、フレームワークは別のスレッドで操作を開始します。非同期操作が完了するか、エラーが発生すると、フレームワークはアプリケーションによって実装された PWINBIO_CAPTURE_CALLBACK 関数に結果を送信します。

例

次の関数は 、WinBioCaptureSample を呼び出して、ユーザーから生体認証サンプルをキャプチャします。 Winbio.lib 静的ライブラリにリンクし、次のヘッダーファイルを含めます。

Windows.h
Stdio.h
Conio.h
Winbio.h

HRESULT CaptureSample()
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    PWINBIO_BIR sample = NULL;
    SIZE_T sampleSize = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Access: Capture raw data
            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.
    wprintf_s(L"\n Calling WinBioCaptureSample - Swipe sensor...\n");
    hr = WinBioCaptureSample(
            sessionHandle,
            WINBIO_NO_PURPOSE_AVAILABLE,
            WINBIO_DATA_FLAG_RAW,
            &unitId,
            &sample,
            &sampleSize,
            &rejectDetail
            );
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioCaptureSample failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    wprintf_s(L"\n Captured %d bytes.\n", sampleSize);


e_Exit:
    if (sample != NULL)
    {
        WinBioFree(sample);
        sample = NULL;
    }

    if (sessionHandle != NULL)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

    wprintf_s(L"\n Press any key to exit...");
    _getch();

    return hr;
}

要件


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

次の方法で共有

WinBioCaptureSample 関数 (winbio.h)

構文

パラメーター

戻り値

解説

例

要件

関連項目

フィードバック

その他のリソース