다음을 통해 공유

WinBioGetProperty 함수(winbio.h)

  • 아티클

세션, 단위 또는 템플릿 속성을 검색합니다. Windows 10 빌드 1607부터 이 함수를 모바일 이미지와 함께 사용할 수 있습니다.

구문

HRESULT WinBioGetProperty(
  [in]            WINBIO_SESSION_HANDLE    SessionHandle,
  [in]            WINBIO_PROPERTY_TYPE     PropertyType,
  [in]            WINBIO_PROPERTY_ID       PropertyId,
  [in, optional]  WINBIO_UNIT_ID           UnitId,
  [in, optional]  WINBIO_IDENTITY          *Identity,
  [in, optional]  WINBIO_BIOMETRIC_SUBTYPE SubFactor,
                  PVOID                    *PropertyBuffer,
  [out, optional] SIZE_T                   *PropertyBufferSize
);

매개 변수

[in] SessionHandle

열린 생체 인식 세션을 식별하는 WINBIO_SESSION_HANDLE 값입니다. WinBioOpenSession을 호출하여 동기 세션 핸들을 엽니다. WinBioAsyncOpenSession을 호출하여 비동기 세션 핸들을 엽니다.

[in] PropertyType

속성 정보의 원본을 지정하는 WINBIO_PROPERTY_TYPE 값입니다. 현재는 WINBIO_PROPERTY_TYPE_UNIT 또는 WINBIO_PROPERTY_TYPE_ACCOUNT 합니다. 속성 형식에 대한 자세한 내용은 WINBIO_PROPERTY_TYPE 상수를 참조하세요.

WINBIO_PROPERTY_TYPE_ACCOUNT 값은 Windows 10 부터 지원됩니다.

[in] PropertyId

쿼리할 속성을 지정하는 WINBIO_PROPERTY_ID 값입니다. 다음 값이 가능합니다.

값 의미
WINBIO_PROPERTY_SAMPLE_HINT
 등록 템플릿을 완료하는 데 필요한 좋은 생체 인식 샘플의 최대 수를 예측합니다. 속성 쿼리의 결과는 PropertyBuffer 매개 변수가 힌트를 포함하는 ULONG 값으로 가리키는 버퍼에 반환됩니다.
WINBIO_PROPERTY_EXTENDED_SENSOR_INFO
특정 생체 인식 단위에 연결된 센서 구성 요소의 기능 및 특성에 대한 확장된 정보를 포함합니다. 속성 쿼리의 결과는 PropertyBuffer 매개 변수가 WINBIO_EXTENDED_SENSOR_INFO 구조체로 가리키는 버퍼에 반환됩니다. 이 값은 Windows 10 부터 지원됩니다.
WINBIO_PROPERTY_EXTENDED_ENGINE_INFO
특정 생체 인식 단위에 연결된 엔진 구성 요소의 기능 및 특성에 대한 확장된 정보를 포함합니다. 속성 쿼리의 결과는 PropertyBuffer 매개 변수가 WINBIO_EXTENDED_ENGINE_INFO 구조체로 가리키는 버퍼에 반환됩니다. 이 값은 Windows 10 부터 지원됩니다.
WINBIO_PROPERTY_EXTENDED_STORAGE_INFO
특정 생체 인식 단위에 연결된 스토리지 구성 요소의 기능 및 특성에 대한 확장된 정보를 포함합니다. 속성 쿼리의 결과는 PropertyBuffer 매개 변수가 WINBIO_EXTENDED_STORAGE_INFO 구조체로 가리키는 버퍼에 반환됩니다. 이 값은 Windows 10 부터 지원됩니다.
WINBIO_PROPERTY_EXTENDED_ENROLLMENT_STATUS
특정 생체 인식 단위에서 진행 중인 등록의 상태 대한 확장 정보를 포함합니다. 속성 쿼리의 결과는 PropertyBuffer 매개 변수가 WINBIO_EXTENDED_ENROLLMENT_STATUS 구조체로 가리키는 버퍼에 반환됩니다. 생체 인식 단위에서 등록이 진행 중이 아니면 반환된 구조체의 TemplateStatus 멤버 값이 WINBIO_E_INVALID_OPERATION. 이 값은 Windows 10 부터 지원됩니다.
WINBIO_PROPERTY_ANTI_SPOOF_POLICY
특정 사용자 계정에 대한 스푸핑 방지 정책의 값을 포함합니다. 속성 작업은 PropertyBuffer 매개 변수가 WINBIO_ANTI_SPOOF_POLICY 구조체로 가리키는 버퍼에 반환됩니다. 이 값은 Windows 10 부터 지원됩니다.
 

이러한 속성에 대한 자세한 내용은 WINBIO_PROPERTY 상수를 참조하세요.

[in, optional] UnitId

생체 인식 단위를 식별하는 WINBIO_UNIT_ID 값입니다. WinBioEnumBiometricUnits 또는 WinBioLocateSensor 함수를 호출하여 단위 식별자를 찾을 수 있습니다.

WINBIO_PROPERTY_ANTI_SPOOF_POLICYPropertyId 매개 변수의 값으로 지정하는 경우 UnitId 매개 변수에 대해 0을 지정합니다. PropertyId 매개 변수를 사용하여 다른 속성을 지정하는 경우 UnitId 매개 변수에 대해 0을 지정할 수 없습니다.

[in, optional] Identity

WINBIO_PROPERTY_ANTI_SPOOF_POLICY PropertyId 매개 변수의 값으로 지정하는 경우 스푸핑 방지 정책을 가져올 계정의 SID를 제공하는 WINBIO_IDENTITY 구조체입니다.

PropertyId 매개 변수에 다른 값을 지정하는 경우 Identity 매개 변수는 NULL이어야 합니다.

[in, optional] SubFactor

예약되어 있습니다. WINBIO_SUBTYPE_NO_INFORMATION 합니다.

PropertyBuffer

속성 값을 수신하는 버퍼에 대한 포인터의 주소입니다. 다른 속성에 대한 이 버퍼의 내용에 대한 자세한 내용은 PropertyId 매개 변수의 속성 값에 대한 설명을 참조하세요.

[out, optional] PropertyBufferSize

PropertyBuffer 매개 변수가 가리키는 버퍼의 크기(바이트)를 수신하는 변수에 대한 포인터입니다.

반환 값

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

반환 코드 설명
E_HANDLE
 SessionHandle 매개 변수로 지정된 세션 핸들이 잘못되었습니다.
E_POINTER
 Identity, PropertyBuffer 또는 PropertyBufferSize 인수는 NULL일 수 없습니다.
E_INVALIDARG
 UnitId, Identity 또는 SubFactor 인수가 잘못되었습니다.
WINBIO_E_INVALID_PROPERTY_TYPE
 PropertyType 인수의 값이 잘못되었습니다.
WINBIO_E_INVALID_PROPERTY_ID
 PropertyId 인수의 값이 잘못되었습니다.
WINBIO_E_LOCK_VIOLATION
 호출자가 잠긴 지역 내에 있는 속성을 쿼리하려고 했습니다.
WINBIO_E_UNSUPPORTED_PROPERTY
 쿼리되는 개체는 지정된 속성을 지원하지 않습니다.
WINBIO_E_ENROLLMENT_IN_PROGRESS
 지정된 생체 인식 단위가 현재 등록 트랜잭션에 사용 중이므로 작업을 완료할 수 없습니다(시스템 풀에만 해당).

설명

WinBioGetProperty를 동기적으로 사용하려면 WinBioOpenSession을 호출하여 만든 세션 핸들을 사용하여 함수를 호출합니다. 함수는 작업이 완료되거나 오류가 발생할 때까지 차단됩니다. WinBioGetProperty를 동기적으로 사용할 때 메모리 누수를 방지하려면 WinBioFree를 호출하여 버퍼에 포함된 데이터 사용을 완료할 때 PropertyBuffer 매개 변수가 가리키는 메모리를 해제해야 합니다.

WinBioGetProperty를 비동기적으로 사용하려면 WinBioAsyncOpenSession을 호출하여 만든 세션 핸들을 사용하여 함수를 호출합니다. 프레임워크는 WINBIO_ASYNC_RESULT 구조를 할당하고 이를 사용하여 작업 성공 또는 실패에 대한 정보를 반환합니다. 작업이 성공하면 프레임워크는 중첩된 GetProperty 구조체에서 정보를 반환합니다. WINBIO_ASYNC_RESULT 구조체는 WinBioAsyncOpenSession 함수의 NotificationMethod 매개 변수에 설정한 값에 따라 애플리케이션 콜백 또는 애플리케이션 메시지 큐로 반환됩니다.

  • 콜백을 사용하여 완료 알림을 수신하도록 선택하는 경우 PWINBIO_ASYNC_COMPLETION_CALLBACK 함수를 구현하고 NotificationMethod 매개 변수를 WINBIO_ASYNC_NOTIFY_CALLBACK 설정해야 합니다.
  • 애플리케이션 메시지 큐를 사용하여 완료 알림을 수신하도록 선택하는 경우 NotificationMethod 매개 변수를 WINBIO_ASYNC_NOTIFY_MESSAGE 설정해야 합니다. 프레임워크는 창 메시지의 LPARAM 필드에 대한 WINBIO_ASYNC_RESULT 포인터를 반환합니다.
WinBioGetProperty를 비동기적으로 사용할 때 메모리 누수 방지를 위해 WinBioFree를 호출하여 WINBIO_ASYNC_RESULT 구조를 해제해야 합니다. WINBIO_ASYNC_RESULT 구조체와 속성 버퍼는 단일 메모리 블록을 차지하므로 애플리케이션은 WINBIO_ASYNC_RESULT 구조체의 주소만 WinBioFree에 전달하면 됩니다. 이러한 방식으로 WinBioFree 를 호출하면 WinBioFree 는 WINBIO_ASYNC_RESULT 구조체와 속성 버퍼를 모두 자동으로 해제합니다. 이 경우 속성 버퍼를 별도로 해제하려고 하면 애플리케이션의 응답이 중지됩니다.

요구 사항

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

추가 정보

WinBioFree

WinBioSetProperty