WinBioOpenSession function (winbio.h)

Connects to a biometric service provider and one or more biometric units.


HRESULT WinBioOpenSession(
  [in]  WINBIO_POOL_TYPE      PoolType,
  [in]  WINBIO_UNIT_ID        *UnitArray,
  [in]  SIZE_T                UnitCount,
  [in]  GUID                  *DatabaseId,
  [out] WINBIO_SESSION_HANDLE *SessionHandle


[in] Factor

A bitmask of WINBIO_BIOMETRIC_TYPE flags that specifies the biometric unit types to be enumerated. Only WINBIO_TYPE_FINGERPRINT is currently supported.

[in] PoolType

A ULONG value that specifies the type of the biometric units that will be used in the session. This can be one of the following values:

Value Meaning
The session connects to a shared collection of biometric units managed by the service provider.
The session connects to a collection of biometric units that are managed by the caller.

[in] Flags

A ULONG value that specifies biometric unit configuration and access characteristics for the new session. Configuration flags specify the general configuration of units in the session. Access flags specify how the application will use the biometric units. You must specify one configuration flag but you can combine that flag with any access flag.

Value Meaning
Group: configuration

The biometric units operate in the manner specified during installation. You must use this value when the PoolType parameter is WINBIO_POOL_SYSTEM.

Group: configuration

The biometric units operate only as basic capture devices. All processing, matching, and storage operations is performed by software plug-ins.

Group: configuration

The biometric units use internal processing and storage capabilities.

Group: access

The client application captures raw biometric data using WinBioCaptureSample.

Group: access

The client performs vendor-defined control operations on a biometric unit by calling WinBioControlUnitPrivileged.

[in] UnitArray

Pointer to an array of biometric unit identifiers to be included in the session. You can call WinBioEnumBiometricUnits to enumerate the biometric units. Set this value to NULL if the PoolType parameter is WINBIO_POOL_SYSTEM.

[in] UnitCount

A value that specifies the number of elements in the array pointed to by the UnitArray parameter. Set this value to zero if the PoolType parameter is WINBIO_POOL_SYSTEM.

[in] DatabaseId

A value that specifies the database(s) to be used by the session. If the PoolType parameter is WINBIO_POOL_PRIVATE, you must specify the GUID of an installed database. If the PoolType parameter is not WINBIO_POOL_PRIVATE, you can specify one of the following common values.

Value Meaning
Each biometric unit in the sensor pool uses the default database specified in the default biometric unit configuration. You must specify this value if the PoolType parameter is WINBIO_POOL_SYSTEM. You cannot use this value if the PoolType parameter is WINBIO_POOL_PRIVATE
You can specify this value to be used for scenarios prior to starting Windows. Typically, the database is part of the sensor chip or is part of the BIOS and can only be used for template enrollment and deletion.
The database is on the sensor chip and is available for enrollment and matching.

[out] SessionHandle

Pointer to the new session handle. If the function does not succeed, the handle is set to zero.

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
One or more arguments have incorrect values or are incompatible with other arguments.
The session handle pointer in the SessionHandle parameter cannot be NULL.
The Flags parameter contains the WINBIO_FLAG_RAW or the WINBIO_FLAG_MAINTENANCE flag and the caller has not been granted either access permission.
One or more of the biometric unit numbers specified in the UnitArray parameter is not valid.
The client application is running on a remote desktop client and is attempting to open a system pool session.
The PoolType parameter is set to WINBIO_POOL_PRIVATE and one or more of the requested sensors in that pool is not available.
Current administrative policy prohibits use of the Windows Biometric Framework API.


Requirement Value
Minimum supported client Windows 7 [desktop apps only]
Minimum supported server Windows Server 2008 R2 [desktop apps only]
Target Platform Windows
Header winbio.h (include Winbio.h)
Library Winbio.lib
DLL Winbio.dll

See also