WinBioDeleteTemplate

WinBioDeleteTemplate function

Deletes a biometric template from the template store.

Syntax


HRESULT WINAPI WinBioDeleteTemplate(
  _In_ WINBIO_SESSION_HANDLE    SessionHandle,
  _In_ WINBIO_UNIT_ID           UnitId,
  _In_ WINBIO_IDENTITY          *Identity,
  _In_ WINBIO_BIOMETRIC_SUBTYPE SubFactor
);

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.

UnitId [in]

A WINBIO_UNIT_ID value that identifies the biometric unit where the template is located.

Identity [in]

Pointer to a WINBIO_IDENTITY structure that contains the GUID or SID of the template to be deleted. If the Type member of the WINBIO_IDENTITY structure is WINBIO_ID_TYPE_WILDCARD, templates matching the SubFactor parameter will be deleted for all identities. Only administrators can perform wildcard identity deletion.

SubFactor [in]

A WINBIO_BIOMETRIC_SUBTYPE value that provides additional information about the template to be deleted. If you specify WINBIO_SUBTYPE_ANY, all templates for the biometric unit specified by the UnitId parameter are deleted.

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_HANDLE

The session handle is not valid.

E_INVALIDARG

The UnitId parameter contains zero or the SubFactor contains WINBIO_SUBTYPE_NO_INFORMATION.

E_POINTER

The pointer specified in the Identity parameter cannot be NULL.

WINBIO_E_ENROLLMENT_IN_PROGRESS

The operation could not be completed because the biometric unit is currently being used for an enrollment transaction.

 

Remarks

To use WinBioDeleteTemplate 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 WinBioDeleteTemplate 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 deletion operation is successful, the framework returns WINBIO_IDENTITY and WINBIO_BIOMETRIC_SUBTYPE information in a nested DeleteTemplate 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 code example calls WinBioDeleteTemplate to delete a specific biometric template. Link to the Winbio.lib static library and include the following header files:

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

HRESULT DeleteTemplate(WINBIO_BIOMETRIC_SUBTYPE subFactor)
{
    HRESULT hr = S_OK;
    WINBIO_IDENTITY identity = {0};
    WINBIO_SESSION_HANDLE sessionHandle = NULL;
    WINBIO_UNIT_ID unitId = 0;

    // Find the identity of the user.
    hr = GetCurrentUserIdentity( &identity );
    if (FAILED(hr))
    {
        wprintf_s(L"\n User identity not found. hr = 0x%x\n", hr);
        goto e_Exit;
    }

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

    // Locate the 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;
    }

    // Delete the template identified by the subFactor argument.
    //
    hr = WinBioDeleteTemplate(
            sessionHandle,
            unitId,
            &identity,
            subFactor
            );
    if (FAILED(hr))
    {
        wprintf_s(L"\n WinBioDeleteTemplate 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 exit...");
    _getch();

    return hr;
}

//------------------------------------------------------------------------
// The following function retrieves the identity of the current user.
// This is a helper function and is not part of the Windows Biometric
// Framework API.
//
HRESULT GetCurrentUserIdentity(__inout PWINBIO_IDENTITY Identity)
{
    // Declare variables.
    HRESULT hr = S_OK;
    HANDLE tokenHandle = NULL;
    DWORD bytesReturned = 0;
    struct{
        TOKEN_USER tokenUser;
        BYTE buffer[SECURITY_MAX_SID_SIZE];
    } tokenInfoBuffer;

    // Zero the input identity and specify the type.
    ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
    Identity->Type = WINBIO_ID_TYPE_NULL;

    // Open the access token associated with the
    // current process
    if (!OpenProcessToken(
            GetCurrentProcess(),            // Process handle
            TOKEN_READ,                     // Read access only
            &tokenHandle))                  // Access token handle
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot open token handle: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // Zero the tokenInfoBuffer structure.
    ZeroMemory(&tokenInfoBuffer, sizeof(tokenInfoBuffer));

    // Retrieve information about the access token. In this case,
    // retrieve a SID.
    if (!GetTokenInformation(
            tokenHandle,                    // Access token handle
            TokenUser,                      // User for the token
            &tokenInfoBuffer.tokenUser,     // Buffer to fill
            sizeof(tokenInfoBuffer),        // Size of the buffer
            &bytesReturned))                // Size needed
    {
        DWORD win32Status = GetLastError();
        wprintf_s(L"Cannot query token information: %d\n", win32Status);
        hr = HRESULT_FROM_WIN32(win32Status);
        goto e_Exit;
    }

    // Copy the SID from the tokenInfoBuffer structure to the
    // WINBIO_IDENTITY structure. 
    CopySid(
        SECURITY_MAX_SID_SIZE,
        Identity->Value.AccountSid.Data,
        tokenInfoBuffer.tokenUser.User.Sid
        );

    // Specify the size of the SID and assign WINBIO_ID_TYPE_SID
    // to the type member of the WINBIO_IDENTITY structure.
    Identity->Value.AccountSid.Size = GetLengthSid(tokenInfoBuffer.tokenUser.User.Sid);
    Identity->Type = WINBIO_ID_TYPE_SID;

e_Exit:

    if (tokenHandle != NULL)
    {
        CloseHandle(tokenHandle);
    }

    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

 

 

Show:
© 2016 Microsoft