WinBioIdentify 함수(winbio.h)

아티클
08/27/2023

생체 인식 샘플을 캡처하고 기존 생체 인식 템플릿과 일치하는지 여부를 결정합니다. Windows 10 빌드 1607부터 이 함수를 모바일 이미지와 함께 사용할 수 있습니다.

구문

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

매개 변수

[in] SessionHandle

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

[out, optional] UnitId

식별을 수행하는 데 사용되는 생체 인식 단위를 지정하는 ULONG 값에 대한 포인터입니다.

[out, optional] Identity

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

[out, optional] SubFactor

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

[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 값을 참조하세요.

반환 코드	설명
E_HANDLE	세션 핸들이 잘못되었습니다.
E_POINTER	UnitId, Identity, SubFactor 또는 RejectDetail 매개 변수로 지정된 포인터는 NULL일 수 없습니다.
WINBIO_E_BAD_CAPTURE	샘플을 캡처할 수 없습니다. 자세한 내용은 RejectDetail 값을 사용합니다.
WINBIO_E_ENROLLMENT_IN_PROGRESS	생체 인식 단위가 현재 등록 트랜잭션에 사용 중이므로 작업을 완료할 수 없습니다(시스템 풀에만 해당).
WINBIO_E_UNKNOWN_ID	생체 인식 샘플은 데이터베이스에 저장된 샘플과 일치하지 않습니다.

설명

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

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

WinBioIdentify를 비동기적으로 사용하려면 WinBioAsyncOpenSession을 호출하여 만든 세션 핸들을 사용하여 함수를 호출합니다. 프레임워크는 WINBIO_ASYNC_RESULT 구조를 할당하고 이를 사용하여 작업 성공 또는 실패에 대한 정보를 반환합니다. 작업이 성공하면 프레임워크는 WINBIO_IDENTITY 반환하고 중첩된 식별 구조에서 정보를 WINBIO_BIOMETRIC_SUBTYPE. 작업이 실패하면 프레임워크는 식별 구조에 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 포인터를 반환합니다.

메모리 누수 방지를 위해 WinBioFree 를 호출하여 WINBIO_ASYNC_RESULT 구조를 해제해야 합니다.

Windows 7: WinBioIdentifyWithCallback 함수를 사용하여 이 작업을 비동기적으로 수행할 수 있습니다. 함수는 입력 인수를 확인하고 즉시 반환합니다. 입력 인수가 유효하지 않으면 함수는 오류 코드를 반환합니다. 그렇지 않으면 프레임워크가 다른 스레드에서 작업을 시작합니다. 비동기 작업이 완료되거나 오류가 발생하면 프레임워크는 애플리케이션에서 구현한 PWINBIO_IDENTIFY_CALLBACK 함수로 결과를 보냅니다.

예제

다음 함수는 WinBioEnumEnrollments 를 호출하여 템플릿에 등록된 생체 인식 하위 요소를 열거하고 WinBioIdentify 를 호출하여 사용자를 식별하는 WINBIO_IDENTITY 개체를 검색합니다. Winbio.lib 정적 라이브러리에 연결하고 다음 헤더 파일을 포함합니다.

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

HRESULT EnumEnrollments( )
{
    // Declare variables.
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    PWINBIO_BIOMETRIC_SUBTYPE subFactorArray = NULL;
    WINBIO_BIOMETRIC_SUBTYPE SubFactor = 0;
    SIZE_T subFactorCount = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_BIOMETRIC_SUBTYPE subFactor = WINBIO_SUBTYPE_NO_INFORMATION;

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

    // Locate the biometric sensor and retrieve a WINBIO_IDENTITY object.
    wprintf_s(L"\n Calling WinBioIdentify - Swipe finger on sensor...\n");
    hr = WinBioIdentify( 
            sessionHandle,              // Session handle
            &unitId,                    // Biometric unit ID
            &identity,                  // User SID
            &subFactor,                 // Finger sub factor
            &rejectDetail               // Rejection information
            );
    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_UNKNOWN_ID)
        {
            wprintf_s(L"\n Unknown identity.\n");
        }
        else if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    // Retrieve the biometric sub-factors for the template.
    hr = WinBioEnumEnrollments( 
            sessionHandle,              // Session handle
            unitId,                     // Biometric unit ID
            &identity,                  // Template ID
            &subFactorArray,            // Subfactors
            &subFactorCount             // Count of subfactors
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnumEnrollments failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Print the sub-factor(s) to the console.
    wprintf_s(L"\n Enrollments for this user on Unit ID %d:", unitId);
    for (SIZE_T index = 0; index < subFactorCount; ++index)
    {
        SubFactor = subFactorArray[index];
        switch (SubFactor)
        {
            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;
            default:
                wprintf_s(L"\n   The sub-factor is not correct\n");
                break;
        }
 
    }

e_Exit:
    if (subFactorArray!= NULL)
    {
        WinBioFree(subFactorArray);
        subFactorArray = NULL;
    }

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

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

    return hr;
}

요구 사항

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

추가 정보

WinBioIdentifyWithCallback

다음을 통해 공유

WinBioIdentify 함수(winbio.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

추가 정보

피드백

추가 리소스