ホーム › Devices.BiometricFramework › WinBioCaptureSample

WinBioCaptureSample

関数

指定用途で生体サンプルを採取して取得する。

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

シグネチャ

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

HRESULT WinBioCaptureSample(
    DWORD SessionHandle,
    BYTE Purpose,
    BYTE Flags,
    DWORD* UnitId,   // optional
    WINBIO_BIR** Sample,
    UINT_PTR* SampleSize,   // optional
    DWORD* RejectDetail   // optional
);

パラメーター

名前	型	方向	説明
SessionHandle	DWORD	in	オープンされている生体認証セッションを識別する WINBIO_SESSION_HANDLE 値。同期セッションハンドルは WinBioOpenSession を呼び出して開きます。非同期セッションハンドルは WinBioAsyncOpenSession を呼び出して開きます。
Purpose	BYTE	in	サンプルの使用目的を指定する WINBIO_BIR_PURPOSE ビットマスク。次の値のビットごとの OR を指定できます。 WINBIO_PURPOSE_VERIFY WINBIO_PURPOSE_IDENTIFY WINBIO_PURPOSE_ENROLL WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION
Flags	BYTE	in	キャプチャしたサンプルに適用する処理の種類を指定する値。次のセキュリティおよび処理レベルのフラグのビットごとの OR を指定できます。 WINBIO_DATA_FLAG_PRIVACY サンプルを暗号化します。 WINBIO_DATA_FLAG_INTEGRITY サンプルに署名するか、メッセージ認証コード (MAC) を使用して保護します。 WINBIO_DATA_FLAG_SIGNED このフラグと WINBIO_DATA_FLAG_INTEGRITY フラグの両方が設定されている場合、サンプルに署名します。このフラグが設定されておらず、WINBIO_DATA_FLAG_INTEGRITY フラグだけが設定されている場合は、MAC を計算します。 WINBIO_DATA_FLAG_RAW センサーによってキャプチャされたそのままの形でサンプルを返します。 WINBIO_DATA_FLAG_INTERMEDIATE クリーニングとフィルター処理が行われた後のサンプルを返します。 WINBIO_DATA_FLAG_PROCESSED Purpose パラメーターで指定された目的に使用できる状態になった後のサンプルを返します。
UnitId	DWORD*	outoptional	サンプルを生成した生体認証ユニットの ID を格納する WINBIO_UNIT_ID 値へのポインター。
Sample	WINBIO_BIR**	out	サンプルを格納する WINBIO_BIR 構造体へのポインターを受け取る変数のアドレス。構造体の使用が終わったら、そのポインターを WinBioFree に渡し、サンプル用に割り当てられたメモリを解放する必要があります。
SampleSize	UINT_PTR*	outoptional	Sample パラメーターで返される WINBIO_BIR 構造体のサイズ (バイト単位) を格納する SIZE_T 値へのポインター。
RejectDetail	DWORD*	outoptional	生体認証サンプルのキャプチャに失敗した原因に関する追加情報を格納する WINBIO_REJECT_DETAIL 値へのポインター。キャプチャが成功した場合、このパラメーターは 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

戻り値の型: HRESULT

公式ドキュメント

生体認証サンプルをキャプチャし、生データまたは処理済みデータで生体情報レコード (BIR) を埋めます。

戻り値

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

戻り値	説明
E_ACCESSDENIED	呼び出し元に生データのサンプルをキャプチャする権限がないか、セッションが WINBIO_FLAG_RAW フラグを使用して開かれていません。
E_HANDLE	セッションハンドルが無効です。
E_NOTIMPL	生体認証ユニットが要求された操作をサポートしていません。
E_POINTER	UnitId、Sample、SampleSize、RejectDetail の各ポインターを NULL にすることはできません。
WINBIO_E_ENROLLMENT_IN_PROGRESS	生体認証ユニットが現在、登録トランザクションで使用されているため、操作を完了できませんでした (システムプールのみ)。
WINBIO_E_INVALID_OPERATION	センサープールにセキュアセンサーが存在するため、操作を完了できませんでした。

解説(Remarks)

この関数を正常に呼び出すには、WinBioOpenSession 関数または WinBioAsyncOpenSession 関数の Flags パラメーターに WINBIO_FLAG_RAW を指定してセッションハンドルを開く必要があります。現在のところ、必要な特権を持つのは Administrators アカウントおよび Local System アカウントで実行されているアプリケーションだけです。

Purpose パラメーターと Flags パラメーターの有効な組み合わせは、使用する生体認証ユニットの機能によって異なります。有効な Purpose 値と Flags 値のどの組み合わせがサポートされ、それらがキャプチャされるデータにどのような影響を与えるかについては、ベンダーのセンサードキュメントを参照してください。サンプルの使用が終わったら、アプリケーションは WinBioFree を呼び出し、WinBioCaptureSample 関数によってサンプル用に割り当てられたメモリを解放する必要があります。

WinBioCaptureSample を同期的に使用するには、WinBioOpenSession を呼び出して作成したセッションハンドルを指定して、この関数を呼び出します。関数は、サンプルがキャプチャされるか、エラーが発生するまでブロックします。システムプールを使用する WinBioCaptureSample の呼び出しは、呼び出し元アプリケーションがウィンドウフォーカスを得て、ユーザーがプール内のいずれかのセンサーにサンプルを提供するまでブロックします。ユーザーが選択したセンサーが既に登録トランザクションで使用されている場合、関数は失敗し、WINBIO_E_ENROLLMENT_IN_PROGRESS を返します。

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

