Export (0) Print
Expand All

WinBioOpenSession function

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

Syntax


HRESULT WINAPI WinBioOpenSession(
  _In_   WINBIO_BIOMETRIC_TYPE Factor,
  _In_   WINBIO_POOL_TYPE PoolType,
  _In_   WINBIO_SESSION_FLAGS Flags,
  _In_   WINBIO_UNIT_ID *UnitArray,
  _In_   SIZE_T UnitCount,
  _In_   GUID *DatabaseId,
  _Out_  WINBIO_SESSION_HANDLE *SessionHandle
);

Parameters

Factor [in]

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

PoolType [in]

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:

ValueMeaning
WINBIO_POOL_SYSTEM

The session connects to a shared collection of biometric units managed by the service provider.

WINBIO_POOL_PRIVATE

The session connects to a collection of biometric units that are managed by the caller.

 

Flags [in]

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.

ValueMeaning
WINBIO_FLAG_DEFAULT

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.

WINBIO_FLAG_BASIC

Group: configuration

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

WINBIO_FLAG_ADVANCED

Group: configuration

The biometric units use internal processing and storage capabilities.

WINBIO_FLAG_RAW

Group: access

The client application captures raw biometric data using WinBioCaptureSample.

WINBIO_FLAG_MAINTENANCE

Group: access

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

 

UnitArray [in]

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.

UnitCount [in]

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.

DatabaseId [in]

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.

ValueMeaning
WINBIO_DB_DEFAULT

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

WINBIO_DB_BOOTSTRAP

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.

WINBIO_DB_ONCHIP

The database is on the sensor chip and is available for enrollment and matching.

 

SessionHandle [out]

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 codeDescription
E_INVALIDARG

One or more arguments have incorrect values or are incompatible with other arguments.

E_POINTER

The session handle pointer in the SessionHandle parameter cannot be NULL.

E_ACCESSDENIED

The Flags parameter contains the WINBIO_FLAG_RAW or the WINBIO_FLAG_MAINTENANCE flag and the caller has not been granted either access permission.

WINBIO_E_INVALID_UNIT

One or more of the biometric unit numbers specified in the UnitArray parameter is not valid.

WINBIO_E_NOT_ACTIVE_CONSOLE

The client application is running on a remote desktop client and is attempting to open a system pool session.

WINBIO_E_SENSOR_UNAVAILABLE

The PoolType parameter is set to WINBIO_POOL_PRIVATE and one or more of the requested sensors in that pool is not available.

WINBIO_E_DISABLED

Current administrative policy prohibits use of the Windows Biometric Framework API.

 

Examples

The following function shows how to call WinBioOpenSession to connect to the system pool and open a biometric session. Link to the Winbio.lib static library and include the following header files:

  • Windows.h
  • Stdio.h
  • Conio.h
  • Winbio.h

HRESULT EnumEnrollments( )
{
    // Declare variables.
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    PWINBIO_BIOMETRIC_SUBTYPE subFactorArray = NULL;
    WINBIO_BIOMETRIC_SUBTYPE SubFactor = 0;
    SIZE_T subFactorCount = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_BIOMETRIC_SUBTYPE subFactor = WINBIO_SUBTYPE_NO_INFORMATION;

    // Connect to the system pool. 
    hr = WinBioOpenSession( 
            WINBIO_TYPE_FINGERPRINT,    // Service provider
            WINBIO_POOL_SYSTEM,         // Pool type
            WINBIO_FLAG_DEFAULT,        // Configuration and access
            NULL,                       // Array of biometric unit IDs
            0,                          // Count of biometric unit IDs
            NULL,                       // Database ID
            &sessionHandle              // [out] Session handle
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioOpenSession failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate the biometric sensor and retrieve a WINBIO_IDENTITY object.
    wprintf_s(L"\n Calling WinBioIdentify - Swipe finger on sensor...\n");
    hr = WinBioIdentify( 
            sessionHandle,              // Session handle
            &unitId,                    // Biometric unit ID
            &identity,                  // User SID
            &subFactor,                 // Finger sub factor
            &rejectDetail               // Rejection information
            );
    wprintf_s(L"\n Swipe processed - Unit ID: %d\n", unitId);
    if (FAILED(hr))
    {
        if (hr == WINBIO_E_UNKNOWN_ID)
        {
            wprintf_s(L"\n Unknown identity.\n");
        }
        else if (hr == WINBIO_E_BAD_CAPTURE)
        {
            wprintf_s(L"\n Bad capture; reason: %d\n", rejectDetail);
        }
        else
        {
            wprintf_s(L"\n WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;
    }

    // Retrieve the biometric sub-factors for the template.
    hr = WinBioEnumEnrollments( 
            sessionHandle,              // Session handle
            unitId,                     // Biometric unit ID
            &identity,                  // Template ID
            &subFactorArray,            // Subfactors
            &subFactorCount             // Count of subfactors
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnumEnrollments failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Print the sub-factor(s) to the console.
    wprintf_s(L"\n Enrollments for this user on Unit ID %d:", unitId);
    for (SIZE_T index = 0; index < subFactorCount; ++index)
    {
        SubFactor = subFactorArray[index];
        switch (SubFactor)
        {
            case WINBIO_ANSI_381_POS_RH_THUMB:
                wprintf_s(L"\n   RH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_RH_INDEX_FINGER:
                wprintf_s(L"\n   RH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER:
                wprintf_s(L"\n   RH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_RING_FINGER:
                wprintf_s(L"\n   RH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_RH_LITTLE_FINGER:
                wprintf_s(L"\n   RH little finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_THUMB:
                wprintf_s(L"\n   LH thumb\n");
                break;
            case WINBIO_ANSI_381_POS_LH_INDEX_FINGER:
                wprintf_s(L"\n   LH index finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER:
                wprintf_s(L"\n   LH middle finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_RING_FINGER:
                wprintf_s(L"\n   LH ring finger\n");
                break;
            case WINBIO_ANSI_381_POS_LH_LITTLE_FINGER:
                wprintf_s(L"\n   LH little finger\n");
                break;
            default:
                wprintf_s(L"\n   The sub-factor is not correct\n");
                break;
        }
 
    }

e_Exit:
    if (subFactorArray!= NULL)
    {
        WinBioFree(subFactorArray);
        subFactorArray = NULL;
    }

    if (sessionHandle != NULL)
    {
        WinBioCloseSession(sessionHandle);
        sessionHandle = NULL;
    }

    wprintf_s(L"\n Press any key to exit...");
    _getch();

    return hr;
}



Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winbio.h (include Winbio.h)

Library

Winbio.lib

DLL

Winbio.dll

See also

WinBioCloseSession

 

 

Community Additions

ADD
Show:
© 2015 Microsoft