PIBIO_ENGINE_VERIFY_FEATURE_SET_FN 콜백 함수(winbio_adapter.h)

현재 기능 집합의 템플릿을 데이터베이스의 특정 템플릿과 비교하기 위해 Windows 생체 인식 프레임워크에서 호출됩니다. 템플릿이 동일한 경우 엔진 어댑터는 Match 매개 변수가 가리키는 부울 값을 TRUE로 설정하고, PayloadBlob 매개 변수에서 일치하는 템플릿을 반환하고, HashValue 매개 변수에서 템플릿의 해시를 반환해야 합니다.

구문

PIBIO_ENGINE_VERIFY_FEATURE_SET_FN PibioEngineVerifyFeatureSetFn;

HRESULT PibioEngineVerifyFeatureSetFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_IDENTITY Identity,
  [in]      WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [out]     PBOOLEAN Match,
  [out]     PUCHAR *PayloadBlob,
  [out]     PSIZE_T PayloadBlobSize,
  [out]     PUCHAR *HashValue,
  [out]     PSIZE_T HashSize,
  [out]     PWINBIO_REJECT_DETAIL RejectDetail
)
{...}

매개 변수

[in, out] Pipeline

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

[in] Identity

데이터베이스에서 복구된 템플릿과 일치해야 하는 GUID 또는 SID가 포함된 WINBIO_IDENTITY 구조체에 대한 포인터입니다.

[in] SubFactor

데이터베이스에서 복구된 템플릿의 값과 일치해야 하는 WINBIO_BIOMETRIC_SUBTYPE 값입니다. 자세한 내용은 설명 섹션을 참조하세요.

[out] Match

ID 및 SubFactor 매개 변수가 데이터베이스에서 복구된 템플릿의 매개 변수와 일치하는지 여부를 지정하는 부울 값에 대한 포인터입니다. TRUE 는 이러한 값이 일치되도록 지정합니다.

[out] PayloadBlob

템플릿으로 저장된 페이로드 데이터에 대한 포인터를 수신하는 변수의 주소입니다. 페이로드 데이터가 없는 경우 이 값을 NULL로 설정합니다.

[out] PayloadBlobSize

PayloadBlob 매개 변수에 지정된 버퍼의 크기(바이트)를 받는 값에 대한 포인터입니다. 템플릿과 함께 저장된 페이로드 데이터가 없는 경우 이 값을 0으로 설정합니다.

[out] HashValue

템플릿의 해시에 대한 포인터를 수신하는 변수의 주소입니다. 엔진 어댑터가 해시 생성을 지원하지 않는 경우 이 값을 NULL로 설정합니다.

[out] HashSize

HashValue 매개 변수로 지정된 해시의 크기(바이트)를 포함하는 값에 대한 포인터입니다. 엔진 어댑터가 해시 생성을 지원하지 않는 경우 이 값을 0으로 설정합니다.

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

설명

SubFactor 매개 변수는 생체 인식 템플릿과 연결된 하위 요소를 지정합니다. 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_SUBTYPE_ANY

이 함수에서 반환된 해시 값(있는 경우)은 파이프라인에 연결된 일치하는 템플릿이 아니라 데이터베이스에 있는 등록 템플릿의 해시입니다.

PayloadBlob 및 HashValue 버퍼는 EngineAdapterIdentifyFeatureSet 함수가 성공적으로 반환된 후 엔진 어댑터가 소유하고 관리합니다. 엔진 어댑터는 EngineAdapterClearContext에 대한 다음 호출까지 이 파이프라인에 대해 버퍼 주소를 유효하게 유지해야 합니다.