例

次の関数は、WinBioCaptureSample を呼び出してユーザーから生体認証サンプルをキャプチャします。Winbio.lib 静的ライブラリにリンクし、次のヘッダーファイルをインクルードしてください。

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

HRESULT CaptureSample()
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    PWINBIO_BIR sample = NULL;
    SIZE_T sampleSize = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Access: Capture raw data
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            WINBIO_DB_DEFAULT,          // Default database
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture a biometric sample.
    wprintf_s(L"\n Calling WinBioCaptureSample - Swipe sensor...\n");
    hr = WinBioCaptureSample(
            sessionHandle,
            WINBIO_NO_PURPOSE_AVAILABLE,
            WINBIO_DATA_FLAG_RAW,
            &unitId,
            &sample,
            &sampleSize,
            &rejectDetail
            );
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioCaptureSample failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    wprintf_s(L"\n Captured %d bytes.\n", sampleSize);


e_Exit:
    if (sample != NULL)
    {
        WinBioFree(sample);
        sample = NULL;
    }

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

    wprintf_s(L"\n Press 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 WinBioCaptureSample(
    DWORD SessionHandle,
    BYTE Purpose,
    BYTE Flags,
    DWORD* UnitId,   // optional
    WINBIO_BIR** Sample,
    UINT_PTR* SampleSize,   // optional
    DWORD* RejectDetail   // optional
);

[DllImport("winbio.dll", ExactSpelling = true)]
static extern int WinBioCaptureSample(
    uint SessionHandle,   // DWORD
    byte Purpose,   // BYTE
    byte Flags,   // BYTE
    IntPtr UnitId,   // DWORD* optional, out
    IntPtr Sample,   // WINBIO_BIR** out
    IntPtr SampleSize,   // UINT_PTR* optional, out
    IntPtr RejectDetail   // DWORD* optional, out
);

<DllImport("winbio.dll", ExactSpelling:=True)>
Public Shared Function WinBioCaptureSample(
    SessionHandle As UInteger,   ' DWORD
    Purpose As Byte,   ' BYTE
    Flags As Byte,   ' BYTE
    UnitId As IntPtr,   ' DWORD* optional, out
    Sample As IntPtr,   ' WINBIO_BIR** out
    SampleSize As IntPtr,   ' UINT_PTR* optional, out
    RejectDetail As IntPtr   ' DWORD* optional, out
) As Integer
End Function

' SessionHandle : DWORD
' Purpose : BYTE
' Flags : BYTE
' UnitId : DWORD* optional, out
' Sample : WINBIO_BIR** out
' SampleSize : UINT_PTR* optional, out
' RejectDetail : DWORD* optional, out
Declare PtrSafe Function WinBioCaptureSample Lib "winbio" ( _
    ByVal SessionHandle As Long, _
    ByVal Purpose As Byte, _
    ByVal Flags As Byte, _
    ByVal UnitId As LongPtr, _
    ByVal Sample As LongPtr, _
    ByVal SampleSize As LongPtr, _
    ByVal RejectDetail As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WinBioCaptureSample = ctypes.windll.winbio.WinBioCaptureSample
WinBioCaptureSample.restype = ctypes.c_int
WinBioCaptureSample.argtypes = [
    wintypes.DWORD,  # SessionHandle : DWORD
    ctypes.c_ubyte,  # Purpose : BYTE
    ctypes.c_ubyte,  # Flags : BYTE
    ctypes.POINTER(wintypes.DWORD),  # UnitId : DWORD* optional, out
    ctypes.c_void_p,  # Sample : WINBIO_BIR** out
    ctypes.POINTER(ctypes.c_size_t),  # SampleSize : UINT_PTR* optional, out
    ctypes.POINTER(wintypes.DWORD),  # RejectDetail : DWORD* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('winbio.dll')
WinBioCaptureSample = Fiddle::Function.new(
  lib['WinBioCaptureSample'],
  [
    -Fiddle::TYPE_INT,  # SessionHandle : DWORD
    -Fiddle::TYPE_CHAR,  # Purpose : BYTE
    -Fiddle::TYPE_CHAR,  # Flags : BYTE
    Fiddle::TYPE_VOIDP,  # UnitId : DWORD* optional, out
    Fiddle::TYPE_VOIDP,  # Sample : WINBIO_BIR** out
    Fiddle::TYPE_VOIDP,  # SampleSize : UINT_PTR* optional, out
    Fiddle::TYPE_VOIDP,  # RejectDetail : DWORD* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "winbio")]
extern "system" {
    fn WinBioCaptureSample(
        SessionHandle: u32,  // DWORD
        Purpose: u8,  // BYTE
        Flags: u8,  // BYTE
        UnitId: *mut u32,  // DWORD* optional, out
        Sample: *mut *mut WINBIO_BIR,  // WINBIO_BIR** out
        SampleSize: *mut usize,  // UINT_PTR* optional, out
        RejectDetail: *mut u32  // DWORD* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("winbio.dll")]
public static extern int WinBioCaptureSample(uint SessionHandle, byte Purpose, byte Flags, IntPtr UnitId, IntPtr Sample, IntPtr SampleSize, IntPtr RejectDetail);
"@
$api = Add-Type -MemberDefinition $sig -Name 'winbio_WinBioCaptureSample' -Namespace Win32 -PassThru
# $api::WinBioCaptureSample(SessionHandle, Purpose, Flags, UnitId, Sample, SampleSize, RejectDetail)

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

出力引数:

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