WinBioCaptureSample 함수(winbio.h)

생체 인식 샘플을 캡처하고 원시 또는 처리된 데이터로 BIR(생체 인식 정보 레코드)를 채웁니다.

구문

HRESULT WinBioCaptureSample(
  [in]            WINBIO_SESSION_HANDLE SessionHandle,
  [in]            WINBIO_BIR_PURPOSE    Purpose,
  [in]            WINBIO_BIR_DATA_FLAGS Flags,
  [out, optional] WINBIO_UNIT_ID        *UnitId,
                  PWINBIO_BIR           *Sample,
  [out, optional] SIZE_T                *SampleSize,
  [out, optional] WINBIO_REJECT_DETAIL  *RejectDetail
);

매개 변수

[in] SessionHandle

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

[in] Purpose

샘플의 의도된 사용을 지정하는 WINBIO_BIR_PURPOSE 비트 마스크입니다. 이 값은 다음 값의 비트 OR 일 수 있습니다.

• WINBIO_PURPOSE_VERIFY
• WINBIO_PURPOSE_IDENTIFY
• WINBIO_PURPOSE_ENROLL
• WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
• WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[in] Flags

캡처된 샘플에 적용할 처리 유형을 지정하는 값입니다. 다음 보안 및 처리 수준 플래그 중 비트 OR 일 수 있습니다.

• WINBIO_DATA_FLAG_PRIVACY

샘플을 암호화합니다.

• WINBIO_DATA_FLAG_INTEGRITY

MAC(메시지 인증 코드)를 사용하여 샘플에 서명하거나 보호합니다.

• WINBIO_DATA_FLAG_SIGNED

이 플래그와 WINBIO_DATA_FLAG_INTEGRITY 플래그가 설정된 경우 샘플에 서명합니다. 이 플래그가 설정되지 않았지만 WINBIO_DATA_FLAG_INTEGRITY 플래그가 설정된 경우 MAC을 계산합니다.

• WINBIO_DATA_FLAG_RAW

센서에서 캡처한 것과 정확하게 샘플을 반환합니다.

• WINBIO_DATA_FLAG_INTERMEDIATE

샘플을 정리하고 필터링한 후 반환합니다.

• WINBIO_DATA_FLAG_PROCESSED

Purpose 매개 변수에 지정된 용도로 사용할 준비가 된 후 샘플을 반환합니다.

[out, optional] UnitId

샘플을 생성한 생체 인식 단위의 ID를 포함하는 WINBIO_UNIT_ID 값에 대한 포인터입니다.

Sample

샘플을 포함하는 WINBIO_BIR 구조체에 대한 포인터를 수신하는 변수의 주소입니다. 구조체 사용을 마쳤으면 포인터를 WinBioFree 에 전달하여 샘플에 할당된 메모리를 해제해야 합니다.

[out, optional] SampleSize

Sample 매개 변수에 반환된 WINBIO_BIR 구조체의 크기(바이트)를 포함하는 SIZE_T 값에 대한 포인터입니다.

[out, optional] RejectDetail

생체 인식 샘플을 캡처하지 못한 것에 대한 추가 정보가 포함된 WINBIO_REJECT_DETAIL 값에 대한 포인터입니다. 캡처에 성공하면 이 매개 변수가 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 값을 참조하세요.

설명

이 함수를 성공적으로 호출하려면 WinBioOpenSession 또는 WinBioAsyncOpenSession 함수의 Flags 매개 변수에 WINBIO_FLAG_RAW 지정하여 세션 핸들을 열어야 합니다. 현재 관리자 및 로컬 시스템 계정으로 실행되는 애플리케이션에만 필요한 권한이 있습니다.

용도 및 플래그 매개 변수의 유효한 조합은 사용 중인 생체 인식 단위의 기능에 따라 달라집니다. 공급업체의 센서 설명서를 참조하여 지원되는 유효한 목적 및 플래그 값의 조합과 캡처된 데이터에 미치는 영향을 확인합니다. 샘플 사용을 완료한 후 애플리케이션은 WinBioFree 를 호출하여 WinBioCaptureSample 함수에 의해 할당된 메모리를 해제해야 합니다.

WinBioCaptureSample을 동기적으로 사용하려면 WinBioOpenSession을 호출하여 만든 세션 핸들을 사용하여 함수를 호출합니다. 함수는 샘플이 캡처되거나 오류가 발생할 때까지 차단됩니다. 시스템 풀을 사용하여 WinBioCaptureSample 에 대한 호출은 호출 애플리케이션에 창 포커스가 있고 사용자가 풀의 센서 중 하나에 샘플을 제공하기 전까지 차단됩니다. 사용자가 선택한 센서가 등록 트랜잭션에 이미 사용 중인 경우 함수가 실패하고 WINBIO_E_ENROLLMENT_IN_PROGRESS 반환합니다.

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

예제

다음 함수는 WinBioCaptureSample 을 호출하여 사용자의 생체 인식 샘플을 캡처합니다. Winbio.lib 정적 라이브러리에 연결하고 다음 헤더 파일을 포함합니다.

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

HRESULT CaptureSample()
{
    HRESULT hr = S_OK;
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    PWINBIO_BIR sample = NULL;
    SIZE_T sampleSize = 0;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_RAW,            // Access: Capture raw data
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            WINBIO_DB_DEFAULT,          // Default database
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture a biometric sample.
    wprintf_s(L"\n Calling WinBioCaptureSample - Swipe sensor...\n");
    hr = WinBioCaptureSample(
            sessionHandle,
            WINBIO_NO_PURPOSE_AVAILABLE,
            WINBIO_DATA_FLAG_RAW,
            &unitId,
            &sample,
            &sampleSize,
            &rejectDetail
            );
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioCaptureSample failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    wprintf_s(L"\n Captured %d bytes.\n", sampleSize);


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

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

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

    return hr;
}

요구 사항

추가 정보

WinBioCaptureSampleWithCallback