функция обратного вызова PIBIO_ENGINE_COMMIT_ENROLLMENT_FN (winbio_adapter.h)

Статья
08/27/2023

Вызывается биометрической платформой Windows для завершения объекта регистрации, преобразования его в шаблон и сохранения шаблона в базе данных.

Синтаксис

PIBIO_ENGINE_COMMIT_ENROLLMENT_FN PibioEngineCommitEnrollmentFn;

HRESULT PibioEngineCommitEnrollmentFn(
  [in, out]      PWINBIO_PIPELINE Pipeline,
  [in]           PWINBIO_IDENTITY Identity,
  [in]           WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [in, optional] PUCHAR PayloadBlob,
  [in]           SIZE_T PayloadBlobSize
)
{...}

Параметры

[in, out] Pipeline

Указатель на структуру WINBIO_PIPELINE , связанную с биометрической единицей, выполняющей операцию.

[in] Identity

Указатель на структуру WINBIO_IDENTITY , содержащую GUID или идентификатор безопасности шаблона, который будет храниться в базе данных.

[in] SubFactor

Значение WINBIO_BIOMETRIC_SUBTYPE , указывающее подфактор, связанный с шаблоном, который будет храниться в базе данных.

[in, optional] PayloadBlob

Необязательный указатель на массив байтов, содержащий сигнатуру проверки, созданную с помощью Биометрической платформы Windows.

[in] PayloadBlobSize

Размер (в байтах) массива символов, на который указывает параметр PayloadBlob . Это значение должно быть равным нулю, если параметр PayloadBlob имеет значение NULL.

Возвращаемое значение

Если функция выполняется успешно, она возвращает S_OK. Если функция завершается сбоем, она должна вернуть одно из следующих значений HRESULT или любое значение, возвращаемое адаптером хранилища.

Код возврата	Описание
E_POINTER	Обязательным аргументом указателя является NULL.
E_INVALIDARG	Недопустимое значение, заданное параметром Identity или SubFactor .
WINBIO_E_DUPLICATE_ENROLLMENT	Шаблон, указанный параметрами Identity и SubFactor, уже сохраняется в базе данных.
WINBIO_E_INVALID_DEVICE_STATE	К конвейеру не подключен шаблон.

Если эта функция выполняется успешно, она должна очистить шаблон регистрации из конвейера. Результат этого действия должен быть эквивалентен вызову EngineAdapterClearContext.

Если эта функция завершается сбоем, она не должна изменять состояние контекста подсистемы. В частности, при наличии готового шаблона, присоединенного к конвейеру, необходимо повторно вызвать эту функцию (после устранения причин сбоя), чтобы зафиксировать шаблон в базе данных.

Адаптеры подсистемы, поддерживающие проверку подлинности перед загрузкой, должны фиксировать регистрацию не только в адаптере хранилища, подключенном к конвейеру, но и в области хранилища перед загрузкой. Сведения о том, как это необходимо сделать, предоставляются поставщику.

Важно

Не пытайтесь проверить значение, указанное для параметра SubFactor . Служба биометрических данных Windows проверит предоставленное значение перед его передачей в реализацию. Если значение равно WINBIO_SUBTYPE_NO_INFORMATION или WINBIO_SUBTYPE_ANY, проверьте, где это необходимо.

Примеры

В следующем псевдокоде показана одна из возможных реализаций этой функции. Пример не компилируется. Вы должны адаптировать его в соответствии с вашей целью.

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterCommitEnrollment
//
// Purpose:
//      Finalizes the enrollment object, converts it to a template, and saves 
//      the template in the database.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Identity        - GUID or SID of the template to be stored in the 
//                        database
//      SubFactor       - Sub-factor associated with the template to be stored
//                        in the database
//      PayloadBlob     - Optional pointer to an array of bytes that contain a 
//                        verification signature generated by the Windows Biometric
//                        Framework
//      PayloadBlobSize - Size, in bytes, of the character array pointed to by 
//                        the PayloadBlob parameter
//

static HRESULT
WINAPI
EngineAdapterCommitEnrollment(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in PUCHAR PayloadBlob,
    __in SIZE_T PayloadBlobSize
    )
{
    HRESULT hr = S_OK;
    DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_STORAGE_RECORD newTemplate = {0};

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(Identity))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    if (ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }
    
    if (!ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize > 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // TODO: Verify that the SubFactor and Identity arguments are valid.

    // Retrieve the context from the pipeline.
    PWINIBIO_ENGINE_CONTEXT context = 
        (PWINIBIO_ENGINE_CONTEXT)Pipeline->EngineContext;

    // Return if an enrollment is not in progress. This example assumes that 
    // an enrollment object is part of your engine context structure.
    if (context->Enrollment.InProgress != TRUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // If your adapter supports index vectors to place templates into buckets,
    // call a custom function (_AdapterCreateIndexVector) to create an index 
    // vector from the template data in the enrollment object.
    hr = _AdapterCreateIndexVector(
                context, 
                context->Enrollment.Template, 
                context->Enrollment.TemplateSize,
                indexVector, 
                NUMBER_OF_TEMPLATE_BINS, 
                &rejectDetail
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    newTemplate.Identity = Identity;
    newTemplate.SubFactor = SubFactor;
    newTemplate.IndexVector = indexVector;
    newTemplate.IndexElementCount = NUMBER_OF_TEMPLATE_BINS;
    newTemplate.TemplateBlob = context->Enrollment.Template;
    newTemplate.TemplateBlobSize = context->Enrollment.TemplateSize;
    newTemplate.PayloadBlob = PayloadBlob;
    newTemplate.PayloadBlobSize = PayloadBlobSize;

    hr = WbioStorageAddRecord(
                Pipeline,
                &newTemplate
                );

    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Call a custom function (_AdapterDestroyEnrollmentTemplate) to release
    // any resources held by the enrollment object.
    _AdapterDestroyEnrollmentTemplate(
        context,
        &context->Enrollment
        );

    // Specify that the enrollment process has been completed.
    context->Enrollment.InProgress = FALSE;

cleanup:

    return hr;
}

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 [только классические приложения]
Минимальная версия сервера	Windows Server 2008 R2 [только классические приложения]
Целевая платформа	Windows
Header	winbio_adapter.h (включая Winbio_adapter.h)

См. также раздел

EngineAdapterClearContext

Функции подключаемых модулей

Поделиться через