winBioLocateSensorWithCallback 函式 (winbio.h)

發行項
03/09/2024

以異步方式擷取使用者以互動方式選取生物特徵辨識單位的標識碼。函式會立即傳回給呼叫端、在個別線程上處理，並藉由呼叫應用程式定義的回呼函式來報告選取的生物特徵辨識單位。

重要

建議您從 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

傳遞至 Callback 函式的 Application 定義數據結構位址 ，其 LocateCallbackContext 參數中。此結構可以包含自定義回呼函式設計用來處理的任何數據。

傳回值

如果函式成功，它會 傳回S_OK。如果函式失敗，它會傳回 指出錯誤的 HRESULT 值。可能的值包括 (但不限於) 下表中的這些值。如需常見錯誤碼的清單，請參閱一般 HRESULT 值。

傳回碼	Description
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)
程式庫	Winbio.lib
Dll	Winbio.dll

另請參閱

WinBioLocateSensor

共用方式為

winBioLocateSensorWithCallback 函式 (winbio.h)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源