функция обратного вызова PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN (winbio_adapter.h)
Вызывается функцией SensorAdapterPushDataToEngine , реализованной адаптером датчика для уведомления адаптера подсистемы о приеме необработанной биометрической выборки и извлечении набора функций. Набор функций можно использовать для сопоставления или регистрации.
Синтаксис
PIBIO_ENGINE_ACCEPT_SAMPLE_DATA_FN PibioEngineAcceptSampleDataFn;
HRESULT PibioEngineAcceptSampleDataFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[in] PWINBIO_BIR SampleBuffer,
[in] SIZE_T SampleSize,
[in] WINBIO_BIR_PURPOSE Purpose,
[out] PWINBIO_REJECT_DETAIL RejectDetail
)
{...}
Параметры
[in, out] Pipeline
Указатель на WINBIO_PIPELINE структуру, связанную с биометрической единицей, выполняющей операцию.
[in] SampleBuffer
Указатель на структуру WINBIO_BIR , которая содержит обрабатываемую биометрическую выборку.
[in] SampleSize
Значение SIZE_T , содержащее размер структуры WINBIO_BIR , возвращенной в параметре SampleBuffer .
[in] Purpose
Битовая маска WINBIO_BIR_PURPOSE, указывающая предполагаемое использование образца. Структура WINBIO_BIR_PURPOSE указывает цель, для которой требуется использовать данные записи, и (как результат) способ их оптимизации. Это может быть побитовое ИЛИ следующих значений:
- WINBIO_PURPOSE_VERIFY
- WINBIO_PURPOSE_IDENTIFY
- WINBIO_PURPOSE_ENROLL
- WINBIO_PURPOSE_ENROLL_FOR_VERIFICATION
- WINBIO_PURPOSE_ENROLL_FOR_IDENTIFICATION
[out] RejectDetail
Указатель на WINBIO_REJECT_DETAIL значение, которое получает дополнительные сведения о невозможности обработки биометрической выборки. Если операция выполнена успешно, для этого параметра устанавливается нулевое значение. Для образцов отпечатков пальцев определены следующие значения:
- WINBIO_FP_TOO_HIGH
- WINBIO_FP_TOO_LOW
- WINBIO_FP_TOO_LEFT
- WINBIO_FP_TOO_RIGHT
- WINBIO_FP_TOO_FAST
- WINBIO_FP_TOO_SLOW
- WINBIO_FP_POOR_QUALITY
- WINBIO_FP_TOO_SKEWED
- WINBIO_FP_TOO_SHORT
- WINBIO_FP_MERGE_FAILURE
Возвращаемое значение
Если функция завершается успешно, она возвращает S_OK. Если функция завершается сбоем, она должна вернуть одно из следующих значений HRESULT , чтобы указать на ошибку.
| Код возврата | Описание |
|---|---|
|
Аргумент SampleSize не может быть равен нулю. Аргумент Цель должен быть побитовой ИЛИ значений, перечисленных в описании параметра. |
|
Аргументы Pipeline, SampleBuffer и RejectDetail не могут иметь значение NULL. |
|
Не удалось завершить операцию из-за нехватки памяти. |
|
Не удалось обработать данные для создания требуемого набора функций. RejectDetail содержит дополнительные сведения о сбое. |
Комментарии
Набор функций, созданный путем вызова этой функции, сохраняется в конвейере биометрических единиц после возврата функции. Он заменяет все предыдущие наборы функций.
Реализация адаптера датчика функции SensorAdapterPushDataToEngine должна использовать следующую функцию-оболочку (определенную в Winbio_adapter.h) для вызова EngineAdapterAcceptSampleData:
HRESULT WbioEngineAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
);
Структура WINBIO_BIR , передаваемая в параметре SampleBuffer , является свойством адаптера датчика. Поскольку адаптер датчика управляет временем существования объекта WINBIO_BIR , функция EngineAdapterAcceptSampleData не должна пытаться освободить структуру или сохранить на нее указатель. Не сохраняя указатель, вы предотвращаете попытки других частей адаптера подсистемы использовать структуру WINBIO_BIR после возврата функции EngineAdapterAcceptSampleData .
Если поле Offset элемента StandardDataBlock структуры WINBIO_BIR больше нуля (что указывает на то, что BIR содержит биометрическую выборку в стандартном формате данных), поле BiometricDataFormat элемента HeaderBlock должно быть задано следующим образом:
- Поле Владелец должно быть WINBIO_ ANSI_381_FORMAT_OWNER.
- Поле Тип должно быть WINBIO_ANSI_381_FORMAT_TYPE.
В Windows Biometric Framework также предполагается, что элемент HeaderBlock ( структура WINBIO_BIR_HEADER ) содержит значения DataFlags и Purpose , используемые адаптером датчика для записи образца.
Датчики отпечатков пальцев, обрабатывающие образцы отпечатков пальцев и отклоняющие недопустимые прокрутки в адаптере подсистемы, также должны использовать допустимые значения для WINBIO_BIR_PURPOSE.
Примеры
В следующем псевдокоде показана одна из возможных реализаций этой функции. Пример не компилируется. Вы должны адаптировать его в соответствии с вашей целью.
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterAcceptSampleData
//
// Purpose:
// Notifies the engine adapter to accept a raw biometric sample and
// extract a feature set.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation.
// SampleBuffer - Contains the biometric sample to be processed.
// SampleSize - Size of the structure returned in the SampleBuffer
// parameter.
// Purpose - Specifies the intended use of the sample.
// RejectDetail - Receives additional information about the failure,
// if any, to process a biometric sample.
//
static HRESULT
WINAPI
EngineAdapterAcceptSampleData(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_BIR SampleBuffer,
__in SIZE_T SampleSize,
__in WINBIO_BIR_PURPOSE Purpose,
__out PWINBIO_REJECT_DETAIL RejectDetail
)
{
HRESULT hr = S_OK;
PUCHAR featureSet = NULL;
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(SampleBuffer) ||
!ARGUMENT_PRESENT(RejectDetail))
{
hr = E_POINTER;
goto cleanup;
}
// Retrieve the context from the pipeline.
PWINBIO_ENGINE_CONTEXT context =
(PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;
// Verify that input arguments are valid.
if (SampleSize == 0 ||
Purpose == WINBIO_NO_PURPOSE_AVAILABLE)
{
hr = E_INVALIDARG;
goto cleanup;
}
// Release any feature set currently attached to the pipeline before
// creating a new feature set.
if (context->FeatureSet != NULL)
{
_AdapterRelease(context->FeatureSet);
context->FeatureSet = NULL;
context->FeatureSetSize = 0;
}
// An actual engine adapter would here process the contents of the sample
// buffer, generate a feature set suitable for the purpose(s) specified
// by the Purpose parameter, and attach the feature set to the pipeline.
// The following trivial example, however, creates a feature set simply
// by making an exact copy of the raw sample.
// If the sample data cannot be processed, return an HRESULT error code
// of WINBIO_E_BAD_CAPTURE and set extended error information in the
// RejectDetail parameter.
featureSet = (PUCHAR)_AdapterAlloc(SampleSize);
if (featureSet == NULL)
{
hr = E_OUTOFMEMORY;
goto cleanup;
}
RtlCopyMemory(featureSet, SampleBuffer, SampleSize);
context->FeatureSet = featureSet;
featureSet = NULL;
context->FeatureSetSize = SampleSize;
cleanup:
if (FAILED(hr))
{
if (featureSet != NULL)
{
_AdapterRelease(featureSet);
}
}
return hr;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 7 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 R2 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbio_adapter.h (включая Winbio_adapter.h) |