WinBioLocateSensorWithCallback 関数 (winbio.h)

[アーティクル]
03/03/2024

ユーザーが対話的に選択した生体認証ユニットの ID 番号を非同期的に取得します。関数は呼び出し元に直ちに戻り、別のスレッドで処理し、アプリケーション定義のコールバック関数を呼び出して選択した生体認証ユニットを報告します。

重要

Windows 8以降では、この関数を使用して非同期操作を開始しなくなったことをお勧めします。代わりに、次の操作を行います。

操作が完了したときに通知を受け取る PWINBIO_ASYNC_COMPLETION_CALLBACK 関数を実装します。
WinBioAsyncOpenSession 関数を呼び出します。 CallbackRoutine パラメーターにコールバックのアドレスを渡します。 NotificationMethod パラメーターにWINBIO_ASYNC_NOTIFY_CALLBACKを渡します。非同期セッションハンドルを取得します。
非同期セッションハンドルを使用して WinBioLocateSensor を呼び出します。操作が完了すると、Windows 生体認証フレームワークは、結果を使用してWINBIO_ASYNC_RESULT 構造体を割り当てて初期化し、結果構造へのポインターを使用してコールバックを呼び出します。
コールバック実装から WinBioFree を呼び出して、WINBIO_ASYNC_RESULT 構造体の使用が完了した後に解放します。

構文

HRESULT WinBioLocateSensorWithCallback(
  [in]           WINBIO_SESSION_HANDLE          SessionHandle,
  [in]           PWINBIO_LOCATE_SENSOR_CALLBACK LocateCallback,
  [in, optional] PVOID                          LocateCallbackContext
);

パラメーター

[in] SessionHandle

開いている生体認証セッションを識別する WINBIO_SESSION_HANDLE 値。

[in] LocateCallback

センサーの場所が成功または失敗したときに WinBioLocateSensorWithCallback 関数によって呼び出されるコールバック関数のアドレス。コールバックを作成する必要があります。

[in, optional] LocateCallbackContext

LocateCallbackContext パラメーターでコールバック関数に渡されるアプリケーション定義データ構造のアドレス。この構造体には、カスタムコールバック関数が処理するように設計されている任意のデータを含めることができます。

戻り値

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

リターンコード	説明
E_HANDLE	セッションハンドルが無効です。
E_POINTER	LocateCallback パラメーターで指定されたアドレスを NULL にすることはできません。

注釈

この関数は、複数のセンサーを持つシステムで使用して、ユーザーが登録に使用するセンサーを決定できます。この関数によって識別情報は返されません。これは、ユーザーセンサーの選択を示すためにのみ提供されます。

SessionHandle パラメーターがシステムセンサープールを参照している場合、アプリケーションがウィンドウフォーカスを取得し、ユーザーが生体認証サンプルを提供するまで、コールバック関数は呼び出されません。フォーカスを取得する方法は、作成するアプリケーションの種類によって異なります。たとえば、GUI アプリケーションを作成する場合は、WM_ACTIVATE、WM_SETFOCUS、またはその他の適切なメッセージをキャプチャするメッセージハンドラーを実装できます。 CUI アプリケーションを作成する場合は、 GetConsoleWindow を呼び出してコンソールウィンドウへのハンドルを取得し、そのハンドルを SetForegroundWindow 関数に渡してコンソールウィンドウをフォアグラウンドに強制的に割り当て、フォーカスを割り当てます。アプリケーションがデタッチされたプロセスで実行されていて、ウィンドウがない場合、または Windows サービスである場合は、 WinBioAcquireFocus と WinBioReleaseFocus を使用して手動でフォーカスを制御します。

コールバックルーチンには、次のシグネチャが必要です。


VOID CALLBACK LocateCallback(
__in_opt PVOID LocateCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId
);

例

次の関数は 、WinBioLocateSensorWithCallback を呼び出して生体認証センサーを検索します。 WinBioLocateSensorWithCallback は、別のスレッドでセンサーを検索するように生体認証サブシステムを構成する非同期関数です。生体認証サブシステムからの出力は、LocateSensorCallback という名前のカスタムコールバック関数に送信されます。 Winbio.lib 静的ライブラリにリンクし、次のヘッダーファイルを含めます。

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

HRESULT LocateSensorWithCallback(BOOL bCancel)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_DEFAULT,        // Configuration and access
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            NULL,                       // Database ID
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    wprintf_s(L"\n Calling WinBioLocateSensorWithCallback.");
    hr = WinBioLocateSensorWithCallback(
                sessionHandle,          // Open biometric session
                LocateSensorCallback,   // Callback function
                NULL                    // Optional context
                );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensorWithCallback failed.");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the identification if the bCancel flag is set.
    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;
        }
    }

    // Wait for the asynchronous identification process to complete 
    // or be canceled.
    hr = WinBioWait( sessionHandle );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioWait failed. hr = 0x%x\n", hr);
    }

e_Exit:

    if (sessionHandle != NULL)
    {
       wprintf_s(L"\n Closing the session.\n");

        hr = WinBioCloseSession(sessionHandle);
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioCloseSession failed. hr = 0x%x\n", hr);
        }
        sessionHandle = NULL;
    }

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

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for 
// WinBioLocateSensorWithCallback. The function filters the response 
// from the biometric subsystem and writes a result to the console window.
// 
VOID CALLBACK LocateSensorCallback(
    __in_opt PVOID LocateCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId
    )
{
    UNREFERENCED_PARAMETER(LocateCallbackContext);

    wprintf_s(L"\n LocateSensorCallback executing.");

    // A sensor could not be located.
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n LocateSensorCallback failed.");
        wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus);
    }
    // A sensor was located.
    else
    {
        wprintf_s(L"\n Selected unit ID: %d\n", UnitId);
    }
}

要件

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

こちらもご覧ください

WinBioLocateSensor

次の方法で共有

WinBioLocateSensorWithCallback 関数 (winbio.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース