次の方法で共有


WinBioIdentify 関数 (winbio.h)

生体認証サンプルをキャプチャし、既存の生体認証テンプレートと一致するかどうかを判断します。 ビルド 1607 Windows 10以降、この関数はモバイル イメージで使用できます。

構文

HRESULT WinBioIdentify(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [out, optional] WINBIO_UNIT_ID           *UnitId,
  [out, optional] WINBIO_IDENTITY          *Identity,
  [out, optional] WINBIO_BIOMETRIC_SUBTYPE *SubFactor,
  [out, optional] WINBIO_REJECT_DETAIL     *RejectDetail
);

パラメーター

[in] SessionHandle

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

[out, optional] UnitId

識別の実行に使用される生体認証ユニットを指定する ULONG 値へのポインター。

[out, optional] Identity

生体認証 サンプルを提供 するユーザーの GUID または SID を受け取るWINBIO_IDENTITY構造体へのポインター。

[out, optional] SubFactor

生体認証サンプルに関連付けられているサブ要素を受け取る WINBIO_BIOMETRIC_SUBTYPE値への ポインター。 詳細については、「解説」を参照してください。

[out, optional] RejectDetail

生体認証サンプルをキャプチャするためのエラーに関する追加情報 (存在する場合) を含む ULONG 値へのポインター。 キャプチャが成功した場合、このパラメーターは 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_HANDLE
セッション ハンドルが無効です。
E_POINTER
UnitIdIdentitySubFactorRejectDetail の各パラメーターで指定されたポインターを NULL にすることはできません。
WINBIO_E_BAD_CAPTURE
サンプルをキャプチャできませんでした。 詳細については、 RejectDetail 値を使用してください。
WINBIO_E_ENROLLMENT_IN_PROGRESS
生体認証ユニットが現在登録トランザクションに使用されているため、操作を完了できませんでした (システム プールのみ)。
WINBIO_E_UNKNOWN_ID
生体認証サンプルは、データベースに保存されているサンプルと一致しません。

注釈

SubFactor パラメーターで返される値は、生体認証サンプルに関連付けられているサブ要素を指定します。 現在、Windows 生体認証フレームワーク (WBF) は指紋キャプチャのみをサポートしており、次の定数を使用してサブタイプ情報を表します。

  • WINBIO_ANSI_381_POS_RH_THUMB
  • WINBIO_ANSI_381_POS_RH_INDEX_FINGER
  • WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
  • WINBIO_ANSI_381_POS_RH_RING_FINGER
  • WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
  • WINBIO_ANSI_381_POS_LH_THUMB
  • WINBIO_ANSI_381_POS_LH_INDEX_FINGER
  • WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
  • WINBIO_ANSI_381_POS_LH_RING_FINGER
  • WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
  • WINBIO_ANSI_381_POS_RH_FOUR_FINGERS
  • WINBIO_ANSI_381_POS_LH_FOUR_FINGERS
WinBioIdentify を同期的に使用するには、WinBioOpenSession を呼び出して作成されたセッション ハンドルで 関数を呼び出します。 関数は、操作が完了するか、エラーが発生するまでブロックします。

WinBioIdentify を非同期的に使用するには、WinBioAsyncOpenSession を呼び出して作成されたセッション ハンドルで 関数を呼び出します。 フレームワークは 、WINBIO_ASYNC_RESULT 構造体を割り当て、それを使用して操作の成功または失敗に関する情報を返します。 操作が成功した場合、フレームワークは入れ子になった Identify 構造体内のWINBIO_IDENTITYおよびWINBIO_BIOMETRIC_SUBTYPE情報を返します。 操作が失敗した場合、フレームワークは Identify 構造体WINBIO_REJECT_DETAIL情報を返します。 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: この操作は、 WinBioIdentifyWithCallback 関数を使用して非同期的に実行できます。 関数は入力引数を検証し、すぐにを返します。 入力引数が無効な場合、関数はエラー コードを返します。 それ以外の場合、フレームワークは別のスレッドで操作を開始します。 非同期操作が完了するか、エラーが発生すると、フレームワークはアプリケーションによって実装された PWINBIO_IDENTIFY_CALLBACK 関数に結果を送信します。

次の関数は 、WinBioEnumEnrollments を呼び出して、テンプレートに登録されている生体認証サブ要素を列挙し、 WinBioIdentify を呼び出して、ユーザーを識別する WINBIO_IDENTITY オブジェクトを取得します。 Winbio.lib 静的ライブラリにリンクし、次のヘッダー ファイルを含めます。

  • Windows.h
  • Stdio.h
  • Conio.h
  • Winbio.h
HRESULT EnumEnrollments( )
{
    // Declare variables.
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    PWINBIO_BIOMETRIC_SUBTYPE subFactorArray = NULL;
    WINBIO_BIOMETRIC_SUBTYPE SubFactor = 0;
    SIZE_T subFactorCount = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_BIOMETRIC_SUBTYPE subFactor = WINBIO_SUBTYPE_NO_INFORMATION;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_DEFAULT,        // Configuration and access
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            NULL,                       // Database ID
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate the biometric sensor and retrieve a WINBIO_IDENTITY object.
    wprintf_s(L"\n Calling WinBioIdentify - Swipe finger on sensor...\n");
    hr = WinBioIdentify( 
            sessionHandle,              // Session handle
            &unitId,                    // Biometric unit ID
            &identity,                  // User SID
            &subFactor,                 // Finger sub factor
            &rejectDetail               // Rejection information
            );
    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_UNKNOWN_ID)
        {
            wprintf_s(L"\n Unknown identity.\n");
        }
        else if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    // Retrieve the biometric sub-factors for the template.
    hr = WinBioEnumEnrollments( 
            sessionHandle,              // Session handle
            unitId,                     // Biometric unit ID
            &identity,                  // Template ID
            &subFactorArray,            // Subfactors
            &subFactorCount             // Count of subfactors
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnumEnrollments failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Print the sub-factor(s) to the console.
    wprintf_s(L"\n Enrollments for this user on Unit ID %d:", unitId);
    for (SIZE_T index = 0; index < subFactorCount; ++index)
    {
        SubFactor = subFactorArray[index];
        switch (SubFactor)
        {
            case WINBIO_ANSI_381_POS_RH_THUMB:
                wprintf_s(L"\n   RH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_RH_INDEX_FINGER:
                wprintf_s(L"\n   RH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER:
                wprintf_s(L"\n   RH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_RING_FINGER:
                wprintf_s(L"\n   RH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_LITTLE_FINGER:
                wprintf_s(L"\n   RH little finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_THUMB:
                wprintf_s(L"\n   LH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_LH_INDEX_FINGER:
                wprintf_s(L"\n   LH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER:
                wprintf_s(L"\n   LH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_RING_FINGER:
                wprintf_s(L"\n   LH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_LITTLE_FINGER:
                wprintf_s(L"\n   LH little finger\n");
                break;
            default:
                wprintf_s(L"\n   The sub-factor is not correct\n");
                break;
        }
 
    }

e_Exit:
    if (subFactorArray!= NULL)
    {
        WinBioFree(subFactorArray);
        subFactorArray = 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

こちらもご覧ください

WinBioIdentifyWithCallback