PIBIO_ENGINE_CHECK_FOR_DUPLICATE_FN 콜백 함수(winbio_adapter.h)

아티클
03/03/2024

Windows 생체 인식 프레임워크에서 호출하여 파이프라인의 새 템플릿이 템플릿과 연결된 ID에 관계없이 데이터베이스에 이미 저장된 템플릿을 복제하는지 여부를 확인합니다.

구문

PIBIO_ENGINE_CHECK_FOR_DUPLICATE_FN PibioEngineCheckForDuplicateFn;

HRESULT PibioEngineCheckForDuplicateFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [out]     PWINBIO_IDENTITY Identity,
  [out]     PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [out]     PBOOLEAN Duplicate
)
{...}

매개 변수

[in, out] Pipeline

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

[out] Identity

데이터베이스에 저장된 중복 템플릿의 GUID 또는 SID를 수신하는 WINBIO_IDENTITY 구조체에 대한 포인터입니다.

[out] SubFactor

데이터베이스의 중복 템플릿과 연결된 하위 요소를 수신하는 WINBIO_BIOMETRIC_SUBTYPE 변수에 대한 포인터입니다.

[out] Duplicate

데이터베이스에서 일치하는 템플릿이 있는지 여부를 지정하는 부울 값에 대한 포인터입니다.

반환 값

반환 코드	설명
E_POINTER	필수 포인터 매개 변수는 NULL입니다.
WINBIO_E_INVALID_DEVICE_STATE	파이프라인 엔진 컨텍스트에 등록 템플릿이 없습니다.

설명

Windows 생체 인식 프레임워크는 생체 인식 단위의 데이터베이스에 새 등록 템플릿을 커밋하기 전에 이 함수를 호출합니다. 이 함수의 목적은 엔진 어댑터의 충돌과 일치하는 공간을 방지하는 것입니다. 충돌하면 가양성 일치가 발생할 수 있습니다.

이 함수는 스토리지 어댑터를 사용하여 콘텐츠 기반 쿼리를 수행하여 템플릿이 데이터베이스에 이미 있는 템플릿과 일치하는지 여부를 확인해야 합니다.

이 메서드가 데이터베이스에서 중복 템플릿을 찾으면 일치하는 템플릿에 대한 IDENTITY 및 SubFactor 값을 반환하고, Duplicate 매개 변수를 TRUE로 설정하고, S_OK HRESULT 값을 반환해야 합니다.

이 메서드가 데이터베이스에서 일치하는 템플릿을 찾지 못하면 Duplicate 매개 변수를 FALSE 로 설정해야 하지만 HRESULT 값 S_OK 반환해야 합니다.

