WinBioCaptureSampleWithCallback 함수(winbio.h)

아티클
12/08/2023

생체 인식 샘플을 비동기적으로 캡처하고 원시 또는 처리된 데이터를 BIR(생체 인식 정보 레코드)에서 반환합니다. 함수는 호출자에게 즉시 반환하고, 별도의 스레드에서 샘플을 캡처하고, 애플리케이션 정의 콜백 함수를 호출하여 작업 상태 업데이트합니다.

중요

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

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

구문

HRESULT WinBioCaptureSampleWithCallback(
  [in]           WINBIO_SESSION_HANDLE    SessionHandle,
  [in]           WINBIO_BIR_PURPOSE       Purpose,
  [in]           WINBIO_BIR_DATA_FLAGS    Flags,
  [in]           PWINBIO_CAPTURE_CALLBACK CaptureCallback,
  [in, optional] PVOID                    CaptureCallbackContext
);

매개 변수

[in] SessionHandle

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

[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_INTEGRITYflag 설정된 경우 샘플에 서명합니다. 이 플래그가 설정되지 않았지만 WINBIO_DATA_FLAG_INTEGRITY 플래그가 설정된 경우 MAC을 계산합니다.

WINBIO_DATA_FLAG_RAW

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

WINBIO_DATA_FLAG_INTERMEDIATE

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

WINBIO_DATA_FLAG_PROCESSED

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

[in] CaptureCallback

캡처 작업이 성공하거나 실패할 때 WinBioCaptureSampleWithCallback 함수에서 호출되는 콜백 함수의 주소입니다. 콜백을 만들어야 합니다.

[in, optional] CaptureCallbackContext

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

반환 값

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

반환 코드	설명
E_ACCESSDENIED	호출자에게 원시 샘플을 캡처할 수 있는 권한이 없거나 WINBIO_FLAG_RAW 플래그를 사용하여 세션을 열지 않았습니다.
E_HANDLE	세션 핸들이 잘못되었습니다.
E_NOTIMPL	생체 인식 단위는 요청된 작업을 지원하지 않습니다.
E_POINTER	UnitId, Sample, SampleSize 및 RejectDetail 포인터는 NULL일 수 없습니다.
WINBIO_E_ENROLLMENT_IN_PROGRESS	생체 인식 단위가 현재 등록 트랜잭션에 사용 중이므로 작업을 완료할 수 없습니다(시스템 풀에만 해당).

설명

WinBioCaptureSampleWithCallback 함수는 샘플을 비동기적으로 캡처합니다. 이 함수를 성공적으로 호출하려면 WINBIO_FLAG_RAW 지정하여 세션 핸들을 열어야 합니다. 관리자 및 로컬 시스템 계정만 필요한 권한을 갖습니다.

용도 및 플래그 매개 변수의 유효한 조합은 사용 중인 생체 인식 단위의 기능에 따라 달라집니다. 지원되는 조합과 캡처된 데이터에 미치는 영향을 확인하려면 공급업체 센서 설명서를 참조하세요.

호출자는 Sample 매개 변수에서 반환된 WINBIO_BIR 구조를 해제해야 합니다.

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

VOID CALLBACK CaptureCallback(
__in_opt PVOID CaptureCallbackContext,
__in HRESULT OperationStatus,
__in WINBIO_UNIT_ID UnitId,
__in_bcount(SampleSize) PWINBIO_BIR Sample,
__in SIZE_T SampleSize,
__in WINBIO_REJECT_DETAIL RejectDetail
);

예제

다음 코드 예제에서는 WinBioCaptureSampleWithCallback 을 호출하고 사용자 지정 콜백 함수에 포인터를 전달하여 샘플을 비동기적으로 캡처합니다. 콜백 함수인 CaptureSampleCallback도 표시됩니다. Winbio.lib 정적 라이브러리에 연결하고 다음 헤더 파일을 포함합니다.

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

HRESULT CaptureSampleWithCallback(BOOL bCancel)
{
    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_RAW,            // Raw access
            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 asynchronously.
    wprintf_s(L"\n Calling WinBioCaptureSampleWithCallback ");
    hr = WinBioCaptureSampleWithCallback(
            sessionHandle,                  // Open session handle
            WINBIO_NO_PURPOSE_AVAILABLE,    // Intended use of the sample
            WINBIO_DATA_FLAG_RAW,           // Sample format
            CaptureSampleCallback,          // Callback function
            NULL                            // Optional context
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }
    wprintf_s(L"\n Swipe the sensor ...\n");

    // Cancel the capture process if the bCancel flag is set.
    if (bCancel)
    {
        wprintf_s(L"\n Starting CANCEL timer...");
        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 capture 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 Press any key to exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function is the callback for WinBioCaptureSampleWithCallback.
// The function filters the response from the biometric subsystem and 
// writes a result to the console window.
//
VOID CALLBACK CaptureSampleCallback(
    __in_opt PVOID CaptureCallbackContext,
    __in HRESULT OperationStatus,
    __in WINBIO_UNIT_ID UnitId,
    __in_bcount(SampleSize) PWINBIO_BIR Sample,
    __in SIZE_T SampleSize,
    __in WINBIO_REJECT_DETAIL RejectDetail
    )
{
    UNREFERENCED_PARAMETER(CaptureCallbackContext);

    wprintf_s(L"\n CaptureSampleCallback executing");
    wprintf_s(L"\n Swipe processed - Unit ID: %d", UnitId);

    if (FAILED(OperationStatus))
    {
        if (OperationStatus == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", RejectDetail);
         }
        else
        {
            wprintf_s(L"\n WinBioCaptureSampleWithCallback failed. ");
            wprintf_s(L" OperationStatus = 0x%x\n", OperationStatus);
        }
        goto e_Exit;
    }

    wprintf_s(L"\n Captured %d bytes.\n", SampleSize);

e_Exit:

    if (Sample != NULL)
    {
        WinBioFree(Sample);
        Sample = NULL;
    }
}

요구 사항

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

추가 정보

WinBioCaptureSample

다음을 통해 공유

WinBioCaptureSampleWithCallback 함수(winbio.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

추가 정보

피드백

추가 리소스