WinBioAsyncOpenSession 関数 (winbio.h)

  • [アーティクル]

生体認証サービス プロバイダーと 1 つ以上の生体認証ユニットに非同期接続します。 Windows 10 ビルド 1607 以降では、この関数をモバイル イメージで使用できます。 成功した場合、関数は生体認証セッション ハンドルを返します。 このハンドルを使用して実行されるすべての操作は、 WinBioCloseSession を含む非同期的に完了し、 NotificationMethod パラメーターで指定されたメソッドを使用して結果がクライアント アプリケーションに返されます。

この関数の同期バージョンについては、「 WinBioOpenSession」を参照してください。

構文

HRESULT WinBioAsyncOpenSession(
  [in]            WINBIO_BIOMETRIC_TYPE             Factor,
  [in]            WINBIO_POOL_TYPE                  PoolType,
  [in]            WINBIO_SESSION_FLAGS              Flags,
  [in, optional]  WINBIO_UNIT_ID                    *UnitArray,
  [in, optional]  SIZE_T                            UnitCount,
  [in, optional]  GUID                              *DatabaseId,
  [in]            WINBIO_ASYNC_NOTIFICATION_METHOD  NotificationMethod,
  [in, optional]  HWND                              TargetWindow,
  [in, optional]  UINT                              MessageCode,
  [in, optional]  PWINBIO_ASYNC_COMPLETION_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                             UserData,
  [in]            BOOL                              AsynchronousOpen,
  [out, optional] WINBIO_SESSION_HANDLE             *SessionHandle
);

パラメーター

[in] Factor

列挙 する 生体認証ユニットの種類を指定するWINBIO_BIOMETRIC_TYPE フラグのビットマスク。 現在、 WINBIO_TYPE_FINGERPRINT のみがサポートされています。

[in] PoolType

セッションで使用される生体認証ユニットの種類を指定する ULONG 値。 次のいずれかの値を指定できます。

値 説明
WINBIO_POOL_SYSTEM
 セッションは、サービス プロバイダーによって管理される生体認証ユニットの共有コレクションに接続します。
WINBIO_POOL_PRIVATE
 セッションは、呼び出し元によって管理される生体認証ユニットのコレクションに接続します。

[in] Flags

新しいセッションの生体認証ユニットの構成とアクセス特性を指定する ULONG 値。 構成フラグは、セッション内のユニットの一般的な構成を指定します。 アクセス フラグは、アプリケーションで生体認証ユニットを使用する方法を指定します。 1 つの構成フラグを指定する必要がありますが、そのフラグを任意のアクセス フラグと組み合わせることができます。

値 説明
WINBIO_FLAG_DEFAULT
 グループ: 構成

生体認証ユニットは、インストール時に指定された方法で動作します。 PoolType パラメーターがWINBIO_POOL_SYSTEMされている場合は、この値を使用する必要があります。
WINBIO_FLAG_BASIC
 グループ: 構成

生体認証ユニットは、基本的なキャプチャ デバイスとしてのみ動作します。 すべての処理、照合、およびストレージ操作は、ソフトウェア プラグインによって実行されます。
WINBIO_FLAG_ADVANCED
 グループ: 構成

生体認証ユニットでは、内部処理とストレージ機能が使用されます。
WINBIO_FLAG_RAW
 グループ: アクセス

クライアント アプリケーションは 、WinBioCaptureSample を使用して生の生体認証データをキャプチャします。
WINBIO_FLAG_MAINTENANCE
 グループ: アクセス

クライアントは、 WinBioControlUnitPrivileged を呼び出すことによって、生体認証ユニットに対してベンダー定義の制御操作を実行します。

[in, optional] UnitArray

セッションに含める生体認証ユニット識別子の配列へのポインター。 WinBioEnumBiometricUnits を呼び出して生体認証ユニットを列挙できます。 PoolType パラメーターがWINBIO_POOL_SYSTEM場合は、この値を NULL に設定します。

[in, optional] UnitCount

