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

Статья
03/03/2024

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

Синтаксис

PIBIO_ENGINE_EXPORT_ENGINE_DATA_FN PibioEngineExportEngineDataFn;

HRESULT PibioEngineExportEngineDataFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      WINBIO_BIR_DATA_FLAGS Flags,
  [out]     PWINBIO_BIR *SampleBuffer,
  [out]     PSIZE_T SampleSize
)
{...}

Параметры

[in, out] Pipeline

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

[in] Flags

Значение типа , указывающее свойства структуры WINBIO_BIR , возвращаемой подсистемой. Это может быть побитовое ИЛИ следующих флагов уровня безопасности и обработки:

WINBIO_DATA_FLAG_PRIVACY

Данные зашифрованы.

WINBIO_DATA_FLAG_INTEGRITY Данные подписываются цифровой подписью или защищаются с помощью кода проверки подлинности сообщения (MAC).
WINBIO_DATA_FLAG_SIGNED Если этот флаг и флаг WINBIO_DATA_FLAG_INTEGRITY установлены, данные подписываются. Если этот флаг не задан, но установлен флаг WINBIO_DATA_FLAG_INTEGRITY , вычисляется mac-файл.
WINBIO_DATA_FLAG_RAW Данные в формате, в котором они были записаны.
WINBIO_DATA_FLAG_INTERMEDIATE Данные не являются необработанными, но не были полностью обработаны.
WINBIO_DATA_FLAG_PROCESSED Данные обработаны.

[out] SampleBuffer

Адрес переменной, получающей указатель на структуру WINBIO_BIR , содержащую набор функций или шаблон.

[out] SampleSize

Указатель на переменную, содержащую размер в байтах структуры WINBIO_BIR , возвращаемой в параметре SampleBuffer .

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

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

Код возврата	Описание
E_INVALIDARG	Адаптер подсистемы не поддерживает сочетание флагов, указанных параметром Flags .
E_OUTOFMEMORY	Недостаточно памяти для создания структуры WINBIO_BIR .
E_POINTER	Обязательный параметр указателя — NULL.
WINBIO_E_INVALID_DEVICE_STATE	Конвейер не содержит тип данных, необходимых для параметра Flags .
E_NOTIMPL	Этот метод в настоящее время не реализован.

Необходимо выделить буфер, возвращаемый в параметре SampleBuffer из кучи процесса, с помощью функции HeapAlloc . После создания буфера он становится свойством Windows Biometric Framework. Так как платформа освобождает эту память после ее использования, реализация этой функции не должна пытаться освободить буфер или сохранить на него указатель. Не сохраняя указатель, вы запрещаете другим частям адаптера подсистемы пытаться использовать буфер после возврата этой функции.

Примеры

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

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterExportEngineData
//
// Purpose:
//      Retrieves a copy of the most recently processed feature set or template.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Flags           - Security and processing level flags
//      SampleBuffer    - Contains the feature set or template
//      SampleSize      - Size, in bytes, of the structure returned in the 
//                        SampleBuffer parameter.
//
static HRESULT
WINAPI
EngineAdapterExportEngineData(
    __inout PWINBIO_PIPELINE Pipeline,
    __in WINBIO_BIR_DATA_FLAGS Flags,
    __out PWINBIO_BIR *SampleBuffer,
    __out PSIZE_T SampleSize
    )
{
    HRESULT hr = S_OK;
    PWINBIO_BIR birAddress = NULL;
    SIZE_T birSize = 0;

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

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

    // At least one processing level flag must be set. Your adapter can also
    // place additional restrictions on supported export formats.
    if (Flags & (WINBIO_DATA_FLAG_RAW | 
                 WINBIO_DATA_FLAG_INTERMEDIATE | 
                 WINBIO_DATA_FLAG_PROCESSED) == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // You must implement the _CreateBirFromAdapterData function to extract
    // data from the engine context and create a new WINBIO_BIR structure. The
    // function passes ownership of the new biometric information record (BIR)
    // to the EngineAdapterExportEngineData routine which then passes the BIR
    // to the caller.
    hr = _CreateBirFromAdapterData( context, Flags, &birAddress, &birSize);
    if (SUCCEEDED(hr))
    {
        *SampleBuffer = birAddress;
        *SampleSize = birSize;
    }

cleanup:

    return hr;
}

Требования

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

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

EngineAdapterAcceptSampleData

Функции подключаемого модуля

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