예제

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterVerifyFeatureSet
//
// Purpose:
//      Compares the template in the current feature set with a specific 
//      template in the database.
//      
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Identity        - GUID or SID that is expected to match that of the 
//                        template recovered from the database
//      SubFactor       - A WINBIO_BIOMETRIC_SUBTYPE value that is expected 
//                        to match that of the template recovered from the 
//                        database
//      Match           - A Boolean value that specifies whether the Identity 
//                        and SubFactor parameters match those of the template
//                        recovered from the database
//      PayloadBlob     - Payload data saved with the template
//      PayloadBlobSize - Size, in bytes, of the buffer specified in the 
//                        PayloadBlob parameter
//      HashValue       - Hash of the template
//      HashSize        - Size, in bytes, of the hash specified by the 
//                        HashValue parameter
//      RejectDetail    - Receives additional information if a capture failure 
//                        prevents the engine from performing a matching operation
// 
static HRESULT
WINAPI
EngineAdapterVerifyFeatureSet(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __out PBOOLEAN Match,
    __out PUCHAR *PayloadBlob,
    __out PSIZE_T PayloadBlobSize,
    __out PUCHAR *HashValue,
    __out PSIZE_T HashSize,
    __out PWINBIO_REJECT_DETAIL RejectDetail
    )
{
    HRESULT hr = S_OK;
    WINBIO_STORAGE_RECORD thisRecord;
    BOOLEAN match = FALSE;
    WINBIO_REJECT_DETAIL rejectDetail = 0;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(Identity) ||
        !ARGUMENT_PRESENT(Match) ||
        !ARGUMENT_PRESENT(PayloadBlob) ||
        !ARGUMENT_PRESENT(PayloadBlobSize) ||
        !ARGUMENT_PRESENT(HashValue) ||
        !ARGUMENT_PRESENT(HashSize) ||
        !ARGUMENT_PRESENT(RejectDetail))
    {
        hr = E_POINTER;
        goto cleanup;
    }

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

    // Initialize the return values.
    *Match              = FALSE;
    *PayloadBlob        = NULL;
    *PayloadBlobSize    = 0;
    *HashValue          = NULL;
    *HashSize           = 0;
    *RejectDetail       = 0;

    // The biometric unit cannot perform verification or identification
    // operations while it is performing an enrollment sequence.
    if (context->Enrollment.InProgress == TRUE)
    {
        hr = WINBIO_E_ENROLLMENT_IN_PROGRESS;
        goto cleanup;
    }

    // Query the storage adapter to determine whether the Identity and 
    // SubFactor combination specified on input are in the database. If
    // they are not, there can be no match. WbioStorageQueryBySubject
    // is a wrapper function defined in the Winbio_adapter.h header file.
    hr = WbioStorageQueryBySubject( Pipeline, Identity, SubFactor);
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_DATABASE_NO_RESULTS)
        {
            hr = WINBIO_E_NO_MATCH;
        }
        goto cleanup;
    }

    // Position the cursor on the first record in the database. 
    // WbioStorageFirstRecord is a wrapper function defined in the 
    // Winbio_adapter.h header file.
    hr = WbioStorageFirstRecord( Pipeline );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Retrieve the current template record for the Identity and SubFactor 
    // combination specified on input. 
    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 the database.
    // If the template and feature set do not match, return WINBIO_E_NO_MATCH
    // and set the Match parameter to FALSE.
    // If your custom function cannot process the feature set, return 
    // WINBIO_E_BAD_CAPTURE and set extended error information in the 
    // RejectDetail parameter.
    hr = _AdapterCompareTemplateToCurrentFeatureSet( 
                context, 
                context->FeatureSet,
                context->FeatureSetSize,
                thisRecord.TemplateBlob, 
                thisRecord.TemplateBlobSize,
                &match,
                RejectDetail 
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // If there is a match and if your engine adapter supports template
    // hashing, call a custom function (_AdapterGenerateHashForTemplate)
    // to calculate the hash. Save the hash value in the context area of
    // the engine adapter.
    // Skip this step if your adapter does not support template hashing.
    hr = _AdapterGenerateHashForTemplate(
                context,
                thisRecord.TemplateBlob, 
                thisRecord.TemplateBlobSize,
                context->HashBuffer,
                &context->HashSize
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Set the return values.
    *Match              = TRUE;
    *PayloadBlob        = thisRecord.PayloadBlob;
    *PayloadBlobSize    = thisRecord.PayloadBlobSize;
    *HashValue          = &context->HashBuffer;
    *HashSize           = context->HashSize;

cleanup:

    if (hr == WINBIO_E_DATABASE_NO_RESULTS)
    {
        hr = WINBIO_E_NO_MATCH;
    }

    return hr;
}

요구 사항

추가 정보

EngineAdapterIdentifyFeatureSet

플러그 인 함수