UnitArray パラメーターが指す配列内の要素の数を示す 値です。 PoolType パラメーターがWINBIO_POOL_SYSTEM場合は、この値を 0 に設定します。

[in, optional] DatabaseId

セッションで使用されるデータベースを示す 値。 PoolType パラメーターがWINBIO_POOL_PRIVATE場合は、インストールされているデータベースの GUID を指定する必要があります。 PoolType パラメーターがWINBIO_POOL_PRIVATEされていない場合は、次のいずれかの共通値を指定できます。

値 説明
WINBIO_DB_DEFAULT
 センサー プール内の各生体認証ユニットは、既定の生体認証ユニット構成で指定された既定のデータベースを使用します。 PoolType パラメーターがWINBIO_POOL_SYSTEM場合は、この値を指定する必要があります。 PoolType パラメーターがWINBIO_POOL_PRIVATE場合は、この値を使用できません。
WINBIO_DB_BOOTSTRAP
 この値は、Windows を起動する前のシナリオで使用するように指定できます。 通常、データベースはセンサー チップの一部であるか、BIOS の一部であり、テンプレートの登録と削除にのみ使用できます。
WINBIO_DB_ONCHIP
 データベースはセンサー チップ上にあり、登録と照合に使用できます。

[in] NotificationMethod

この生体認証セッションでの非同期操作の完了通知をクライアント アプリケーションに配信する方法を指定します。 これは、次のいずれかの値である必要があります。

値 説明
WINBIO_ASYNC_NOTIFY_CALLBACK
 セッションは、アプリケーションによって定義されたコールバック関数を呼び出します。
WINBIO_ASYNC_NOTIFY_MESSAGE
 セッションは、アプリケーションのメッセージ キューにウィンドウ メッセージを投稿します。

[in, optional] TargetWindow

完了通知を受け取るウィンドウのハンドル。 NotificationMethod パラメーターが WINBIO_ASYNC_NOTIFY_MESSAGE に設定されていない限り、この値は無視されます。

[in, optional] MessageCode

フレームワークが完了通知を示すために送信する必要があるウィンドウ メッセージ コード。 NotificationMethod パラメーターが WINBIO_ASYNC_NOTIFY_MESSAGE に設定されていない限り、この値は無視されます。 値は、0xBFFF WM_APP(0x8000) の範囲内である必要があります。

Windows 生体認証フレームワークは、メッセージの LPARAM 値を、操作の結果を含む WINBIO_ASYNC_RESULT 構造体のアドレスに設定します。 使用が完了したら、 WinBioFree を呼び出して構造体を解放する必要があります。

[in, optional] CallbackRoutine

セッション ハンドルを使用して操作が開始されたときに呼び出されるコールバック ルーチンのアドレス。 NotificationMethod パラメーターが WINBIO_ASYNC_NOTIFY_CALLBACK に設定されていない限り、この値は無視されます。

[in, optional] UserData

呼び出し元によって提供されるバッファーのアドレス。 バッファーは、フレームワークまたは生体認証ユニットによって変更されません。 WINBIO_ASYNC_RESULT構造体で返されます。 アプリケーションはデータを使用して、完了通知の受信時に実行するアクションを決定したり、要求された操作に関する追加情報を保持したりするのに役立ちます。

[in] AsynchronousOpen

フレームワーク セッションが開かれるまでブロックするかどうかを指定します。 FALSE を指定すると、プロセスがブロックされます。 TRUE を指定すると、セッションが非同期で開かれます。

FALSE を指定してフレームワーク セッションを同期的に開くと、HRESULT 戻り値でこの関数によって、成功または失敗が呼び出し元に直接返されます。 セッションが正常に開かれた場合、アプリケーションが受け取る最初の非同期完了イベントは、フレームワークが開かれた後に要求された非同期操作に対して行われます。

