WinBioLocateSensor 関数 (winbio.h)

ユーザーが対話形式で選択した生体認証ユニットの ID 番号を取得します。

構文

HRESULT WinBioLocateSensor(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [out, optional] WINBIO_UNIT_ID        *UnitId
);

パラメーター

[in] SessionHandle

開いている生体認証セッションを識別する WINBIO_SESSION_HANDLE 値。 WinBioOpenSession を呼び出して、同期セッション ハンドルを開きます。 WinBioAsyncOpenSession を呼び出して非同期セッション ハンドルを開きます。

[out, optional] UnitId

生体認証ユニットを指定する ULONG 値へのポインター。

戻り値

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

解説

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

システム プールを使用してこの関数を呼び出すと、アプリケーションがウィンドウ フォーカスを取得し、ユーザーが生体認証サンプルを提供するまでブロックされます。 そのため、フォーカスが取得されるまで、アプリケーションで 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 ポインターを返します。

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;

    // 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 WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate the sensor.
    wprintf_s(L"\n Tap the sensor once...\n");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Sensor located successfully. ");
    wprintf_s(L"\n Unit ID = %d \n", unitId);

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

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

    return hr;
}

要件

関連項目

WinBioLocateSensorWithCallback