PIBIO_STORAGE_QUERY_BY_SUBJECT_FN 콜백 함수(winbio_adapter.h)

아티클
08/27/2023

지정된 ID 및 하위 요소와 일치하는 템플릿을 찾기 위해 Windows 생체 인식 프레임워크 또는 엔진 어댑터에서 호출됩니다.

구문

PIBIO_STORAGE_QUERY_BY_SUBJECT_FN PibioStorageQueryBySubjectFn;

HRESULT PibioStorageQueryBySubjectFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_IDENTITY Identity,
  [in]      WINBIO_BIOMETRIC_SUBTYPE SubFactor
)
{...}

매개 변수

[in, out] Pipeline

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

[in] Identity

배치할 GUID 또는 SID를 포함하는 WINBIO_IDENTITY 구조체에 대한 포인터입니다. 이 구조체의 형식 필드에 WINBIO_IDENTITY_TYPE_WILDCARD 포함된 경우 쿼리는 SubFactor 매개 변수와 일치하는 모든 템플릿을 반환합니다.

[in] SubFactor

배치할 하위 요소를 지정하는 WINBIO_BIOMETRIC_SUBTYPE 값입니다. 이 값이 WINBIO_SUBTYPE_ANY 경우 쿼리는 Identity 매개 변수와 일치하는 모든 템플릿을 반환합니다.

반환 값

함수가 성공하면 S_OK를 반환합니다. 함수가 실패하면 다음 HRESULT 값 중 하나를 반환하여 오류를 나타내야 합니다.

반환 코드	설명
E_INVALIDARG	SubFactor 매개 변수로 지정된 인수가 잘못되었거나 Identity 매개 변수로 지정된 구조체의 멤버가 잘못되었습니다.
E_POINTER	필수 포인터 인수는 NULL입니다.
WINBIO_E_DATABASE_NO_RESULTS	쿼리가 성공했지만 일치하는 레코드를 찾을 수 없습니다.
WINBIO_E_DATABASE_LOCKED	데이터베이스가 잠겨 있습니다.
WINBIO_E_DATABASE_READ_ERROR	지정되지 않은 문제가 발생했습니다.
WINBIO_E_INVALID_DEVICE_STATE	파이프라인 개체의 StorageContext 멤버가 NULL 이거나 FileHandle 멤버가 잘못되었습니다.

설명

이 메서드가 성공적으로 반환되면 쿼리가 빈 집합을 반환하더라도 파이프라인의 결과 집합이 쿼리의 결과로 대체됩니다.

이 함수의 호출자는 다음을 통해 모든 레코드를 검색할 수 있어야 합니다.

형식 필드가 WINBIO_IDENTITY_TYPE_WILDCARD 설정된 Identity 매개 변수의 WINBIO_IDENTITY 구조체를 전달합니다.
SubFactor 매개 변수에 WINBIO_SUBTYPE_ANY 전달합니다.

이 함수를 성공적으로 호출한 후에는 결과 집합 커서가 집합의 첫 번째 레코드에 배치되어야 합니다.

중요

SubFactor 매개 변수에 제공된 값의 유효성을 검사하지 마세요. Windows 생체 인식 서비스는 제공된 값을 구현에 전달하기 전에 유효성을 검사합니다. 값이 WINBIO_SUBTYPE_NO_INFORMATION 또는 WINBIO_SUBTYPE_ANY 경우 적절한 경우 유효성을 검사합니다.

예제

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

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterQueryBySubject
//
// Purpose:
//      Locates templates that match a specified identity and sub-factor.
//
// Parameters:
//      Pipeline  -  Pointer to a WINBIO_PIPELINE structure associated with 
//                   the biometric unit performing the operation.
//      Identity  -  Pointer to a WINBIO_IDENTITY structure that contains the GUID 
//                   or SID to be located.
//      SubFactor -  A WINBIO_BIOMETRIC_SUBTYPE value that specifies the sub-factor 
//                   to be located.
//
static HRESULT
WINAPI
StorageAdapterQueryBySubject(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor
    )
{
    HRESULT hr = S_OK;
    SIZE_T recordCount = 0;

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

    // Retrieve the context from the pipeline.
    PWINBIO_STORAGE_CONTEXT storageContext = (PWINBIO_STORAGE_CONTEXT)Pipeline->StorageContext;

    // Verify the pipeline state.
    if (storageContext == NULL || storageContext->FileHandle == INVALID_HANDLE_VALUE)
    {
        hr =  WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Verify the Identity argument.
    if (Identity->Type != WINBIO_ID_TYPE_GUID &&
        Identity->Type != WINBIO_ID_TYPE_SID &&
        Identity->Type != WINBIO_ID_TYPE_WILDCARD)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    if (Identity->Type == WINBIO_ID_TYPE_WILDCARD &&
        Identity->Value.Wildcard != WINBIO_IDENTITY_WILDCARD)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // WINBIO_SUBTYPE_ANY is a valid sub-factor.
    // WINBIO_SUBTYPE_NO_INFORMATION is not a valid sub-factor.
    if (SubFactor == WINBIO_SUBTYPE_NO_INFORMATION)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Call a custom function (_FindAllMatchingRecords) that compares the 
    // identity and sub-factor values from the caller to the identity and
    // sub-factor values of every record in the database and adds the matching
    // database records to the result set in the pipeline.
    hr = _FindAllMatchingRecords( 
            Pipeline,
            Identity,
            SubFactor,
            &recordCount
            );
    if (FAILED(hr))
    {
        goto cleanup;
    }
    if (recordCount == 0)
    {
        hr = WINBIO_E_DATABASE_NO_RESULTS;
        goto cleanup;
    }

cleanup:

    return hr;
}

요구 사항

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