WINBIO_ASYNC_RESULT
構造体サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。
フィールド
| フィールド | 型 | サイズ | x64 | x86 | 説明 |
|---|---|---|---|---|---|
| SessionHandle | DWORD | 4 | +0 | +0 | WinBioAsyncOpenSession 関数または WinBioAsyncOpenFramework 関数を呼び出して開始された非同期セッションのハンドルです。 |
| Operation | DWORD | 4 | +4 | +4 | 非同期操作の種類です。詳細については、WINBIO_OPERATION_TYPE 定数を参照してください。 |
| SequenceNumber | ULONGLONG | 8 | +8 | +8 | 非同期操作のシーケンス番号です。この整数は、バイオメトリック セッション内の各操作に対して 1 から順に割り当てられます。どのセッションでも、オープン操作には常に最初のシーケンス番号が、クローズ操作には最後のシーケンス番号が割り当てられます。アプリケーションが複数の操作をキューに入れる場合、シーケンス番号を使用してエラー処理を行うことができます。たとえば、特定のシーケンス番号がアプリケーションに送信されるまで操作結果を無視する、といった処理が可能です。 |
| TimeStamp | LONGLONG | 8 | +16 | +16 | バイオメトリック操作が開始されたシステム日時です。詳細については、GetSystemTimeAsFileTime 関数を参照してください。 |
| ApiStatus | HRESULT | 4 | +24 | +24 | 操作が返したエラー コードです。 |
| UnitId | DWORD | 4 | +28 | +28 | 操作を実行したバイオメトリック ユニットの数値のユニット識別子です。 |
| UserData | void* | 8/4 | +32 | +32 | 呼び出し元が指定する省略可能なバッファーのアドレスです。このバッファーは、フレームワークやバイオメトリック ユニットによって変更されません。アプリケーションはこのデータを利用して、完了通知を受け取ったときに実行する処理を判断したり、要求した操作に関する追加情報を保持したりできます。 |
| Parameters | _Parameters_e__Union | 8/4 | +40 | +36 | クライアント アプリケーションが開始した非同期操作の成否に関する追加情報を格納する、入れ子構造体を包含する共用体です。 |
共用体: _Parameters_e__Union x64 8B / x86 4B
| フィールド | 型 | サイズ | x64 | x86 | 説明 |
|---|---|---|---|---|---|
| Verify | _Verify_e__Struct | 8/4 | +0 | +0 | WinBioVerify への非同期呼び出しの結果を格納します。 |
| Identify | _Identify_e__Struct | 8/4 | +0 | +0 | WinBioIdentify への非同期呼び出しの結果を格納します。 |
| EnrollBegin | _EnrollBegin_e__Struct | 8/4 | +0 | +0 | WinBioEnrollBegin への非同期呼び出しの結果を格納します。 |
| EnrollCapture | _EnrollCapture_e__Struct | 8/4 | +0 | +0 | WinBioEnrollCapture への非同期呼び出しの結果を格納します。 |
| EnrollCommit | _EnrollCommit_e__Struct | 8/4 | +0 | +0 | WinBioEnrollCommit への非同期呼び出しの結果を格納します。 |
| EnumEnrollments | _EnumEnrollments_e__Struct | 8/4 | +0 | +0 | WinBioEnumEnrollments への非同期呼び出しの結果を格納します。 |
| CaptureSample | _CaptureSample_e__Struct | 8/4 | +0 | +0 | WinBioCaptureSample への非同期呼び出しの結果を格納します。 |
| DeleteTemplate | _DeleteTemplate_e__Struct | 8/4 | +0 | +0 | WinBioDeleteTemplate への非同期呼び出しの結果を格納します。 |
| GetProperty | _GetProperty_e__Struct | 8/4 | +0 | +0 | WinBioGetProperty への非同期呼び出しの結果を格納します。 |
| SetProperty | _SetProperty_e__Struct | 8/4 | +0 | +0 | WinBioSetProperty への非同期呼び出しの結果を格納します。このメンバーは Windows 10 以降でサポートされます。 SetProperty.PropretyBufferSizePropertyBuffer パラメーターが指す構造体のサイズ (バイト単位) です。 |
| GetEvent | _GetEvent_e__Struct | 8/4 | +0 | +0 | 発生したイベントに関する状態情報を格納します。 |
| ControlUnit | _ControlUnit_e__Struct | 8/4 | +0 | +0 | WinBioControlUnit または WinBioControlUnitPrivileged への非同期呼び出しの結果を格納します。 |
| EnumServiceProviders | _EnumServiceProviders_e__Struct | 8/4 | +0 | +0 | WinBioEnumServiceProviders または WinBioAsyncEnumServiceProviders への非同期呼び出しの結果を格納します。 |
| EnumBiometricUnits | _EnumBiometricUnits_e__Struct | 8/4 | +0 | +0 | WinBioEnumBiometricUnits または WinBioAsyncEnumBiometricUnits への非同期呼び出しの結果を格納します。 |
| EnumDatabases | _EnumDatabases_e__Struct | 8/4 | +0 | +0 | WinBioEnumDatabases または WinBioAsyncEnumDatabases への非同期呼び出しの結果を格納します。 |
| VerifyAndReleaseTicket | _VerifyAndReleaseTicket_e__Struct | 8/4 | +0 | +0 | 予約済みです。このメンバーは Windows 10 以降でサポートされます。 |
| IdentifyAndReleaseTicket | _IdentifyAndReleaseTicket_e__Struct | 8/4 | +0 | +0 | 予約済みです。このメンバーは Windows 10 以降でサポートされます。 |
| EnrollSelect | _EnrollSelect_e__Struct | 8/4 | +0 | +0 | WinBioEnrollSelect への非同期呼び出しの結果を格納します。このメンバーは Windows 10 以降でサポートされます。 |
| MonitorPresence | _MonitorPresence_e__Struct | 8/4 | +0 | +0 | WinBioMonitorPresence への非同期呼び出しの結果を格納します。このメンバーは Windows 10 以降でサポートされます。 |
| GetProtectionPolicy | _GetProtectionPolicy_e__Struct | 8/4 | +0 | +0 | |
| NotifyUnitStatusChange | _NotifyUnitStatusChange_e__Struct | 8/4 | +0 | +0 |
公式ドキュメント
WINBIO_ASYNC_RESULT 構造体は、非同期操作の結果を格納します。
解説(Remarks)
非同期操作は、バイオメトリック セッションまたはフレームワーク セッションを開くことによって開始します。バイオメトリック セッションを開くには WinBioAsyncOpenSession を呼び出します。フレームワーク セッションを開くには WinBioAsyncOpenFramework を呼び出します。
非同期バイオメトリック セッション ハンドルを使用すると、次の操作を非同期に呼び出すことができます。
- WinBioCancel
- WinBioCaptureSample
- WinBioCloseSession
- WinBioControlUnit
- WinBioControlUnitPrivileged
- WinBioDeleteTemplate
- WinBioEnrollBegin
- WinBioEnrollCapture
- WinBioEnrollCommit
- WinBioEnrollDiscard
- WinBioEnumEnrollments
- WinBioGetProperty
- WinBioIdentify
- WinBioLocateSensor
- WinBioLockUnit
- WinBioLogonIdentifiedUser
- WinBioRegisterEventMonitor
- WinBioUnlockUnit
- WinBioUnregisterEventMonitor
- WinBioVerify
- WinBioWait
- WinBioSetProperty
- WinBioEnrollSelect
- WinBioMonitorPresence
非同期フレームワーク ハンドルを使用すると、次の操作を非同期に呼び出すことができます。
- WinBioAsyncEnumBiometricUnits
- WinBioAsyncEnumDatabases
- WinBioAsyncOpenFramework
- WinBioAsyncEnumServiceProviders
- WinBioAsyncMonitorFrameworkChanges
WINBIO_ASYNC_RESULT 構造体は、Windows Biometric Framework によって内部的に割り当てられます。そのため、使用が終わったら WinBioFree を呼び出して、割り当てられたメモリを解放し、リークを防いでください。この呼び出しでは入れ子になったすべてのデータ構造も解放されるため、WINBIO_ASYNC_RESULT 構造体で返されたポインターのコピーを保持しないでください。入れ子構造体で返されたデータを保存したい場合は、WinBioFree を呼び出す前に、そのデータの独自のコピーを作成してください。
Windows 8、Windows Server 2012、Windows 8.1、Windows Server 2012 R2: Windows Biometric Framework は指紋リーダーのみをサポートします。そのため、操作が失敗して WINBIO_REJECT_DETAIL 定数で追加情報が返される場合、その値は次のいずれかになります。
- 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
さらに、操作が WINBIO_BIOMETRIC_SUBTYPE データ型を使用する場合、その値は次のいずれかになります。
- WINBIO_ANSI_381_POS_UNKNOWN
- 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
- WINBIO_ANSI_381_POS_TWO_THUMBS
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
各言語での定義
#include <windows.h>
// WINBIO_ASYNC_RESULT (x64 48 / x86 40 バイト)
typedef struct WINBIO_ASYNC_RESULT {
DWORD SessionHandle;
DWORD Operation;
ULONGLONG SequenceNumber;
LONGLONG TimeStamp;
HRESULT ApiStatus;
DWORD UnitId;
void* UserData;
_Parameters_e__Union Parameters;
} WINBIO_ASYNC_RESULT;using System;
using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct WINBIO_ASYNC_RESULT
{
public uint SessionHandle;
public uint Operation;
public ulong SequenceNumber;
public long TimeStamp;
public int ApiStatus;
public uint UnitId;
public IntPtr UserData;
public _Parameters_e__Union Parameters;
}Imports System.Runtime.InteropServices
<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure WINBIO_ASYNC_RESULT
Public SessionHandle As UInteger
Public Operation As UInteger
Public SequenceNumber As ULong
Public TimeStamp As Long
Public ApiStatus As Integer
Public UnitId As UInteger
Public UserData As IntPtr
Public Parameters As _Parameters_e__Union
End Structureimport ctypes
from ctypes import wintypes
class WINBIO_ASYNC_RESULT(ctypes.Structure):
_fields_ = [
("SessionHandle", wintypes.DWORD),
("Operation", wintypes.DWORD),
("SequenceNumber", ctypes.c_ulonglong),
("TimeStamp", ctypes.c_longlong),
("ApiStatus", ctypes.c_int),
("UnitId", wintypes.DWORD),
("UserData", ctypes.c_void_p),
("Parameters", _Parameters_e__Union),
]#[repr(C)]
pub struct WINBIO_ASYNC_RESULT {
pub SessionHandle: u32,
pub Operation: u32,
pub SequenceNumber: u64,
pub TimeStamp: i64,
pub ApiStatus: i32,
pub UnitId: u32,
pub UserData: *mut core::ffi::c_void,
pub Parameters: _Parameters_e__Union,
}import "golang.org/x/sys/windows"
type WINBIO_ASYNC_RESULT struct {
SessionHandle uint32
Operation uint32
SequenceNumber uint64
TimeStamp int64
ApiStatus int32
UnitId uint32
UserData uintptr
Parameters _Parameters_e__Union
}type
WINBIO_ASYNC_RESULT = record
SessionHandle: DWORD;
Operation: DWORD;
SequenceNumber: UInt64;
TimeStamp: Int64;
ApiStatus: Integer;
UnitId: DWORD;
UserData: Pointer;
Parameters: _Parameters_e__Union;
end;const WINBIO_ASYNC_RESULT = extern struct {
SessionHandle: u32,
Operation: u32,
SequenceNumber: u64,
TimeStamp: i64,
ApiStatus: i32,
UnitId: u32,
UserData: ?*anyopaque,
Parameters: _Parameters_e__Union,
};type
WINBIO_ASYNC_RESULT {.bycopy.} = object
SessionHandle: uint32
Operation: uint32
SequenceNumber: uint64
TimeStamp: int64
ApiStatus: int32
UnitId: uint32
UserData: pointer
Parameters: _Parameters_e__Unionstruct WINBIO_ASYNC_RESULT
{
uint SessionHandle;
uint Operation;
ulong SequenceNumber;
long TimeStamp;
int ApiStatus;
uint UnitId;
void* UserData;
_Parameters_e__Union Parameters;
}HSP用 定義
HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; WINBIO_ASYNC_RESULT サイズ: 40 バイト(x86)
dim st, 10 ; 4byte整数×10(構造体サイズ 40 / 4 切り上げ)
; SessionHandle : DWORD (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; Operation : DWORD (+4, 4byte) st.1 = 値 / 値 = st.1 (lpoke/lpeek も可)
; SequenceNumber : ULONGLONG (+8, 8byte) qpoke st,8,値 / qpeek(st,8) ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; TimeStamp : LONGLONG (+16, 8byte) qpoke st,16,値 / qpeek(st,16) ※IronHSPのみ。3.7/3.8は lpoke st,16,下位 : lpoke st,20,上位
; ApiStatus : HRESULT (+24, 4byte) st.6 = 値 / 値 = st.6 (lpoke/lpeek も可)
; UnitId : DWORD (+28, 4byte) st.7 = 値 / 値 = st.7 (lpoke/lpeek も可)
; UserData : void* (+32, 4byte) st.8 = 値 / 値 = st.8 (lpoke/lpeek も可)
; Parameters : _Parameters_e__Union (+36, 4byte) varptr(st)+36 を基点に操作(4byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; WINBIO_ASYNC_RESULT サイズ: 48 バイト(x64)
dim st, 12 ; 4byte整数×12(構造体サイズ 48 / 4 切り上げ)
; SessionHandle : DWORD (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; Operation : DWORD (+4, 4byte) st.1 = 値 / 値 = st.1 (lpoke/lpeek も可)
; SequenceNumber : ULONGLONG (+8, 8byte) qpoke st,8,値 / qpeek(st,8) ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; TimeStamp : LONGLONG (+16, 8byte) qpoke st,16,値 / qpeek(st,16) ※IronHSPのみ。3.7/3.8は lpoke st,16,下位 : lpoke st,20,上位
; ApiStatus : HRESULT (+24, 4byte) st.6 = 値 / 値 = st.6 (lpoke/lpeek も可)
; UnitId : DWORD (+28, 4byte) st.7 = 値 / 値 = st.7 (lpoke/lpeek も可)
; UserData : void* (+32, 8byte) qpoke st,32,値 / qpeek(st,32) ※IronHSPのみ。3.7/3.8は lpoke st,32,下位 : lpoke st,36,上位
; Parameters : _Parameters_e__Union (+40, 8byte) varptr(st)+40 を基点に操作(8byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global WINBIO_ASYNC_RESULT
#field int SessionHandle
#field int Operation
#field int64 SequenceNumber
#field int64 TimeStamp
#field int ApiStatus
#field int UnitId
#field intptr UserData
#field byte Parameters 8
#endstruct
stdim st, WINBIO_ASYNC_RESULT ; NSTRUCT 変数を確保
st->SessionHandle = 100
mes "SessionHandle=" + st->SessionHandle
; ※union フィールドは byte 列で確保(NSTRUCT は union 非対応)。必要に応じ手動でアクセス。