PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN 콜백 함수(winbio_adapter.h)

아티클
08/27/2023

센서 어댑터에 의해 구현된 SensorAdapterPushDataToEngine 함수에 의해 호출되어 엔진 어댑터에 원시 생체 인식 샘플을 수락하고 기능 집합을 추출하도록 알립니다. 기능 집합은 일치 또는 등록에 사용할 수 있습니다.

구문

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN PibioEngineAcceptSampleDataFn;

HRESULT PibioEngineAcceptSampleDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_BIR SampleBuffer,
  [in]      SIZE_T SampleSize,
  [in]      WINBIO_BIR_PURPOSE Purpose,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

매개 변수

[in, out] Pipeline

작업을 수행하는 생체 인식 단위와 연결된 WINBIO_PIPELINE 구조체에 대한 포인터입니다.

[in] SampleBuffer

처리할 생체 인식 샘플을 포함하는 WINBIO_BIR 구조체에 대한 포인터입니다.

[in] SampleSize

SampleBuffer 매개 변수에 반환된 WINBIO_BIR 구조체의 크기를 포함하는 SIZE_T값입니다.

[in] Purpose

샘플의 의도된 사용을 지정하는 WINBIO_BIR_PURPOSE 비트 마스크입니다. WINBIO_BIR_PURPOSE 구조는 캡처 데이터를 사용할 목적과 최적화 방법을 지정합니다. 다음 값 중 비트 OR 일 수 있습니다.

WINBIO_PURPOSE_VERIFY
WINBIO_PURPOSE_IDENTIFY
WINBIO_PURPOSE_ENROLL
WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION

[out] 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 값 중 하나를 반환하여 오류를 나타내야 합니다.

반환 코드	설명
E_INVALIDARG	SampleSize 인수는 0일 수 없습니다. Purpose 인수는 매개 변수 설명에 나열된 값의 비트 OR이어야 합니다.
E_POINTER	Pipeline, SampleBuffer 및 RejectDetail 인수는 NULL일 수 없습니다.
E_OUTOFMEMORY	메모리가 부족하여 작업을 완료할 수 없습니다.
WINBIO_E_BAD_CAPTURE	필요한 기능 집합을 만들기 위해 데이터를 처리할 수 없습니다. RejectDetail에는 실패에 대한 추가 정보가 포함되어 있습니다.

설명

이 함수를 호출하여 만든 기능 집합은 함수가 반환된 후 생체 인식 단위 파이프라인에 유지됩니다. 이전 기능 집합을 대체합니다.

SensorAdapterPushDataToEngine 함수의 센서 어댑터 구현은 다음 래퍼 함수(Winbio_adapter.h에 정의됨)를 사용하여 EngineAdapterAcceptSampleData를 호출해야 합니다.

HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);

SampleBuffer 매개 변수에 전달되는 WINBIO_BIR 구조체는 센서 어댑터의 속성입니다. 센서 어댑터는 WINBIO_BIR 개체의 수명을 제어하므로 EngineAdapterAcceptSampleData 함수는 구조체의 할당을 취소하거나 포인터를 저장하려고 시도해서는 안 됩니다. 포인터를 저장하지 않으면 EngineAdapterAcceptSampleData 함수가 반환된 후 엔진 어댑터의 다른 부분이 WINBIO_BIR 구조를 사용하지 못하게 됩니다.

WINBIO_BIR 구조체의 StandardDataBlock 멤버의 Offset 필드가 0보다 큰 경우(BIR에 표준 데이터 형식의 생체 인식 샘플이 포함됨을 나타낸) HeaderBlock 멤버의 BiometricDataFormat 필드는 다음과 같이 설정해야 합니다.

소유자 필드는 WINBIO_ ANSI_381_FORMAT_OWNER 합니다.
형식 필드는 WINBIO_ANSI_381_FORMAT_TYPE 합니다.

Windows 생체 인식 프레임워크에서 지원하는 유일한 표준 데이터 형식입니다.

또한 Windows 생체 인식 프레임워크는 HeaderBlock 멤버( WINBIO_BIR_HEADER 구조체)에 샘플 캡처를 위해 센서 어댑터에서 사용하는 DataFlags 및 Purpose 값이 포함되어 있다고 가정합니다.

지문 센서가 지문 샘플을 처리하고 엔진 어댑터에서 잘못된 살짝 밀기를 거부하는 것도 WINBIO_BIR_PURPOSE 유효한 값을 사용해야 합니다.

예제

다음 의사 코드는 이 함수의 가능한 구현 중 하나를 보여 줍니다. 예제는 컴파일되지 않습니다. 목적에 맞게 조정해야 합니다.

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAcceptSampleData
//
// Purpose:
//      Notifies the engine adapter to accept a raw biometric sample and 
//      extract a feature set.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation. 
//      SampleBuffer    - Contains the biometric sample to be processed.
//      SampleSize      - Size of the structure returned in the SampleBuffer 
//                        parameter.
//      Purpose         - Specifies the intended use of the sample.
//      RejectDetail    - Receives additional information about the failure, 
//                        if any, to process a biometric sample.
//
static HRESULT
WINAPI
EngineAdapterAcceptSampleData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_BIR SampleBuffer,
    __in SIZE_T SampleSize,
    __in WINBIO_BIR_PURPOSE Purpose,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    PUCHAR featureSet = NULL;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline)     ||
        !ARGUMENT_PRESENT(SampleBuffer) ||
        !ARGUMENT_PRESENT(RejectDetail))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_ENGINE_CONTEXT context = 
           (PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

    // Verify that input arguments are valid.
    if (SampleSize == 0 ||
        Purpose == WINBIO_NO_PURPOSE_AVAILABLE)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Release any feature set currently attached to the pipeline before
    // creating a new feature set.
    if (context->FeatureSet != NULL)
    {
        _AdapterRelease(context->FeatureSet);
        context->FeatureSet = NULL;
        context->FeatureSetSize = 0;
    }

    // An actual engine adapter would here process the contents of the sample 
    // buffer, generate a feature set suitable for the purpose(s) specified 
    // by the Purpose parameter, and attach the feature set to the pipeline. 
    // The following trivial example, however, creates a feature set simply
    // by making an exact copy of the raw sample.
    // If the sample data cannot be processed, return an HRESULT error code
    // of WINBIO_E_BAD_CAPTURE and set extended error information in the 
    // RejectDetail parameter.
    featureSet = (PUCHAR)_AdapterAlloc(SampleSize);
    if (featureSet == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }
    RtlCopyMemory(featureSet, SampleBuffer, SampleSize);
    context->FeatureSet = featureSet;
    featureSet = NULL;
    context->FeatureSetSize = SampleSize;

cleanup:

    if (FAILED(hr))
    {
        if (featureSet != NULL)
        {
            _AdapterRelease(featureSet);
        }
    }

    return hr;
}

요구 사항

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

추가 정보

EngineAdapterExportEngineData

플러그 인 함수

다음을 통해 공유

PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN 콜백 함수(winbio_adapter.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

추가 정보

피드백

추가 리소스