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 포함)
라이브러리	Winbio.lib
DLL	Winbio.dll

추가 정보

WinBioLocateSensor

다음을 통해 공유

WinBioLocateSensorWithCallback 함수(winbio.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

추가 정보

피드백

추가 리소스