WinBioVerify 함수(winbio.h)

생체 인식 샘플을 캡처하고 샘플이 지정된 사용자 ID에 해당하는지 여부를 확인합니다. Windows 10 빌드 1607부터 이 함수를 모바일 이미지와 함께 사용할 수 있습니다.

구문

HRESULT WinBioVerify(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_IDENTITY          *Identity,
  [in]            WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [out, optional] WINBIO_UNIT_ID           *UnitId,
  [out, optional] BOOLEAN                  *Match,
  [out, optional] WINBIO_REJECT_DETAIL     *RejectDetail
);

매개 변수

[in] SessionHandle

열린 생체 인식 세션을 식별하는 WINBIO_SESSION_HANDLE 값입니다. WinBioOpenSession을 호출하여 동기 세션 핸들을 엽니다. WinBioAsyncOpenSession을 호출하여 비동기 세션 핸들을 엽니다.

[in] Identity

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

[in] SubFactor

생체 인식 샘플과 연결된 하위 요소를 지정하는 WINBIO_BIOMETRIC_SUBTYPE 값입니다. 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
• WINBIO_SUBTYPE_ANY

[out, optional] UnitId

확인을 수행한 생체 인식 단위를 지정하는 WINBIO_UNIT_ID 값에 대한 포인터입니다.

[out, optional] Match

캡처된 샘플이 Identity 매개 변수로 지정된 사용자 ID와 일치하는지 여부를 지정하는 부울 값에 대한 포인터입니다.

[out, optional] RejectDetail

생체 인식 샘플을 캡처하지 못한 것에 대한 추가 정보가 포함된 ULONG 값에 대한 포인터입니다. 캡처에 성공하면 이 매개 변수가 0으로 설정됩니다. 지문 캡처에 대해 정의된 값은 다음과 같습니다.

• WINBIO_FP_TOO_HIGH
• WINBIO_FP_TOO_LOW
• WINBIO_FP_TOO_LEFT
• WINBIO_FP_TOO_RIGHT
• WINBIO_FP_TOO_FAST
• WINBIO_FP_TOO_SLOW
• WINBIO_FP_POOR_QUALITY
• WINBIO_FP_TOO_SKEWED
• WINBIO_FP_TOO_SHORT
• WINBIO_FP_MERGE_FAILURE

반환 값

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

설명

생체 인식 샘플 캡처가 실패하면 UnitId 매개 변수에 캡처를 수행하려고 시도한 센서의 단위 번호가 포함됩니다.

시스템 풀을 사용하여 이 함수에 대한 호출은 애플리케이션이 창 포커스를 획득하고 사용자가 생체 인식 샘플을 제공할 때까지 차단됩니다. 따라서 애플리케이션이 포커스를 획득할 때까지 WinBioVerify 를 호출하지 않는 것이 좋습니다. 포커스를 얻는 방법은 작성 중인 애플리케이션의 유형에 따라 달라집니다. 예를 들어 GUI 애플리케이션을 만드는 경우 WM_ACTIVATE, WM_SETFOCUS 또는 기타 적절한 메시지를 캡처하는 메시지 처리기를 구현할 수 있습니다. CUI 애플리케이션을 작성하는 경우 GetConsoleWindow 를 호출하여 콘솔 창에 대한 핸들을 검색하고 해당 핸들을 SetForegroundWindow 함수에 전달하여 콘솔 창을 포그라운드로 강제 적용하고 포커스를 할당합니다. 애플리케이션이 분리된 프로세스에서 실행 중이고 창이 없거나 Windows 서비스인 경우 WinBioAcquireFocus 및 WinBioReleaseFocus 를 사용하여 수동으로 포커스를 제어합니다.

WinBioVerify를 동기적으로 사용하려면 WinBioOpenSession을 호출하여 만든 세션 핸들을 사용하여 함수를 호출합니다. 함수는 작업이 완료되거나 오류가 발생할 때까지 차단됩니다.

WinBioVerify를 비동기적으로 사용하려면 WinBioAsyncOpenSession을 호출하여 만든 세션 핸들을 사용하여 함수를 호출합니다. 프레임워크는 WINBIO_ASYNC_RESULT 구조를 할당하고 이를 사용하여 작업 성공 또는 실패에 대한 정보를 반환합니다. 작업이 성공하면 프레임워크는 중첩된 Verify 구조체에서 BOOLEAN 일치 값을 반환합니다. 작업이 실패하면 프레임워크는 Verify 구조의 WINBIO_REJECT_DETAIL 정보를 반환합니다. 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: WinBioVerifyWithCallback 함수를 사용하여 이 작업을 비동기적으로 수행할 수 있습니다. 함수는 입력 인수를 확인하고 즉시 를 반환합니다. 입력 인수가 유효하지 않으면 함수는 오류 코드를 반환합니다. 그렇지 않으면 프레임워크가 다른 스레드에서 작업을 시작합니다. 비동기 작업이 완료되거나 오류가 발생하면 프레임워크는 애플리케이션에서 구현한 PWINBIO_VERIFY_CALLBACK 함수로 결과를 보냅니다.

예제

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

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

HRESULT Verify(WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_IDENTITY identity = {0};
    BOOLEAN match = FALSE;

    // 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.
    wprintf_s(L"\n Calling WinBioVerify - Swipe finger on sensor...\n");
    hr = WinBioVerify( 
            sessionHandle, 
            &identity, 
            subFactor, 
            &unitId, 
            &match,
            &rejectDetail
            );
    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_NO_MATCH)
        {
            wprintf_s(L"\n- NO MATCH - identity verification failed.\n");
        }
        else if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n- Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
        wprintf_s(L"\n WinBioVerify failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }
    wprintf_s(L"\n Fingerprint verified:\n", unitId);


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

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

    return hr;
}

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

요구 사항

추가 정보

WinBioVerifyWithCallback