WinBioVerifyWithCallback 함수(winbio.h)

아티클
08/27/2023

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

중요

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

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

구문

HRESULT WinBioVerifyWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_IDENTITY          *Identity,
  [in]           WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [in]           PWINBIO_VERIFY_CALLBACK  VerifyCallback,
  [in, optional] PVOID                    VerifyCallbackContext
);

매개 변수

[in] SessionHandle

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

[in] Identity

생체 인식 샘플을 제공하는 사용자의 GUID 또는 SID를 포함하는 WINBIO_IDENTITY 구조체에 대한 포인터입니다.

[in] SubFactor

생체 인식 샘플과 연결된 하위 요소를 지정하는 WINBIO_BIOMETRIC_SUBTYPE 값입니다. 자세한 내용은 설명 섹션을 참조하세요.

[in] VerifyCallback

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

[in, optional] VerifyCallbackContext

콜백 함수의 VerifyCallbackContext 매개 변수에 반환되는 선택적 애플리케이션 정의 구조체입니다. 이 구조체는 사용자 지정 콜백 함수가 처리하도록 설계된 모든 데이터를 포함할 수 있습니다.

반환 값

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

반환 코드	설명
E_HANDLE	세션 핸들이 잘못되었습니다.
E_INVALIDARG	SubFactor 인수가 잘못되었습니다.
E_POINTER	Identity 및 VerifyCallback 매개 변수로 지정된 포인터는 NULL일 수 없습니다.

설명

SubFactor 매개 변수는 생체 인식 샘플과 연결된 하위 요소를 지정합니다. WBF(Windows 생체 인식 프레임워크)는 현재 지문 캡처만 지원하며 다음 상수를 사용하여 하위 형식 정보를 나타냅니다.

WINBIO_ANSI_381_POS_RH_THUMB
WINBIO_ANSI_381_POS_RH_INDEX_FINGER
WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
WINBIO_ANSI_381_POS_RH_RING_FINGER
WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
WINBIO_ANSI_381_POS_LH_THUMB
WINBIO_ANSI_381_POS_LH_INDEX_FINGER
WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
WINBIO_ANSI_381_POS_LH_RING_FINGER
WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
WINBIO_ANSI_381_POS_RH_FOUR_FINGERS
WINBIO_ANSI_381_POS_LH_FOUR_FINGERS

콜백 루틴은 호출 프로세스에서 임의의 스레드의 컨텍스트에서 실행됩니다. 호출자는 콜백과 애플리케이션의 다른 부분 간에 공유될 수 있는 모든 메모리에 대한 액세스를 동기화해야 합니다.

WinBioVerifyWithCallback 함수는 즉시 반환되고 호출자에게 S_OK 전달합니다. 캡처 및 확인 프로세스의 상태 확인하려면 콜백 함수에서 OperationStatus 매개 변수를 검사해야 합니다.

WinBioCancel 함수를 호출하여 보류 중인 콜백 작업을 취소할 수 있습니다. 세션을 닫으면 해당 세션에 대한 콜백도 암시적으로 취소됩니다.

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


VOID CALLBACK VerifyCallback(
__in_opt PVOID VerifyCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in BOOLEAN Match,
__in WINBIO_REJECT_DETAIL RejectDetail
);

예제

다음 함수는 WinBioVerifyWithCallback 을 호출하여 생체 인식 샘플이 현재 사용자의 로그온 ID와 일치하는지 여부를 비동기적으로 확인합니다. 콜백 루틴 VerifyCallback 및 도우미 함수인 GetCurrentUserIdentity도 포함됩니다. Winbio.lib 정적 라이브러리에 연결하고 다음 헤더 파일을 포함합니다.

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

HRESULT VerifyWithCallback(BOOL bCancel, WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    // Declare variables.
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_IDENTITY identity = {0};

    // Find the identity of the user.
    hr = GetCurrentUserIdentity( &identity );
    if (FAILED(hr))
    {
        wprintf_s(L"\n User identity not found. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // 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;
    }

    // Verify a biometric sample asynchronously.
    wprintf_s(L"\n Calling WinBioVerifyWithCallback.\n");
    hr = WinBioVerifyWithCallback(
            sessionHandle,              // Open session handle
            &identity,                  // User SID or GUID
            subFactor,                  // Sample sub-factor
            VerifyCallback,             // Callback function
            NULL                        // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioVerifyWithCallback failed. 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)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

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

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioVerifyWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
// 
VOID CALLBACK VerifyCallback(
  __in_opt PVOID VerifyCallbackContext,
  __in HRESULT OperationStatus,
  __in WINBIO_UNIT_ID UnitId,
  __in BOOLEAN Match,
  __in WINBIO_REJECT_DETAIL RejectDetail
  )
{
    UNREFERENCED_PARAMETER(VerifyCallbackContext);
    UNREFERENCED_PARAMETER(Match);

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

    // The identity could not be verified.
    if (FAILED(OperationStatus))
    {
        wprintf_s(L"\n Verification failed for the following reason:");
        if (OperationStatus == WINBIO_E_NO_MATCH)
        {
            wprintf_s(L"\n No match.\n");
        }
        else if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture.\n ");
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
        }
        else
        {
            wprintf_s(L"VerifyCallback failed.");
            wprintf_s(L"OperationStatus = 0x%x\n", OperationStatus); 
        }
        goto e_Exit;
    }

    // The user identity was verified.
    wprintf_s(L"\n Fingerprint verified:\n");

e_Exit:
    return;
}

//------------------------------------------------------------------------
// The following function retrieves the identity of the current user.
// This is a helper function and is not part of the Windows Biometric
// Framework API.
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
    // Declare variables.
    HRESULT hr = S_OK;
    HANDLE tokenHandle = NULL;
    DWORD bytesReturned = 0;
    struct{
        TOKEN_USER tokenUser;
        BYTE buffer[SECURITY_MAX_SID_SIZE];
    } tokenInfoBuffer;

    // Zero the input identity and specify the type.
    ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
    Identity->Type = WINBIO_ID_TYPE_NULL;

    // Open the access token associated with the
    // current process
    if (!OpenProcessToken(
            GetCurrentProcess(),            // Process handle
            TOKEN_READ,                     // Read access only
            &tokenHandle))                  // Access token handle
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot open token handle: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // Zero the tokenInfoBuffer structure.
    ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));

    // Retrieve information about the access token. In this case,
    // retrieve a SID.
    if (!GetTokenInformation(
            tokenHandle,                    // Access token handle
            TokenUser,                      // User for the token
            &tokenInfoBuffer.tokenUser,     // Buffer to fill
            sizeof(tokenInfoBuffer),        // Size of the buffer
            &bytesReturned))                // Size needed
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot query token information: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // Copy the SID from the tokenInfoBuffer structure to the
    // WINBIO_IDENTITY structure. 
    CopySid(
        SECURITY_MAX_SID_SIZE,
        Identity->Value.AccountSid.Data,
        tokenInfoBuffer.tokenUser.User.Sid
        );

    // Specify the size of the SID and assign WINBIO_ID_TYPE_SID
    // to the type member of the WINBIO_IDENTITY structure.
    Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
    Identity->Type = WINBIO_ID_TYPE_SID;

e_Exit:

    if (tokenHandle != NULL)
    {
        CloseHandle(tokenHandle);
    }

    return hr;
}

요구 사항

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

추가 정보

WinBioCancel

WinBioVerify

다음을 통해 공유

WinBioVerifyWithCallback 함수(winbio.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

추가 정보

피드백

추가 리소스