WinBioCaptureSample 関数 (winbio.h)

生体認証サンプルをキャプチャし、生データまたは処理されたデータを生体認証情報レコード (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 値」を参照してください。

解説

この関数を正常に呼び出すには、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 ポインターを返します。

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

要件

関連項目

WinBioCaptureSampleWithCallback