WinBioIdentifyWithCallback 함수(winbio.h)

아티클
08/27/2023

생체 인식 샘플을 비동기적으로 캡처하고 기존 생체 인식 템플릿과 일치하는지 여부를 결정합니다. 함수는 호출자에게 즉시 반환되고, 별도의 스레드에서 캡처 및 식별을 수행하고, 애플리케이션 정의 콜백 함수를 호출하여 작업 상태 업데이트합니다.

중요

Windows 8부터는 더 이상 이 함수를 사용하여 비동기 작업을 시작하지 않는 것이 좋습니다. 대신 다음을 수행합니다.

PWINBIO_ASYNC_COMPLETION_CALLBACK 함수를 구현하여 작업이 완료될 때 알림을 받습니다.
WinBioAsyncOpenSession 함수를 호출합니다. 콜백의 주소를 CallbackRoutine 매개 변수에 전달합니다. NotificationMethod 매개 변수에 WINBIO_ASYNC_NOTIFY_CALLBACK 전달합니다. 비동기 세션 핸들을 검색합니다.
비동기 세션 핸들을 사용하여 WinBioIdentify를 호출합니다. 작업이 완료되면 Windows 생체 인식 프레임워크는 결과를 사용하여 WINBIO_ASYNC_RESULT 구조를 할당 및 초기화하고 결과 구조에 대한 포인터를 사용하여 콜백을 호출합니다.
콜백 구현에서 WinBioFree 를 호출하여 사용이 완료된 후 WINBIO_ASYNC_RESULT 구조를 해제합니다.

구문

HRESULT WinBioIdentifyWithCallback(
  [in]           WINBIO_SESSION_HANDLE     SessionHandle,
  [in]           PWINBIO_IDENTIFY_CALLBACK IdentifyCallback,
  [in, optional] PVOID                     IdentifyCallbackContext
);

매개 변수

[in] SessionHandle

열린 생체 인식 세션을 식별하는 WINBIO_SESSION_HANDLE 값입니다.

[in] IdentifyCallback

식별이 성공하거나 실패할 때 WinBioIdentifyWithCallback 함수에서 호출할 콜백 함수의 주소입니다. 콜백을 만들어야 합니다.

[in, optional] IdentifyCallbackContext

IdentifyCallbackContext 매개 변수의 콜백 함수에 전달되는 애플리케이션 정의 데이터 구조에 대한 포인터입니다. 이 구조체는 사용자 지정 콜백 함수가 처리하도록 설계된 모든 데이터를 포함할 수 있습니다.

반환 값

함수가 성공하면 S_OK를 반환합니다. 함수가 실패하면 오류를 나타내는 HRESULT 값을 반환합니다. 가능한 값에는 다음 표에 있는 값이 포함되지만, 이에 국한되는 것은 아닙니다. 일반적인 오류 코드 목록은 일반 HRESULT 값을 참조하세요.

반환 코드	설명
E_HANDLE	세션 핸들이 잘못되었습니다.
E_POINTER	SessionHandle 및 IdentifyCallback 매개 변수는 NULL일 수 없습니다.

설명

콜백 루틴에는 다음 서명이 있어야 합니다.

VOID CALLBACK IdentifyCallback(
__in_opt PVOID IdentifyCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in WINBIO_IDENTITY *Identity,
__in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
__in WINBIO_REJECT_DETAIL RejectDetail
);

예제

다음 코드 예제에서는 WinBioIdentifyWithCallback 을 호출하여 생체 인식 검사에서 사용자를 식별합니다. WinBioIdentifyWithCallback 은 다른 스레드에서 생체 인식 입력을 처리하도록 생체 인식 하위 시스템을 구성하는 비동기 함수입니다. 생체 인식 하위 시스템의 출력은 IdentifyCallback이라는 사용자 지정 콜백 함수로 전송됩니다. Winbio.lib 정적 라이브러리에 연결하고 다음 헤더 파일을 포함합니다.

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

HRESULT IdentifyWithCallback(BOOL bCancel)
{
    // Declare variables.
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;

    // 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 
            WINBIO_DB_DEFAULT,          // Database ID 
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Call WinBioIdentifyWithCallback. The method is asynchronous
    // and returns immediately.
    wprintf_s(L"\n Calling WinBioIdentifyWithCallback");
    wprintf_s(L"\n Swipe the sensor ...\n");
    hr = WinBioIdentifyWithCallback( 
            sessionHandle,              // Open biometric session
            IdentifyCallback,           // Callback function
            NULL                        // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioIdentifyWithCallback failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Cancel user 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 WinBioIdentifyWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
// 
VOID CALLBACK IdentifyCallback(
    __in_opt PVOID IdentifyCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in WINBIO_IDENTITY *Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(IdentifyCallbackContext);
    UNREFERENCED_PARAMETER(Identity);

    wprintf_s(L"\n IdentifyCallback executing");
    wprintf_s(L"\n Swipe processed for unit ID %d\n", UnitId);

    // The attempt to process the fingerprint failed.
    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_UNKNOWN_ID)
        {
            wprintf_s(L"\n Unknown identity.\n");
        }
        else if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
        }
        else
        {
            wprintf_s(L"IdentifyCallback failed.");
            wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus); 
        }
    }
    // Processing succeeded and the finger swiped is written
    // to the console window.
    else
    {
        wprintf_s(L"\n The following finger was used:");
        switch (SubFactor)
        {
            case WINBIO_SUBTYPE_NO_INFORMATION:
                wprintf_s(L"\n No information\n");
                break;
            case WINBIO_ANSI_381_POS_RH_THUMB:
                wprintf_s(L"\n RH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_RH_INDEX_FINGER:
                wprintf_s(L"\n RH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER:
                wprintf_s(L"\n RH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_RING_FINGER:
                wprintf_s(L"\n RH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_LITTLE_FINGER:
                wprintf_s(L"\n RH little finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_THUMB:
                wprintf_s(L"\n LH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_LH_INDEX_FINGER:
                wprintf_s(L"\n LH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER:
                wprintf_s(L"\n LH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_RING_FINGER:
                wprintf_s(L"\n LH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_LITTLE_FINGER:
                wprintf_s(L"\n LH little finger\n");
                break;
            case WINBIO_SUBTYPE_ANY:
                wprintf_s(L"\n Any finger\n");
                break;
            default:
                break;
        }
    }
}

요구 사항


지원되는 최소 클라이언트	Windows 7 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 R2 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	winbio.h(Winbio.h 포함)
라이브러리	Winbio.lib
DLL	Winbio.dll

추가 정보

WinBioIdentify

다음을 통해 공유

WinBioIdentifyWithCallback 함수(winbio.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

추가 정보

피드백

추가 리소스