ホーム › Devices.BiometricFramework › WinBioVerifyWithCallback

WinBioVerifyWithCallback

関数

コールバック方式で生体情報の本人確認検証を行う。

DLLwinbio.dll呼出規約winapi対応OSWindows 7 以降

シグネチャ

// winbio.dll
#include <windows.h>

HRESULT WinBioVerifyWithCallback(
    DWORD SessionHandle,
    WINBIO_IDENTITY* Identity,
    BYTE SubFactor,
    PWINBIO_VERIFY_CALLBACK VerifyCallback,
    void* VerifyCallbackContext   // optional
);

パラメーター

名前	型	方向	説明
SessionHandle	DWORD	in	開いているバイオメトリックセッションを識別する WINBIO_SESSION_HANDLE 値です。
Identity	WINBIO_IDENTITY*	in	バイオメトリックサンプルを提供するユーザーの GUID または SID を格納する WINBIO_IDENTITY 構造体へのポインターです。
SubFactor	BYTE	in	バイオメトリックサンプルに関連付けられたサブファクターを指定する WINBIO_BIOMETRIC_SUBTYPE 値です。詳細については「解説」セクションを参照してください。
VerifyCallback	PWINBIO_VERIFY_CALLBACK	in	検証が成功または失敗したときに WinBioVerifyWithCallback 関数から呼び出されるコールバック関数のアドレスです。このコールバックは呼び出し側で作成する必要があります。
VerifyCallbackContext	void*	inoptional	コールバック関数の VerifyCallbackContext パラメーターで返される、アプリケーション定義の省略可能な構造体です。この構造体には、カスタムコールバック関数が処理できる任意のデータを格納できます。

戻り値の型: HRESULT

公式ドキュメント

バイオメトリックサンプルを非同期にキャプチャし、そのサンプルが指定されたユーザー ID に対応するかどうかを判定します。

戻り値

関数が成功した場合は S_OK を返します。関数が失敗した場合は、エラーを示す HRESULT 値を返します。返される可能性のある値には、次の表に示すものが含まれます (ただし、これらに限定されません)。一般的なエラーコードの一覧については、「Common HRESULT Values」を参照してください。

戻り値	説明
E_HANDLE	セッションハンドルが無効です。
E_INVALIDARG	SubFactor 引数が正しくありません。
E_POINTER	Identity パラメーターおよび VerifyCallback パラメーターで指定するポインターを NULL にすることはできません。

解説(Remarks)

SubFactor パラメーターは、バイオメトリックサンプルに関連付けられたサブファクターを指定します。Windows Biometric Framework (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

コールバックルーチンは、呼び出し元プロセス内の任意のスレッドのコンテキストで実行されます。コールバックとアプリケーションの他の部分との間で共有される可能性のあるメモリへのアクセスを同期する責任は、呼び出し側にあります。

WinBioVerifyWithCallback 関数はすぐに戻り、呼び出し側に S_OK を返します。キャプチャおよび検証処理の状態を判断するには、コールバック関数内で OperationStatus パラメーターを調べる必要があります。

保留中のコールバック操作を取り消すには、WinBioCancel 関数を呼び出します。セッションを閉じた場合も、そのセッションのコールバックは暗黙的に取り消されます。

コールバックルーチンは、次のシグネチャを持つ必要があります。


VOID CALLBACK VerifyCallback(
__in_opt PVOID VerifyCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in BOOLEAN Match,
__in WINBIO_REJECT_DETAIL RejectDetail
);

例

次の関数は WinBioVerifyWithCallback を呼び出して、バイオメトリックサンプルが現在のユーザーのログオン ID と一致するかどうかを非同期に判定します。コールバックルーチン VerifyCallback とヘルパー関数 GetCurrentUserIdentity も含まれています。Winbio.lib スタティックライブラリをリンクし、次のヘッダーファイルをインクルードしてください。

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

HRESULT VerifyWithCallback(BOOL bCancel, WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    // 変数を宣言します。
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_IDENTITY identity = {0};

    // ユーザーの ID を取得します。
    hr = GetCurrentUserIdentity( &identity );
    if (FAILED(hr))
    {
        wprintf_s(L"\n User identity not found. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // システム プールに接続します。 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // サービス プロバイダー
            WINBIO_POOL_SYSTEM,         // プールの種類
            WINBIO_FLAG_DEFAULT,        // 構成とアクセス
            NULL,                       // バイオメトリック ユニット ID の配列
            0,                          // バイオメトリック ユニット ID の数
            NULL,                       // データベース ID
            &sessionHandle              // [out] セッション ハンドル
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // バイオメトリック サンプルを非同期に検証します。
    wprintf_s(L"\n Calling WinBioVerifyWithCallback.\n");
    hr = WinBioVerifyWithCallback(
            sessionHandle,              // 開いているセッション ハンドル
            &identity,                  // ユーザーの SID または GUID
            subFactor,                  // サンプルのサブファクター
            VerifyCallback,             // コールバック関数
            NULL                        // 省略可能なコンテキスト
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioVerifyWithCallback failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // bCancel フラグが設定されている場合は識別を取り消します。
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...\n");
        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;
        }
    }

    // 非同期の識別処理が完了するか取り消されるまで 
    // 待機します。
    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 Hit any key to continue...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// 次の関数は WinBioVerifyWithCallback のコールバックです。
// この関数はバイオメトリック サブシステムからの応答をフィルター処理し、 
// 結果をコンソール ウィンドウに書き込みます。
// 
VOID CALLBACK VerifyCallback(
  __in_opt PVOID VerifyCallbackContext,
  __in HRESULT OperationStatus,
  __in WINBIO_UNIT_ID UnitId,
  __in BOOLEAN Match,
  __in WINBIO_REJECT_DETAIL RejectDetail
  )
{
    UNREFERENCED_PARAMETER(VerifyCallbackContext);
    UNREFERENCED_PARAMETER(Match);

    wprintf_s(L"\n VerifyCallback executing");
    wprintf_s(L"\n Swipe processed for unit ID %d\n", UnitId);

    // ID を検証できませんでした。
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n Verification failed for the following reason:");
        if (OperationStatus == WINBIO_E_NO_MATCH)
        {
            wprintf_s(L"\n No match.\n");
        }
        else if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture.\n ");
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
        }
        else
        {
            wprintf_s(L"VerifyCallback failed.");
            wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus); 
        }
        goto e_Exit;
    }

    // ユーザー ID が検証されました。
    wprintf_s(L"\n Fingerprint verified:\n");

e_Exit:
    return;
}

