WinBioAsyncOpenSession 함수(winbio.h)

생체 인식 서비스 공급자와 하나 이상의 생체 인식 단위에 비동기적으로 연결합니다. Windows 10 빌드 1607부터 이 함수를 모바일 이미지와 함께 사용할 수 있습니다. 성공하면 함수는 생체 인식 세션 핸들을 반환합니다. 이 핸들을 사용하여 수행되는 모든 작업은 WinBioCloseSession을 포함하여 비동기적으로 완료되며, 결과는 NotificationMethod 매개 변수에 지정된 메서드를 사용하여 클라이언트 애플리케이션에 반환됩니다.

이 함수의 동기 버전은 WinBioOpenSession을 참조하세요.

구문

HRESULT WinBioAsyncOpenSession(
  [in]            WINBIO_BIOMETRIC_TYPE             Factor,
  [in]            WINBIO_POOL_TYPE                  PoolType,
  [in]            WINBIO_SESSION_FLAGS              Flags,
  [in, optional]  WINBIO_UNIT_ID                    *UnitArray,
  [in, optional]  SIZE_T                            UnitCount,
  [in, optional]  GUID                              *DatabaseId,
  [in]            WINBIO_ASYNC_NOTIFICATION_METHOD  NotificationMethod,
  [in, optional]  HWND                              TargetWindow,
  [in, optional]  UINT                              MessageCode,
  [in, optional]  PWINBIO_ASYNC_COMPLETION_CALLBACK CallbackRoutine,
  [in, optional]  PVOID                             UserData,
  [in]            BOOL                              AsynchronousOpen,
  [out, optional] WINBIO_SESSION_HANDLE             *SessionHandle
);

매개 변수

[in] Factor

열거할 생체 인식 단위 유형을 지정하는 WINBIO_BIOMETRIC_TYPE 플래그의 비트 마스크입니다. 현재 WINBIO_TYPE_FINGERPRINT 만 지원됩니다.

[in] PoolType

세션에서 사용할 생체 인식 단위의 형식을 지정하는 ULONG 값입니다. 다음 값 중 하나일 수 있습니다.

값	의미
WINBIO_POOL_SYSTEM	세션은 서비스 공급자가 관리하는 생체 인식 단위의 공유 컬렉션에 연결합니다.
WINBIO_POOL_PRIVATE	세션은 호출자가 관리하는 생체 인식 단위 컬렉션에 연결합니다.

[in] Flags

새 세션의 생체 인식 단위 구성 및 액세스 특성을 지정하는 ULONG 값입니다. 구성 플래그는 세션에서 단위의 일반 구성을 지정합니다. 액세스 플래그는 애플리케이션이 생체 인식 단위를 사용하는 방법을 지정합니다. 하나의 구성 플래그를 지정해야 하지만 해당 플래그를 액세스 플래그와 결합할 수 있습니다.

값	의미
WINBIO_FLAG_DEFAULT	그룹: 구성 생체 인식 단위는 설치 중에 지정된 방식으로 작동합니다. PoolType 매개 변수가 WINBIO_POOL_SYSTEM 경우 이 값을 사용해야 합니다.
WINBIO_FLAG_BASIC	그룹: 구성 생체 인식 단위는 기본 캡처 디바이스로만 작동합니다. 모든 처리, 일치 및 스토리지 작업은 소프트웨어 플러그 인에서 수행됩니다.
WINBIO_FLAG_ADVANCED	그룹: 구성 생체 인식 단위는 내부 처리 및 스토리지 기능을 사용합니다.
WINBIO_FLAG_RAW	그룹: 액세스 클라이언트 애플리케이션은 WinBioCaptureSample을 사용하여 원시 생체 인식 데이터를 캡처합니다.
WINBIO_FLAG_MAINTENANCE	그룹: 액세스 클라이언트는 WinBioControlUnitPrivileged를 호출하여 생체 인식 단위에서 공급업체 정의 제어 작업을 수행합니다.

[in, optional] UnitArray

세션에 포함할 생체 인식 단위 식별자 배열에 대한 포인터입니다. WinBioEnumBiometricUnits를 호출하여 생체 인식 단위를 열거할 수 있습니다. PoolType 매개 변수가 WINBIO_POOL_SYSTEM 경우 이 값을 NULL로 설정합니다.

[in, optional] UnitCount

UnitArray 매개 변수가 가리키는 배열의 요소 수를 지정하는 값입니다. PoolType 매개 변수가 WINBIO_POOL_SYSTEM 경우 이 값을 0으로 설정합니다.

[in, optional] DatabaseId