フレームワーク セッションを非同期で開くために TRUE を 指定した場合、受信した最初の非同期完了通知はフレームワークを開くための通知になります。 NotificationMethod パラメーターが WINBIO_ASYNC_NOTIFY_CALLBACK に設定されている場合、操作の結果は CallbackRoutine パラメーターで指定されたコールバック関数のWINBIO_ASYNC_RESULT構造体に配信されます。 NotificationMethod パラメーターが WINBIO_ASYNC_NOTIFY_MESSAGE に設定されている場合、操作の結果は、ウィンドウ メッセージの LPARAM フィールドが指すWINBIO_ASYNC_RESULT構造体に配信されます。

[out, optional] SessionHandle

関数が成功しない場合、このパラメーターは NULL になります。

セッションが同期的に正常に開かれた場合、このパラメーターにはセッション ハンドルへのポインターが含まれます。

セッションを非同期で開くように指定した場合、このメソッドは直ちにを返します。セッション ハンドルは NULL になり、セッションが正常に開かれたかどうかを判断するには 、WINBIO_ASYNC_RESULT 構造体を調べる必要があります。

戻り値

関数が成功した場合は、S_OK を返します。 関数が失敗した場合は、エラーを示す HRESULT 値を返します。 有効な値を次の表に示しますが、これ以外にもあります。 一般的なエラー コードの一覧については、「 共通の HRESULT 値」を参照してください。

リターン コード 説明
E_OUTOFMEMORY
 生体認証セッションを作成するのに十分なメモリがありません。
E_INVALIDARG
 通知メソッドを WINBIO_ASYNC_NOTIFY_MESSAGE に設定した場合、 TargetWindow パラメーターを NULL または HWND_BROADCAST にすることはできません。 MessageCode パラメーターを 0 (0) にすることはできません。
E_POINTER
 SessionHandle パラメーターと AsyncOpen パラメーターを設定する必要があります。

通知メソッドを WINBIO_ASYNC_NOTIFY_CALLBACK に設定する場合は、 CallbackRoutine パラメーターでコールバック関数のアドレスも指定する必要があります。
E_ACCESSDENIED
 Flags パラメーターには、WINBIO_FLAG_RAWまたはWINBIO_FLAG_MAINTENANCE フラグが含まれており、呼び出し元にどちらのアクセス許可も付与されていません。
WINBIO_E_INVALID_UNIT
 UnitArray パラメーターで指定された 1 つ以上の生体認証ユニット番号が無効です。
WINBIO_E_NOT_ACTIVE_CONSOLE
 クライアント アプリケーションがリモート デスクトップ クライアントで実行されており、システム プール セッションを開こうとしています。
WINBIO_E_SENSOR_UNAVAILABLE
 PoolType パラメーターは WINBIO_POOL_PRIVATE に設定されており、そのプール内の 1 つ以上の要求されたセンサーは使用できません。
WINBIO_E_DISABLED
 現在の管理ポリシーでは、Windows 生体認証フレームワーク API の使用は禁止されています。

解説

WinBioAsyncOpenSession 関数によって返されるセッション ハンドルを使用して、次のいずれかの関数の非同期完了通知を生成できます。

WinBioAsyncOpenSession によって返されるセッション ハンドルは、次の関数では使用できません。 Windows 7 で最初に使用できるこれらの関数には互換性のないコールバック署名があり、新しいアプリケーションでの使用はお勧めしません。 非同期コールバックを必要とする開発者は、代わりに、NotificationMethod が WINBIO_ASYNC_NOTIFY_CALLBACK の WinBioAsyncOpenSession を使用する必要があります。

AsyncOpen パラメーターは、開いている操作がブロックされるかどうかを判断します。 このパラメーターは、セッション ハンドルを使用する後続の呼び出しの完了動作には影響しません。

AsyncOpen パラメーターを TRUE に設定すると、この関数は引数の初期検証を実行するとすぐにS_OKを返します。 その時点を超えて検出されたエラーは、 NotificationMethod パラメーターで指定されたメソッドを使用して呼び出し元に報告されます。 つまり、正常な戻り値は、 WinBioAsyncOpenSession パラメーターが正常であり、開いている操作が成功しなかったことを示すだけです。 開いている操作が成功したかどうかを判断するには、 WINBIO_ASYNC_RESULT 構造を調べる必要があります。

要件

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

関連項目

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession