функция обратного вызова PIBIO_ENGINE_VERIFY_FEATURE_SET_FN (winbio_adapter.h)
Вызывается платформой Биометрических данных Windows для сравнения шаблона в текущем наборе функций с определенным шаблоном в базе данных. Если шаблоны эквивалентны, адаптер подсистемы должен задать для логического значения, на которое указывает параметр Match значение TRUE, вернуть соответствующий шаблон в параметре PayloadBlob и возвратить хэш шаблона в параметре HashValue .
Синтаксис
PIBIO_ENGINE_VERIFY_FEATURE_SET_FN PibioEngineVerifyFeatureSetFn;
HRESULT PibioEngineVerifyFeatureSetFn(
[in, out] PWINBIO_PIPELINE Pipeline,
[in] PWINBIO_IDENTITY Identity,
[in] WINBIO_BIOMETRIC_SUBTYPE SubFactor,
[out] PBOOLEAN Match,
[out] PUCHAR *PayloadBlob,
[out] PSIZE_T PayloadBlobSize,
[out] PUCHAR *HashValue,
[out] PSIZE_T HashSize,
[out] PWINBIO_REJECT_DETAIL RejectDetail
)
{...}
Параметры
[in, out] Pipeline
Указатель на WINBIO_PIPELINE структуру, связанную с биометрической единицей, выполняющей операцию.
[in] Identity
Указатель на структуру WINBIO_IDENTITY , содержащую ИДЕНТИФИКАТОР GUID или идентификатор безопасности, который должен соответствовать идентификатору шаблона, восстановленного из базы данных.
[in] SubFactor
Значение WINBIO_BIOMETRIC_SUBTYPE , которое должно соответствовать значению шаблона, восстановленного из базы данных. Дополнительные сведения см. в разделе "Примечания".
[out] Match
Указатель на логическое значение, указывающее, совпадают ли параметры Identity и SubFactor с параметрами шаблона, восстановленного из базы данных. Значение TRUE указывает, что эти значения совпадают.
[out] PayloadBlob
Адрес переменной, получающей указатель на полезные данные, сохраненные с помощью шаблона. Если полезные данные отсутствуют, присвойте этому значению значение NULL.
[out] PayloadBlobSize
Указатель на значение, которое получает размер (в байтах) буфера, указанного в параметре PayloadBlob . Если в шаблоне нет данных полезных данных, задайте для этого значения нулевое значение.
[out] HashValue
Адрес переменной, получающей указатель на хэш шаблона. Если адаптер обработчика не поддерживает создание хэша, присвойте этому значению значение NULL.
[out] HashSize
Указатель на значение, содержащее размер (в байтах) хэша, указанного параметром HashValue . Если адаптер обработчика не поддерживает создание хэша, задайте для этого значения нулевое значение.
[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 , чтобы указать на ошибку.
| Код возврата | Описание |
|---|---|
|
Обязательный параметр указателя — NULL. |
|
Значение, указанное в параметре SubFactor , неверное. |
|
Набор функций не соответствует внутренним требованиям адаптера подсистемы для операции проверки. Дополнительные сведения о сбое указываются параметром RejectDetail . |
|
Набор функций в конвейере соответствует хранящейся в базе данных, но не соответствует сочетанию значений, переданных в параметрах Identity и SubFactor . |
Комментарии
Параметр SubFactor указывает подфактор, связанный с биометрическим шаблоном. Windows Biometric Framework поддерживает только захват отпечатков пальцев и может использовать следующие константы для представления сведений о подтипе.
- WINBIO_ANSI_381_POS_RH_THUMB
- WINBIO_ANSI_381_POS_RH_INDEX_FINGER
- WINBIO_ANSI_381_POS_RH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_RH_RING_FINGER
- WINBIO_ANSI_381_POS_RH_LITTLE_FINGER
- WINBIO_ANSI_381_POS_LH_THUMB
- WINBIO_ANSI_381_POS_LH_INDEX_FINGER
- WINBIO_ANSI_381_POS_LH_MIDDLE_FINGER
- WINBIO_ANSI_381_POS_LH_RING_FINGER
- WINBIO_ANSI_381_POS_LH_LITTLE_FINGER
- WINBIO_SUBTYPE_ANY
Не пытайтесь проверить значение, предоставленное для параметра SubFactor . Служба биометрических данных Windows проверит предоставленное значение перед его передачей в реализацию. Если значение равно WINBIO_SUBTYPE_NO_INFORMATION или WINBIO_SUBTYPE_ANY, проверьте, где это необходимо.
Хэш-значение, возвращаемое этой функцией, если таковое имеется, — это хэш шаблона регистрации, найденного в базе данных, а не соответствующего шаблона, присоединенного к конвейеру.
Буферы PayloadBlob и HashValue принадлежат адаптеру подсистемы и управляются ими после успешного возврата функции EngineAdapterIdentifyFeatureSet . Адаптер подсистемы должен поддерживать допустимый адрес буфера для этого конвейера до следующего вызова EngineAdapterClearContext.
Примеры
В следующем псевдокоде показана одна из возможных реализаций этой функции. Пример не компилируется. Вы должны адаптировать его в соответствии с вашей целью.
//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterVerifyFeatureSet
//
// Purpose:
// Compares the template in the current feature set with a specific
// template in the database.
//
// Parameters:
// Pipeline - Pointer to a WINBIO_PIPELINE structure associated
// with the biometric unit performing the operation
// Identity - GUID or SID that is expected to match that of the
// template recovered from the database
// SubFactor - A WINBIO_BIOMETRIC_SUBTYPE value that is expected
// to match that of the template recovered from the
// database
// Match - A Boolean value that specifies whether the Identity
// and SubFactor parameters match those of the template
// recovered from the database
// PayloadBlob - Payload data saved with the template
// PayloadBlobSize - Size, in bytes, of the buffer specified in the
// PayloadBlob parameter
// HashValue - Hash of the template
// HashSize - Size, in bytes, of the hash specified by the
// HashValue parameter
// RejectDetail - Receives additional information if a capture failure
// prevents the engine from performing a matching operation
//
static HRESULT
WINAPI
EngineAdapterVerifyFeatureSet(
__inout PWINBIO_PIPELINE Pipeline,
__in PWINBIO_IDENTITY Identity,
__in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
__out PBOOLEAN Match,
__out PUCHAR *PayloadBlob,
__out PSIZE_T PayloadBlobSize,
__out PUCHAR *HashValue,
__out PSIZE_T HashSize,
__out PWINBIO_REJECT_DETAIL RejectDetail
)
{
HRESULT hr = S_OK;
WINBIO_STORAGE_RECORD thisRecord;
BOOLEAN match = FALSE;
WINBIO_REJECT_DETAIL rejectDetail = 0;
// Verify that pointer arguments are not NULL.
if (!ARGUMENT_PRESENT(Pipeline) ||
!ARGUMENT_PRESENT(Identity) ||
!ARGUMENT_PRESENT(Match) ||
!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.
*Match = FALSE;
*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;
}
// Query the storage adapter to determine whether the Identity and
// SubFactor combination specified on input are in the database. If
// they are not, there can be no match. WbioStorageQueryBySubject
// is a wrapper function defined in the Winbio_adapter.h header file.
hr = WbioStorageQueryBySubject( Pipeline, Identity, SubFactor);
if (FAILED(hr))
{
if (hr == WINBIO_E_DATABASE_NO_RESULTS)
{
hr = WINBIO_E_NO_MATCH;
}
goto cleanup;
}
// Position the cursor on the first record in the database.
// WbioStorageFirstRecord is a wrapper function defined in the
// Winbio_adapter.h header file.
hr = WbioStorageFirstRecord( Pipeline );
if (FAILED(hr))
{
goto cleanup;
}
// Retrieve the current template record for the Identity and SubFactor
// combination specified on input.
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 the database.
// 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))
{
goto cleanup;
}
// 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;
}
// Set the return values.
*Match = TRUE;
*PayloadBlob = thisRecord.PayloadBlob;
*PayloadBlobSize = thisRecord.PayloadBlobSize;
*HashValue = &context->HashBuffer;
*HashSize = context->HashSize;
cleanup:
if (hr == WINBIO_E_DATABASE_NO_RESULTS)
{
hr = WINBIO_E_NO_MATCH;
}
return hr;
}
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 7 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 R2 [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbio_adapter.h (включая Winbio_adapter.h) |