세션에서 사용할 데이터베이스를 지정하는 값입니다. PoolType 매개 변수가 WINBIO_POOL_PRIVATE 경우 설치된 데이터베이스의 GUID를 지정해야 합니다. PoolType 매개 변수가 WINBIO_POOL_PRIVATE 않으면 다음 공통 값 중 하나를 지정할 수 있습니다.

값	의미
WINBIO_DB_DEFAULT	센서 풀의 각 생체 인식 단위는 기본 생체 인식 단위 구성에 지정된 기본 데이터베이스를 사용합니다. PoolType 매개 변수가 WINBIO_POOL_SYSTEM 경우 이 값을 지정해야 합니다. PoolType 매개 변수가 WINBIO_POOL_PRIVATE 경우 이 값을 사용할 수 없습니다.
WINBIO_DB_BOOTSTRAP	Windows를 시작하기 전에 시나리오에 사용할 이 값을 지정할 수 있습니다. 일반적으로 데이터베이스는 센서 칩의 일부이거나 BIOS의 일부이며 템플릿 등록 및 삭제에만 사용할 수 있습니다.
WINBIO_DB_ONCHIP	데이터베이스는 센서 칩에 있으며 등록 및 일치에 사용할 수 있습니다.

[in] NotificationMethod

이 생체 인식 세션의 비동기 작업에 대한 완료 알림을 클라이언트 애플리케이션에 전달하는 방법을 지정합니다. 다음 값 중 하나여야 합니다.

값	의미
WINBIO_ASYNC_NOTIFY_CALLBACK	세션은 애플리케이션에서 정의한 콜백 함수를 호출합니다.
WINBIO_ASYNC_NOTIFY_MESSAGE	세션은 애플리케이션의 메시지 큐에 창 메시지를 게시합니다.

[in, optional] TargetWindow

완료 알림을 받을 창의 핸들입니다. NotificationMethod 매개 변수를 WINBIO_ASYNC_NOTIFY_MESSAGE 설정하지 않으면 이 값은 무시됩니다.

[in, optional] MessageCode

완료 알림을 나타내기 위해 프레임워크에서 보내야 하는 창 메시지 코드입니다. NotificationMethod 매개 변수를 WINBIO_ASYNC_NOTIFY_MESSAGE 설정하지 않으면 이 값은 무시됩니다. 값은 0xBFFF WM_APP(0x8000) 범위 내에 있어야 합니다.

Windows 생체 인식 프레임워크는 메시지의 LPARAM 값을 작업 결과를 포함하는 WINBIO_ASYNC_RESULT 구조체의 주소로 설정합니다. WinBioFree를 호출하여 구조를 사용한 후 해제해야 합니다.

[in, optional] CallbackRoutine

세션 핸들을 사용하여 작업을 시작할 때 호출할 콜백 루틴의 주소가 완료됩니다. NotificationMethod 매개 변수가 WINBIO_ASYNC_NOTIFY_CALLBACK 설정되지 않으면 이 값은 무시됩니다.

[in, optional] UserData

호출자가 제공한 버퍼의 주소입니다. 버퍼는 프레임워크 또는 생체 인식 단위에 의해 수정되지 않습니다. WINBIO_ASYNC_RESULT 구조체에서 반환됩니다. 애플리케이션은 데이터를 사용하여 완료 알림을 받을 때 수행할 작업을 결정하거나 요청된 작업에 대한 추가 정보를 유지할 수 있습니다.

[in] AsynchronousOpen

프레임워크 세션이 열릴 때까지 차단할지 여부를 지정합니다. FALSE를 지정하면 프로세스가 차단됩니다. TRUE를 지정하면 세션이 비동기적으로 열립니다.

FALSE를 지정하여 프레임워크 세션을 동기적으로 열면 성공 또는 실패가 HRESULT 반환 값의 이 함수에 의해 호출자에게 직접 반환됩니다. 세션이 성공적으로 열리면 애플리케이션이 수신하는 첫 번째 비동기 완료 이벤트는 프레임워크가 열린 후 요청된 비동기 작업에 대한 것입니다.

TRUE를 지정하여 프레임워크 세션을 비동기적으로 열면 수신된 첫 번째 비동기 완료 알림은 프레임워크를 여는 것입니다. NotificationMethod 매개 변수를 WINBIO_ASYNC_NOTIFY_CALLBACK 설정하면 작업 결과가 CallbackRoutine 매개 변수로 지정된 콜백 함수의 WINBIO_ASYNC_RESULT 구조로 전달됩니다. NotificationMethod 매개 변수를 WINBIO_ASYNC_NOTIFY_MESSAGE 설정하면 작업 결과가 창 메시지의 LPARAM 필드가 가리키는 WINBIO_ASYNC_RESULT 구조로 전달됩니다.

[out, optional] SessionHandle

함수가 성공하지 못하면 이 매개 변수는 NULL이 됩니다.