//------------------------------------------------------------------------
// 次の関数は現在のユーザーの ID を取得します。
// これはヘルパー関数であり、Windows Biometric Framework API の
// 一部ではありません。
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
    // 変数を宣言します。
    HRESULT hr = S_OK;
    HANDLE tokenHandle = NULL;
    DWORD bytesReturned = 0;
    struct{
        TOKEN_USER tokenUser;
        BYTE buffer[SECURITY_MAX_SID_SIZE];
    } tokenInfoBuffer;

    // 入力の identity をゼロで初期化し、種類を指定します。
    ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
    Identity->Type = WINBIO_ID_TYPE_NULL;

    // 現在のプロセスに関連付けられた
    // アクセス トークンを開きます。
    if (!OpenProcessToken(
            GetCurrentProcess(),            // プロセス ハンドル
            TOKEN_READ,                     // 読み取りアクセスのみ
            &tokenHandle))                  // アクセス トークン ハンドル
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot open token handle: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // tokenInfoBuffer 構造体をゼロで初期化します。
    ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));

    // アクセス トークンの情報を取得します。ここでは
    // SID を取得します。
    if (!GetTokenInformation(
            tokenHandle,                    // アクセス トークン ハンドル
            TokenUser,                      // トークンのユーザー
            &tokenInfoBuffer.tokenUser,     // 格納先のバッファー
            sizeof(tokenInfoBuffer),        // バッファーのサイズ
            &bytesReturned))                // 必要なサイズ
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot query token information: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // tokenInfoBuffer 構造体から WINBIO_IDENTITY 構造体へ
    // SID をコピーします。 
    CopySid(
        SECURITY_MAX_SID_SIZE,
        Identity->Value.AccountSid.Data,
        tokenInfoBuffer.tokenUser.User.Sid
        );

    // SID のサイズを指定し、WINBIO_IDENTITY 構造体の
    // Type メンバーに WINBIO_ID_TYPE_SID を設定します。
    Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
    Identity->Type = WINBIO_ID_TYPE_SID;

e_Exit:

    if (tokenHandle != NULL)
    {
        CloseHandle(tokenHandle);
    }

    return hr;
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// winbio.dll
#include <windows.h>

HRESULT WinBioVerifyWithCallback(
    DWORD SessionHandle,
    WINBIO_IDENTITY* Identity,
    BYTE SubFactor,
    PWINBIO_VERIFY_CALLBACK VerifyCallback,
    void* VerifyCallbackContext   // optional
);

[DllImport("winbio.dll", ExactSpelling = true)]
static extern int WinBioVerifyWithCallback(
    uint SessionHandle,   // DWORD
    IntPtr Identity,   // WINBIO_IDENTITY*
    byte SubFactor,   // BYTE
    IntPtr VerifyCallback,   // PWINBIO_VERIFY_CALLBACK
    IntPtr VerifyCallbackContext   // void* optional
);