예제

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterCheckForDuplicate
// 
// Purpose:
//      Determines whether a new template in the pipeline duplicates any 
//      template already saved in the database regardless of the identity 
//      associated with the templates.
//
// Parameters:
//      Pipeline    - Pointer to a WINBIO_PIPELINE structure associated 
//                    with the biometric unit performing the operation
//      Identity    - GUID or SID of the duplicate template stored in the 
//                    database
//      SubFactor   - sub-factor associated with the duplicate template in
//                    the database
//      Duplicate   - Boolean value that specifies whether a matching template 
//                    was found in the database
//
static HRESULT
WINAPI
EngineAdapterCheckForDuplicate(
    __inout PWINBIO_PIPELINE Pipeline,
    __out PWINBIO_IDENTITY Identity,
    __out PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __out PBOOLEAN Duplicate
    )
{
    HRESULT hr = S_OK;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    SIZE_T recordCount = 0;
    SIZE_T index = 0;
    WINBIO_STORAGE_RECORD thisRecord;
    BOOLEAN match = FALSE;
    DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};

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

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

    // Return if an enrollment is not in progress. This example assumes that 
    // an enrollment object is part of your engine context structure.
    if (context->Enrollment.InProgress != TRUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Zero the memory pointed to by the Identity argument and set the
    // pointer to NULL.
    ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
    Identity->Type = WINBIO_ID_TYPE_NULL;

    // Eliminate sub-factor information.
    *SubFactor  = WINBIO_SUBTYPE_NO_INFORMATION;

    // Initialize the Boolean Duplicate argument to FALSE.
    *Duplicate  = FALSE;

    // If your adapter supports index vectors to place templates into buckets,
    // call a custom function (_AdapterCreateIndexVector) to create an index 
    // vector from the template data in the feature set. In this example, the
    // engine adapter context attached to the pipeline contains an Enrollment
    // member that references the current template. Your implementation may
    // differ.
    hr = _AdapterCreateIndexVector(
                context, 
                context->Enrollment.Template, 
                context->Enrollment.TemplateSize,
                indexVector, 
                NUMBER_OF_TEMPLATE_BINS, 
                &rejectDetail
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Retrieve the records in the index vector. If your adapter does not support 
    // index vectors (the vector length is zero), calling the WbioStorageQueryByContent 
    // function will retrieve all records.
    // WbioStorageQueryByContent is a wrapper function in the Winbio_adapter.h 
    // header file.
    hr = WbioStorageQueryByContent(
            Pipeline,
            WINBIO_SUBTYPE_ANY,
            indexVector,
            NUMBER_OF_TEMPLATE_BINS
            );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Determine the size of the result set. WbioStorageGetRecordCount is a wrapper
    // function in the Winbio_adapter.h header file.
    hr = WbioStorageGetRecordCount( Pipeline, &recordCount);
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Point the result set cursor at the first record. WbioStorageFirstRecord
    // is a wrapper function in the Winbio_adapter.h header file.
    hr = WbioStorageFirstRecord( Pipeline );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Iterate through all records in the result set and determine which record
    // matches the current feature set. WbioStorageGetCurrentRecord is a wrapper
    // function in the Winbio_adapter.h header file. 
    for (index = 0; index < recordCount; ++index)
    {
        hr = WbioStorageGetCurrentRecord( Pipeline, &thisRecord );
        if (FAILED(hr))
        {
            goto cleanup;
        }

        // Call a custom function (_AdapterCompareTemplateToCurrentFeatureSet) to
        // compare the feature set attached to the pipeline with the template
        // retrieved from storage.
        // If the template and feature set match, return S_OK and set the match
        // argument to TRUE. If the template and feature set do not match, return
        // S_OK and set the match argument to FALSE. If the function fails for some
        // other reason, return a failure HRESULT.
        hr = _AdapterCompareTemplateToEnrollmentTemplate( 
                    context, 
                    context->Enrollment.Template, 
                    context->Enrollment.TemplateSize,
                    thisRecord.TemplateBlob, 
                    thisRecord.TemplateBlobSize,
                    &match
                    );
        if (FAILED(hr))
        {
            goto cleanup;
        }
        if (match)
        {
            break;
        }

        // Retrieve the next record.
        hr = WbioStorageNextRecord( Pipeline );
        if (FAILED(hr))
        {
            if (hr == WINBIO_E_DATABASE_NO_MORE_RECORDS)
            {
                hr = S_OK;
                break;
            }
            else
            {
                goto cleanup;
            }
        }
    }

    // If there is a duplicate template in the database, return information about
    // it to the caller.
    if (match)
    {
        CopyMemory( Identity, thisRecord.Identity, sizeof(WINBIO_IDENTITY));
        *SubFactor = thisRecord.SubFactor;
        *Duplicate = TRUE;
        hr = S_OK;
    }

cleanup:

    // There are no duplicates. This is an acceptable result.
    if (hr == WINBIO_E_DATABASE_NO_RESULTS)
    {
        hr = S_OK;
    }
    return hr;
}

요구 사항

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

추가 정보

플러그 인 함수

다음을 통해 공유

PIBIO_ENGINE_CHECK_FOR_DUPLICATE_FN 콜백 함수(winbio_adapter.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

추가 정보

피드백

추가 리소스