세션이 동기적으로 성공적으로 열리면 이 매개 변수에는 세션 핸들에 대한 포인터가 포함됩니다.

세션을 비동기적으로 열도록 지정하면 이 메서드는 즉시 반환되고 세션 핸들은 NULL이 되며 WINBIO_ASYNC_RESULT 구조를 검사하여 세션이 성공적으로 열렸는지 확인해야 합니다.

반환 값

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

반환 코드	설명
E_OUTOFMEMORY	생체 인식 세션을 만드는 데 사용할 수 있는 메모리가 충분하지 않습니다.
E_INVALIDARG	알림 메서드를 WINBIO_ASYNC_NOTIFY_MESSAGE 설정하면 TargetWindow 매개 변수는 NULL 이거나 HWND_BROADCAST 수 없으며 MessageCode 매개 변수는 0일 수 없습니다.
E_POINTER	SessionHandle 매개 변수 및 AsynchronousOpen 매개 변수를 설정해야 합니다. 알림 메서드를 WINBIO_ASYNC_NOTIFY_CALLBACK 설정하는 경우 CallbackRoutine 매개 변수에서 콜백 함수의 주소도 지정해야 합니다.
E_ACCESSDENIED	Flags 매개 변수에는 WINBIO_FLAG_RAW 또는 WINBIO_FLAG_MAINTENANCE 플래그가 포함되며 호출자에게 액세스 권한이 부여되지 않았습니다.
WINBIO_E_INVALID_UNIT	UnitArray 매개 변수에 지정된 하나 이상의 생체 인식 단위 번호가 잘못되었습니다.
WINBIO_E_NOT_ACTIVE_CONSOLE	클라이언트 애플리케이션이 원격 데스크톱 클라이언트에서 실행 중이며 시스템 풀 세션을 열려고 합니다.
WINBIO_E_SENSOR_UNAVAILABLE	PoolType 매개 변수는 WINBIO_POOL_PRIVATE 설정되며 해당 풀에서 요청된 센서 중 하나 이상을 사용할 수 없습니다.
WINBIO_E_DISABLED	현재 관리 정책은 Windows 생체 인식 프레임워크 API 사용을 금지합니다.

설명

WinBioAsyncOpenSession 함수에서 반환된 세션 핸들을 사용하여 다음 함수에 대한 비동기 완료 알림을 생성할 수 있습니다.

• WinBioCancel
• WinBioCaptureSample
• WinBioCloseSession
• WinBioControlUnit
• WinBioControlUnitPrivileged
• WinBioDeleteTemplate
• WinBioEnrollBegin
• WinBioEnrollCapture
• WinBioEnrollCommit
• WinBioEnrollDiscard
• WinBioEnumEnrollments
• WinBioGetProperty
• WinBioIdentify
• WinBioLocateSensor
• WinBioLockUnit
• WinBioLogonIdentifiedUser
• WinBioRegisterEventMonitor
• WinBioUnlockUnit
• WinBioUnregisterEventMonitor
• WinBioVerify
• WinBioWait

WinBioAsyncOpenSession에서 반환된 세션 핸들은 다음 함수와 함께 사용할 수 없습니다.

• WinBioCaptureSampleWithCallback
• WinBioEnrollCaptureWithCallback
• WinBioIdentifyWithCallback
• WinBioIdentifyWithCallback

Windows 7에서 처음 사용할 수 있는 이러한 함수에는 호환되지 않는 콜백 서명이 있으며 새 애플리케이션에서 사용하는 것은 권장되지 않습니다. 비동기 콜백을 원하는 개발자는 대신 WINBIO_ASYNC_NOTIFY_CALLBACK NotificationMethod와 함께 WinBioAsyncOpenSession을 사용해야 합니다.

AsynchronousOpen 매개 변수는 열린 작업이 차단되는지 여부만 결정합니다. 이 매개 변수는 세션 핸들을 사용하는 후속 호출의 완료 동작에 영향을 주지 않습니다.

AsynchronousOpen 매개 변수를 TRUE로 설정하면 이 함수는 인수의 초기 유효성 검사를 수행하는 즉시 S_OK 반환합니다. 해당 시점을 초과하여 검색된 오류는 NotificationMethod 매개 변수로 지정된 메서드를 사용하여 호출자에게 보고됩니다. 즉, 반환 값이 성공하면 WinBioAsyncOpenSession 매개 변수가 정상이고 열린 작업이 성공하지 못했음을 나타냅니다. 열린 작업이 성공했는지 여부를 확인하려면 WINBIO_ASYNC_RESULT 구조를 검사해야 합니다.

요구 사항

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

추가 정보

WinBioAsyncOpenFramework

WinBioCloseSession

WinBioOpenSession