<DllImport("winbio.dll", ExactSpelling:=True)>
Public Shared Function WinBioVerifyWithCallback(
    SessionHandle As UInteger,   ' DWORD
    Identity As IntPtr,   ' WINBIO_IDENTITY*
    SubFactor As Byte,   ' BYTE
    VerifyCallback As IntPtr,   ' PWINBIO_VERIFY_CALLBACK
    VerifyCallbackContext As IntPtr   ' void* optional
) As Integer
End Function

' SessionHandle : DWORD
' Identity : WINBIO_IDENTITY*
' SubFactor : BYTE
' VerifyCallback : PWINBIO_VERIFY_CALLBACK
' VerifyCallbackContext : void* optional
Declare PtrSafe Function WinBioVerifyWithCallback Lib "winbio" ( _
    ByVal SessionHandle As Long, _
    ByVal Identity As LongPtr, _
    ByVal SubFactor As Byte, _
    ByVal VerifyCallback As LongPtr, _
    ByVal VerifyCallbackContext As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WinBioVerifyWithCallback = ctypes.windll.winbio.WinBioVerifyWithCallback
WinBioVerifyWithCallback.restype = ctypes.c_int
WinBioVerifyWithCallback.argtypes = [
    wintypes.DWORD,  # SessionHandle : DWORD
    ctypes.c_void_p,  # Identity : WINBIO_IDENTITY*
    ctypes.c_ubyte,  # SubFactor : BYTE
    ctypes.c_void_p,  # VerifyCallback : PWINBIO_VERIFY_CALLBACK
    ctypes.POINTER(None),  # VerifyCallbackContext : void* optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('winbio.dll')
WinBioVerifyWithCallback = Fiddle::Function.new(
  lib['WinBioVerifyWithCallback'],
  [
    -Fiddle::TYPE_INT,  # SessionHandle : DWORD
    Fiddle::TYPE_VOIDP,  # Identity : WINBIO_IDENTITY*
    -Fiddle::TYPE_CHAR,  # SubFactor : BYTE
    Fiddle::TYPE_VOIDP,  # VerifyCallback : PWINBIO_VERIFY_CALLBACK
    Fiddle::TYPE_VOIDP,  # VerifyCallbackContext : void* optional
  ],
  Fiddle::TYPE_INT)

#[link(name = "winbio")]
extern "system" {
    fn WinBioVerifyWithCallback(
        SessionHandle: u32,  // DWORD
        Identity: *mut WINBIO_IDENTITY,  // WINBIO_IDENTITY*
        SubFactor: u8,  // BYTE
        VerifyCallback: *const core::ffi::c_void,  // PWINBIO_VERIFY_CALLBACK
        VerifyCallbackContext: *mut ()  // void* optional
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("winbio.dll")]
public static extern int WinBioVerifyWithCallback(uint SessionHandle, IntPtr Identity, byte SubFactor, IntPtr VerifyCallback, IntPtr VerifyCallbackContext);
"@
$api = Add-Type -MemberDefinition $sig -Name 'winbio_WinBioVerifyWithCallback' -Namespace Win32 -PassThru
# $api::WinBioVerifyWithCallback(SessionHandle, Identity, SubFactor, VerifyCallback, VerifyCallbackContext)

#uselib "winbio.dll"
#func global WinBioVerifyWithCallback "WinBioVerifyWithCallback" sptr, sptr, sptr, sptr, sptr
; WinBioVerifyWithCallback SessionHandle, varptr(Identity), SubFactor, VerifyCallback, VerifyCallbackContext   ; 戻り値は stat
; SessionHandle : DWORD -> "sptr"
; Identity : WINBIO_IDENTITY* -> "sptr"
; SubFactor : BYTE -> "sptr"
; VerifyCallback : PWINBIO_VERIFY_CALLBACK -> "sptr"
; VerifyCallbackContext : void* optional -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "winbio.dll"
#cfunc global WinBioVerifyWithCallback "WinBioVerifyWithCallback" int, var, int, sptr, sptr
; res = WinBioVerifyWithCallback(SessionHandle, Identity, SubFactor, VerifyCallback, VerifyCallbackContext)
; SessionHandle : DWORD -> "int"
; Identity : WINBIO_IDENTITY* -> "var"
; SubFactor : BYTE -> "int"
; VerifyCallback : PWINBIO_VERIFY_CALLBACK -> "sptr"
; VerifyCallbackContext : void* optional -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "winbio.dll"
#cfunc global WinBioVerifyWithCallback "WinBioVerifyWithCallback" int, sptr, int, sptr, sptr
; res = WinBioVerifyWithCallback(SessionHandle, varptr(Identity), SubFactor, VerifyCallback, VerifyCallbackContext)
; SessionHandle : DWORD -> "int"
; Identity : WINBIO_IDENTITY* -> "sptr"
; SubFactor : BYTE -> "int"
; VerifyCallback : PWINBIO_VERIFY_CALLBACK -> "sptr"
; VerifyCallbackContext : void* optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。