функция обратного вызова PIBIO_ENGINE_IDENTIFY_FEATURE_SET_FN (winbio_adapter.h)
Вызывается Платформой Биометрических данных Windows для создания шаблона из текущего набора функций и поиска соответствующего шаблона в базе данных. Если совпадение найдено, адаптер подсистемы должен заполнить параметры Identity, SubFactor, PayloadBlob соответствующими сведениями из сохраненного шаблона.
Синтаксис
PIBIO_ENGINE_IDENTIFY_FEATURE_SET_FN PibioEngineIdentifyFeatureSetFn;
HRESULT PibioEngineIdentifyFeatureSetFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[out] PWINBIO_IDENTITY Identity,
[out] PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
[out] PUCHAR *PayloadBlob,
[out] PSIZE_T PayloadBlobSize,
[out] PUCHAR *HashValue,
[out] PSIZE_T HashSize,
[out] PWINBIO_REJECT_DETAIL RejectDetail
)
{...}
Параметры
[in, out] Pipeline
Указатель на WINBIO_PIPELINE структуру, связанную с биометрической единицей, выполняющей операцию.
[out] Identity
Указатель на структуру WINBIO_IDENTITY , содержащую ИДЕНТИФИКАТОР GUID или ИДЕНТИФИКАТОР шаблона, восстановленного из базы данных. Это значение возвращается только в том случае, если найдено совпадение.
[out] SubFactor
Значение WINBIO_BIOMETRIC_SUBTYPE , которое получает подфактор, связанный с шаблоном в базе данных. Дополнительные сведения см. в разделе "Примечания". Это значение возвращается только в том случае, если найдено совпадение.
[out] PayloadBlob
Адрес переменной, получающей указатель на полезные данные, сохраненные с помощью шаблона. Если полезные данные отсутствуют, присвойте этому значению значение NULL.
[out] PayloadBlobSize
Указатель на переменную, которая получает размер (в байтах) буфера, заданного параметром PayloadBlob . Если полезные данные отсутствуют, задайте для этого значения нулевое значение.
[out] HashValue
Адрес переменной, получающей указатель на созданное хэш-значение для шаблона. Если адаптер обработчика не поддерживает создание хэша, присвойте этому значению значение NULL.
[out] HashSize
Указатель на переменную, которая получает размер (в байтах) буфера, заданного параметром HashValue . Если адаптер обработчика не поддерживает создание хэша, задайте для этого значения нулевое значение.
[out] RejectDetail
Указатель на переменную, которая получает дополнительные сведения, если сбой записи не позволяет подсистеме выполнить операцию сопоставления. Если последняя запись выполнена успешно, задайте для этого параметра нулевое значение. Для захвата отпечатков пальцев определяются следующие значения:
- 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 , чтобы указать на ошибку.
| Код возврата | Описание |
|---|---|
|
Параметр Pipeline имеет значение NULL. |
|
Набор функций не соответствовал внутренним требованиям адаптера подсистемы для операции идентификации. Дополнительные сведения о сбое указываются параметром RejectDetail . |
|
Набор компонентов в конвейере не соответствует ни одному удостоверению в базе данных. |
Комментарии
Алгоритм, используемый для создания хэша шаблона, — это алгоритм, выбранный последним вызовом в этом конвейере в EngineAdapterSetHashAlgorithm.
Хэш-значение, возвращаемое этой функцией, если таковое имеется, — это хэш шаблона регистрации, найденного в базе данных, а не соответствующего шаблона, присоединенного к конвейеру.
Буферы PayloadBlob и HashValue принадлежат адаптеру подсистемы и управляются ими после успешного возврата функции EngineAdapterIdentifyFeatureSet . Адаптер подсистемы должен поддерживать допустимый адрес буфера для этого конвейера до следующего вызова EngineAdapterClearContext.
Примеры
В следующем псевдокоде показана одна из возможных реализаций этой функции. Пример не компилируется. Вы должны адаптировать его в соответствии с вашей целью.
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterIdentifyFeatureSet
//
// Purpose:
// Build a template from the current feature set and locate a matching
// template in the database.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation
// Identity - The GUID or SID of the template recovered from the
// database
// SubFactor - Sub-factor associated with the template in the
// database
// PayloadBlob - Payload data saved with the template
// PayloadBlobSize - Size, in bytes, of the buffer specified by the
// PayloadBlob parameter.
// HashValue - Hash value for the template
// HashSize - Size, in bytes, of the buffer specified by the
// HashValue parameter.
// RejectDetail - Receives additional information if a capture
// failure prevents the engine from performing a matching
// operation.
//
static HRESULT
WINAPI
EngineAdapterIdentifyFeatureSet(
__inout PWINBIO_PIPELINE Pipeline,
__out PWINBIO_IDENTITY Identity,
__out PWINBIO_BIOMETRIC_SUBTYPE SubFactor,
__out PUCHAR *PayloadBlob,
__out PSIZE_T PayloadBlobSize,
__out PUCHAR *HashValue,
__out PSIZE_T HashSize,
__out PWINBIO_REJECT_DETAIL RejectDetail
)
{
HRESULT hr = S_OK;
SIZE_T recordCount = 0;
SIZE_T index = 0;
WINBIO_STORAGE_RECORD thisRecord;
BOOLEAN match = FALSE;
DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(Identity) ||
!ARGUMENT_PRESENT(SubFactor) ||
!ARGUMENT_PRESENT(PayloadBlob) ||
!ARGUMENT_PRESENT(PayloadBlobSize) ||
!ARGUMENT_PRESENT(HashValue) ||
!ARGUMENT_PRESENT(HashSize) ||
!ARGUMENT_PRESENT(RejectDetail))
{
hr = E_POINTER;
goto cleanup;
}
// Retrieve the context from the pipeline.
PWINBIO_ENGINE_CONTEXT context =
(PWINBIO_ENGINE_CONTEXT)Pipeline->EngineContext;
// Initialize the return values.
ZeroMemory( Identity, sizeof(WINBIO_IDENTITY));
Identity->Type = WINBIO_ID_TYPE_NULL;
*SubFactor = WINBIO_SUBTYPE_NO_INFORMATION;
*PayloadBlob = NULL;
*PayloadBlobSize = 0;
*HashValue = NULL;
*HashSize = 0;
*RejectDetail = 0;
// The biometric unit cannot perform verification or identification
// operations while it is performing an enrollment sequence.
if (context->Enrollment.InProgress == TRUE)
{
hr = WINBIO_E_ENROLLMENT_IN_PROGRESS;
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 feature set. In this example, the
// engine adapter context attached to the pipeline contains a FeatureSet
// member.
hr = _AdapterCreateIndexVector(
context,
context->FeatureSet,
context->FeatureSetSize,
indexVector,
NUMBER_OF_TEMPLATE_BINS,
RejectDetail
);
if (FAILED(hr))
{
goto cleanup;
}
// Retrieve the records in the index vector. If your adapter does not support
// index vectors (the vector length is zero), calling the WbioStorageQueryByContent
// function will retrieve all records.
// WbioStorageQueryByContent is a wrapper function in the Winbio_adapter.h
// header file.
hr = WbioStorageQueryByContent(
Pipeline,
WINBIO_SUBTYPE_ANY,
indexVector,
NUMBER_OF_TEMPLATE_BINS
);
if (FAILED(hr))
{
goto cleanup;
}
// Determine the size of the result set. WbioStorageGetRecordCount is a wrapper
// function in the Winbio_adapter.h header file.
hr = WbioStorageGetRecordCount( Pipeline, &recordCount);
if (FAILED(hr))
{
goto cleanup;
}
// Point the result set cursor at the first record. WbioStorageFirstRecord
// is a wrapper function in the Winbio_adapter.h header file.
hr = WbioStorageFirstRecord( Pipeline );
if (FAILED(hr))
{
goto cleanup;
}
// Iterate through all records in the result set and determine which record
// matches the current feature set. WbioStorageGetCurrentRecord is a wrapper
// function in the Winbio_adapter.h header file.
for (index = 0; index < recordCount; ++index)
{
hr = WbioStorageGetCurrentRecord( Pipeline, &thisRecord );
if (FAILED(hr))
{
goto cleanup;
}
// Call a custom function (_AdapterCompareTemplateToCurrentFeatureSet) to
// compare the feature set attached to the pipeline with the template
// retrieved from storage.
// If the template and feature set do not match, return WINBIO_E_NO_MATCH
// and set the Match parameter to FALSE.
// If your custom function cannot process the feature set, return
// WINBIO_E_BAD_CAPTURE and set extended error information in the
// RejectDetail parameter.
hr = _AdapterCompareTemplateToCurrentFeatureSet(
context,
context->FeatureSet,
context->FeatureSetSize,
thisRecord.TemplateBlob,
thisRecord.TemplateBlobSize,
&match,
RejectDetail
);
if (FAILED(hr) && hr != WINBIO_E_NO_MATCH)
{
goto cleanup;
}
if (match)
{
break;
}
hr = WbioStorageNextRecord( Pipeline );
if (FAILED(hr))
{
if (hr == WINBIO_E_DATABASE_NO_MORE_RECORDS)
{
hr = S_OK;
break;
}
else
{
goto cleanup;
}
}
}
if (match)
{
// If there is a match and if your engine adapter supports template
// hashing, call a custom function (_AdapterGenerateHashForTemplate)
// to calculate the hash. Save the hash value in the context area of
// the engine adapter.
// Skip this step if your adapter does not support template hashing.
hr = _AdapterGenerateHashForTemplate(
context,
thisRecord.TemplateBlob,
thisRecord.TemplateBlobSize,
context->HashBuffer,
&context->HashSize
);
if (FAILED(hr))
{
goto cleanup;
}
// Return information about the matching template to the caller.
CopyMemory( Identity, thisRecord.Identity, sizeof(WINBIO_IDENTITY));
*SubFactor = thisRecord.SubFactor;
*PayloadBlob = thisRecord.PayloadBlob;
*PayloadBlobSize = thisRecord.PayloadBlobSize;
*HashValue = &context->HashBuffer;
*HashSize = context->HashSize;
}
else
{
hr = WINBIO_E_UNKNOWN_ID;
}
cleanup:
if (hr == WINBIO_E_DATABASE_NO_RESULTS)
{
hr = WINBIO_E_UNKNOWN_ID;
}
return hr;
}
Требования
| Минимальная версия клиента | Windows 7 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 R2 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbio_adapter.h (включая Winbio_adapter.h) |