WinBioEnrollBegin function

Initiates a biometric enrollment sequence and creates an empty biometric template.

Syntax


HRESULT WINAPI WinBioEnrollBegin(
  _In_  WINBIO_SESSION_HANDLE SessionHandle,
  _In_  WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  _In_  WINBIO_UNIT_ID UnitId
);

Parameters

SessionHandle [in]

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.

SubFactor [in]

A WINBIO_BIOMETRIC_SUBTYPE value that provides additional information about the enrollment. This must be one of the following values:

  • WINBIO_ANSI_381_POS_RH_THUMB
  • WINBIO_ANSI_381_POS_RH_INDEX_FINGER
  • WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
  • WINBIO_ANSI_381_POS_RH_RING_FINGER
  • WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
  • WINBIO_ANSI_381_POS_LH_THUMB
  • WINBIO_ANSI_381_POS_LH_INDEX_FINGER
  • WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
  • WINBIO_ANSI_381_POS_LH_RING_FINGER
  • WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
  • WINBIO_ANSI_381_POS_RH_FOUR_FINGERS
  • WINBIO_ANSI_381_POS_LH_FOUR_FINGERS
UnitId [in]

A WINBIO_UNIT_ID value that identifies the biometric unit. This value cannot be zero. You can find a unit ID by calling the WinBioEnumBiometricUnits or WinBioLocateSensor functions.

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_ACCESSDENIED

The caller does not have permission to enroll.

E_HANDLE

The session handle is not valid.

E_INVALIDARG

The SubFactor parameter cannot equal WINBIO_SUBTYPE_NO_INFORMATION or WINBIO_SUBTYPE_ANY, and the UnitId parameter cannot equal zero.

WINBIO_E_ENROLLMENT_IN_PROGRESS

An enrollment operation is already in progress, and only one enrollment can occur at a given time.

WINBIO_E_LOCK_VIOLATION

The biometric unit is in use and is locked.

 

Remarks

A single biometric enrollment requires the collection of multiple samples from a user. Only one enrollment operation can take place at any time, and all of the biometric samples that apply to a single enrollment must be generated by the same sensor. This sensor is specified by the UnitId parameter.

Any application that enrolls by using a biometric unit in the system pool must have window focus when it calls WinBioEnrollBegin. If it does not, the call blocks until the application acquires window focus and the user has provided a biometric sample. We recommend, therefore, that your application not call WinBioEnrollBegin until it has acquired focus. The manner in which you acquire focus depends on the type of application you are writing. For example, if you are creating a GUI application you can implement a message handler that captures a WM_ACTIVATE, WM_SETFOCUS, or other appropriate message. If you are writing a CUI application, call GetConsoleWindow to retrieve a handle to the console window and pass that handle to the SetForegroundWindow function to force the console window into the foreground and assign it focus. If your application is running in a detached process and has no window or is a Windows service, use WinBioAcquireFocus and WinBioReleaseFocus to manually control focus.

To use WinBioEnrollBegin synchronously, call the function with a session handle created by calling WinBioOpenSession. The function blocks until the operation completes or an error is encountered.

To use WinBioEnrollBegin asynchronously, call the function with a session handle created by calling WinBioAsyncOpenSession. The framework allocates a WINBIO_ASYNC_RESULT structure and uses it to return information about operation success or failure. If the operation is successful, the framework returns WINBIO_BIOMETRIC_SUBTYPE information in a nested EnrollBegin structure. If the operation is unsuccessful, the framework returns error information. The WINBIO_ASYNC_RESULT structure is returned to the application callback or to the application message queue, depending on the value you set in the NotificationMethod parameter of the WinBioAsyncOpenSession function:

  • If you choose to receive completion notices by using a callback, you must implement a PWINBIO_ASYNC_COMPLETION_CALLBACK function and set the NotificationMethod parameter to WINBIO_ASYNC_NOTIFY_CALLBACK.
  • If you choose to receive completion notices by using the application message queue, you must set the NotificationMethod parameter to WINBIO_ASYNC_NOTIFY_MESSAGE. The framework returns a WINBIO_ASYNC_RESULT pointer to the LPARAM field of the window message.

To prevent memory leaks, you must call WinBioFree to release the WINBIO_ASYNC_RESULT structure after you have finished using it.

Examples

The following function enrolls a biometric template in the system pool. It calls WinBioEnrollBegin to start the enrollment sequence. Link to the Winbio.lib static library and include the following header files:

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

HRESULT EnrollSysPool(
                      BOOL discardEnrollment, 
                      WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    BOOLEAN isNewTemplate = TRUE;

    // 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. ");
        wprintf_s(L"hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Locate a sensor.
    wprintf_s(L"\n Swipe your finger on the sensor...\n");
    hr = WinBioLocateSensor( sessionHandle, &unitId);
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Begin the enrollment sequence. 
    wprintf_s(L"\n Starting enrollment sequence...\n");
    hr = WinBioEnrollBegin(
            sessionHandle,      // Handle to open biometric session
            subFactor,          // Finger to create template for
            unitId              // Biometric unit ID
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioEnrollBegin failed. hr = 0x%x\n", hr);
        goto e_Exit;
    }

    // Capture enrollment information by swiping the sensor with
    // the finger identified by the subFactor argument in the 
    // WinBioEnrollBegin function.
    for (int swipeCount = 1;; ++swipeCount)
    {
        wprintf_s(L"\n Swipe the sensor to capture %s sample.",
                 (swipeCount == 1)?L"the first":L"another");

        hr = WinBioEnrollCapture(
                sessionHandle,  // Handle to open biometric session
                &rejectDetail   // [out] Failure information
                );

        wprintf_s(L"\n Sample %d captured from unit number %d.", 
                  swipeCount, 
                  unitId);

        if (hr == WINBIO_I_MORE_DATA)
        {
            wprintf_s(L"\n    More data required.\n");
            continue;
        }
        if (FAILED(hr))
        {
            if (hr == WINBIO_E_BAD_CAPTURE)
            {
                wprintf_s(L"\n  Error: Bad capture; reason: %d", 
                          rejectDetail);
                continue;
            }
            else
            {
                wprintf_s(L"\n WinBioEnrollCapture failed. hr = 0x%x", hr);
                goto e_Exit;
            }
        }
        else
        {
            wprintf_s(L"\n    Template completed.\n");
            break;
        }
    }

    // Discard the enrollment if the appropriate flag is set.
    // Commit the enrollment if it is not discarded.
    if (discardEnrollment == TRUE)
    {
        wprintf_s(L"\n Discarding enrollment...\n\n");
        hr = WinBioEnrollDiscard( sessionHandle );
        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
        }
        goto e_Exit;    
    }
    else
    {
        wprintf_s(L"\n Committing enrollment...\n");
        hr = WinBioEnrollCommit( 
                sessionHandle,      // Handle to open biometric session
                &identity,          // WINBIO_IDENTITY object for the user
                &isNewTemplate);    // Is this a new template

        if (FAILED(hr))
        {
            wprintf_s(L"\n WinBioEnrollCommit failed. hr = 0x%x\n", hr);
            goto e_Exit;
        }
    }


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

    wprintf_s(L" Press any key to continue...");
    _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

WinBioAcquireFocus
WinBioEnrollCapture
WinBioEnrollCaptureWithCallback
WinBioEnrollCommit
WinBioEnrollDiscard
WinBioReleaseFocus

 

 

Community Additions

ADD
Show:
© 2014 Microsoft