Edit

Share via

WinBioEnrollSelect function (winbio.h)

  • Article

Specifies the individual that you want to enroll when data that represents multiple individuals is present in the sample buffer. Starting with Windows 10, build 1607, this function is available to use with a mobile image.

Syntax

HRESULT WinBioEnrollSelect(
  [in] WINBIO_SESSION_HANDLE SessionHandle,
  [in] ULONGLONG             SelectorValue
);

Parameters

[in] SessionHandle

A WINBIO_SESSION_HANDLE value that identifies an open biometric session. Open a synchronous session handle by calling WinBioOpenSession. Open an asynchronous session handle by calling WinBioAsyncOpenSession.

For enrollment in facial recognition, use WinBioAsyncOpenSession with the PoolType parameter set to WINBIO_POOL_SYSTEM to get the handle.

[in] SelectorValue

A value that identifies that individual that you want to select for enrollment.

Return value

If the function succeeds, it returns S_OK. If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

Return code Description
E_HANDLE
 The session handle is not valid.
E_INVALIDARG
 The SelectorValue parameter cannot equal zero.
WINBIO_E_INCORRECT_SESSION_TYPE
 The session handle does not correspond to a biometric session.

Remarks

For enrollment in facial recognition, you can find the correct selector value in either of two ways:

  • The value of the Id member of one of the WINBIO_PRESENCE structures previously sent.
  • The data produced by the NUI face-tracking APIs.
Call WinBioEnrollSelect to set the selector value after you call WinBioEnrollBegin to start an enrollment sequence. The selector value applies to all subsequent WinBioEnrollCapture calls. The selection setting is temporary and is automatically cleared when you finish the enrollment sequence by calling WinBioEnrollCommit or WinBioEnrollDiscard.

If you call WinBioEnrollSelect for biometric factors that do not require disambiguation, such as fingerprints, the return value for the function indicates success, but function ignores the selector value.

If you do not call WinBioEnrollSelect for a biometric factor that requires you to call the function, subsequent calls to WinBioEnrollCapture fail with the WINBIO_E_SELECTION_REQUIRED error.

For Windows 10, the factors that require you to call WinBioEnrollSelect are facial features and iris.

You can call WinBioEnrollSelect by using either a synchronous or asynchronous session handle. As with other calls to Windows Biometric Framework API functions, when you call WinBioEnrollSelect with an asynchronous session handle, the return value indicates only that the function parameters were acceptable. The actual success or failure of the operation itself will be returned to your notification routine in a WINBIO_ASYNC_RESULT structure.

Requirements

Requirement Value
Minimum supported client Windows 10 [desktop apps only]
Minimum supported server Windows Server 2016 [desktop apps only]
Target Platform Windows
Header winbio.h
Library Winbio.lib
DLL Winbio.dll

See also

WINBIO_ASYNC_RESULT

WINBIO_PRESENCE

WinBioEnrollBegin

WinBioEnrollCapture

WinBioEnrollCommit

WinBioEnrollDiscard