ホーム › Devices.BiometricFramework › WinBioLocateSensor

WinBioLocateSensor

関数

ユーザー操作により対象の生体センサーを特定する。

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

シグネチャ

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

HRESULT WinBioLocateSensor(
    DWORD SessionHandle,
    DWORD* UnitId   // optional
);

パラメーター

名前	型	方向	説明
SessionHandle	DWORD	in	開いているバイオメトリックセッションを識別する WINBIO_SESSION_HANDLE 値です。同期セッションハンドルを開くには WinBioOpenSession を呼び出します。非同期セッションハンドルを開くには WinBioAsyncOpenSession を呼び出します。
UnitId	DWORD*	outoptional	バイオメトリックユニットを指定する ULONG 値へのポインターです。

戻り値の型: HRESULT

公式ドキュメント

ユーザーが対話的に選択したバイオメトリックユニットの ID 番号を取得します。

戻り値

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

戻り値	説明
E_HANDLE	セッションハンドルが無効です。
E_POINTER	UnitId パラメーターで指定するポインターを NULL にすることはできません。
WINBIO_E_ENROLLMENT_IN_PROGRESS	バイオメトリックユニットが現在登録トランザクションに使用されているため、操作を完了できませんでした (システムプールのみ)。

解説(Remarks)

複数のセンサーを備えたシステムでは、この関数を使用して、ユーザーが登録用にどのセンサーを優先しているかを判断できます。この関数は識別情報を返しません。ユーザーによるセンサーの選択を示すためだけに提供されています。

システムプールを使用してこの関数を呼び出した場合、アプリケーションがウィンドウフォーカスを取得し、ユーザーがバイオメトリックサンプルを提供するまでブロックします。そのため、アプリケーションはフォーカスを取得するまで WinBioLocateSensor を呼び出さないことをお勧めします。フォーカスを取得する方法は、作成するアプリケーションの種類によって異なります。たとえば、GUI アプリケーションを作成する場合は、WM_ACTIVATE、WM_SETFOCUS、またはその他の適切なメッセージを捕捉するメッセージハンドラーを実装できます。CUI アプリケーションを作成する場合は、GetConsoleWindow を呼び出してコンソールウィンドウのハンドルを取得し、そのハンドルを SetForegroundWindow 関数に渡して、コンソールウィンドウを強制的に前面に移動させてフォーカスを割り当てます。アプリケーションがデタッチされたプロセスで実行されていてウィンドウを持たない場合や、Windows サービスである場合は、WinBioAcquireFocus と WinBioReleaseFocus を使用してフォーカスを手動で制御してください。

WinBioLocateSensor を同期的に使用するには、WinBioOpenSession を呼び出して作成したセッションハンドルを指定して、この関数を呼び出します。この関数は、操作が完了するかエラーが発生するまでブロックします。

WinBioLocateSensor を非同期的に使用するには、WinBioAsyncOpenSession を呼び出して作成したセッションハンドルを指定して、この関数を呼び出します。フレームワークは WINBIO_ASYNC_RESULT 構造体を割り当て、それを使用して操作の成否に関する情報を返します。WINBIO_ASYNC_RESULT 構造体は、WinBioAsyncOpenSession 関数の NotificationMethod パラメーターに設定した値に応じて、アプリケーションのコールバックまたはアプリケーションのメッセージキューに返されます。

コールバックを使用して完了通知を受け取る場合は、PWINBIO_ASYNC_COMPLETION_CALLBACK 関数を実装し、NotificationMethod パラメーターに WINBIO_ASYNC_NOTIFY_CALLBACK を設定する必要があります。
アプリケーションのメッセージキューを使用して完了通知を受け取る場合は、NotificationMethod パラメーターに WINBIO_ASYNC_NOTIFY_MESSAGE を設定する必要があります。フレームワークは、ウィンドウメッセージの LPARAM フィールドに WINBIO_ASYNC_RESULT ポインターを返します。

メモリリークを防ぐため、WINBIO_ASYNC_RESULT 構造体の使用が終わったら、WinBioFree を呼び出して解放する必要があります。

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

例

次の関数は、インストールされているバイオメトリックセンサーを検出するために WinBioLocateSensor を呼び出します。 Winbio.lib スタティックライブラリをリンクし、次のヘッダーファイルをインクルードしてください。

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

HRESULT LocateSensor( )
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;

    // システムプールに接続します。
    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"
 WinBioEnumBiometricUnits failed. hr = 0x%x
", hr);
        goto e_Exit;
    }

    // センサーを検出します。
    wprintf_s(L"
 Tap the sensor once...
");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"
 WinBioLocateSensor failed. hr = 0x%x
", hr);
        goto e_Exit;
    }
    wprintf_s(L"
 Sensor located successfully. ");
    wprintf_s(L"
 Unit ID = %d 
", unitId);

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

    wprintf_s(L"
 Hit any key to exit...");
    _getch();

    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 WinBioLocateSensor(
    DWORD SessionHandle,
    DWORD* UnitId   // optional
);

[DllImport("winbio.dll", ExactSpelling = true)]
static extern int WinBioLocateSensor(
    uint SessionHandle,   // DWORD
    IntPtr UnitId   // DWORD* optional, out
);

<DllImport("winbio.dll", ExactSpelling:=True)>
Public Shared Function WinBioLocateSensor(
    SessionHandle As UInteger,   ' DWORD
    UnitId As IntPtr   ' DWORD* optional, out
) As Integer
End Function

' SessionHandle : DWORD
' UnitId : DWORD* optional, out
Declare PtrSafe Function WinBioLocateSensor Lib "winbio" ( _
    ByVal SessionHandle As Long, _
    ByVal UnitId As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WinBioLocateSensor = ctypes.windll.winbio.WinBioLocateSensor
WinBioLocateSensor.restype = ctypes.c_int
WinBioLocateSensor.argtypes = [
    wintypes.DWORD,  # SessionHandle : DWORD
    ctypes.POINTER(wintypes.DWORD),  # UnitId : DWORD* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('winbio.dll')
WinBioLocateSensor = Fiddle::Function.new(
  lib['WinBioLocateSensor'],
  [
    -Fiddle::TYPE_INT,  # SessionHandle : DWORD
    Fiddle::TYPE_VOIDP,  # UnitId : DWORD* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "winbio")]
extern "system" {
    fn WinBioLocateSensor(
        SessionHandle: u32,  // DWORD
        UnitId: *mut u32  // DWORD* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("winbio.dll")]
public static extern int WinBioLocateSensor(uint SessionHandle, IntPtr UnitId);
"@
$api = Add-Type -MemberDefinition $sig -Name 'winbio_WinBioLocateSensor' -Namespace Win32 -PassThru
# $api::WinBioLocateSensor(SessionHandle, UnitId)

#uselib "winbio.dll"
#func global WinBioLocateSensor "WinBioLocateSensor" sptr, sptr
; WinBioLocateSensor SessionHandle, varptr(UnitId)   ; 戻り値は stat
; SessionHandle : DWORD -> "sptr"
; UnitId : DWORD* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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