função de retorno de chamada PIBIO_ENGINE_VERIFY_FEATURE_SET_FN (winbio_adapter.h)
Chamado pela Estrutura Biométrica do Windows para comparar o modelo no conjunto de recursos atual com um modelo específico no banco de dados. Se os modelos forem equivalentes, o adaptador do mecanismo deverá definir o valor booliano apontado pelo parâmetro Match como TRUE, retornar o modelo correspondente no parâmetro PayloadBlob e retornar um hash do modelo no parâmetro HashValue .
Sintaxe
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
)
{...}
Parâmetros
[in, out] Pipeline
Ponteiro para uma estrutura WINBIO_PIPELINE associada à unidade biométrica que executa a operação.
[in] Identity
Ponteiro para uma estrutura WINBIO_IDENTITY que contém um GUID ou SID que deve corresponder ao do modelo recuperado do banco de dados.
[in] SubFactor
Um valor WINBIO_BIOMETRIC_SUBTYPE que deve corresponder ao do modelo recuperado do banco de dados. Para obter mais detalhes, consulte a seção Comentários.
[out] Match
Ponteiro para um valor booliano que especifica se os parâmetros Identity e SubFactor correspondem aos do modelo recuperado do banco de dados. TRUE especifica que esses valores correspondem.
[out] PayloadBlob
Endereço de uma variável que recebe um ponteiro para os dados de carga salvos com o modelo. Se não houver dados de conteúdo, defina esse valor como NULL.
[out] PayloadBlobSize
Ponteiro para um valor que recebe o tamanho, em bytes, do buffer especificado no parâmetro PayloadBlob . Se não houver dados de conteúdo armazenados com o modelo, defina esse valor como zero.
[out] HashValue
Endereço de uma variável que recebe um ponteiro para o hash do modelo. Se o adaptador do mecanismo não der suporte à geração de hash, defina esse valor como NULL.
[out] HashSize
Ponteiro para um valor que contém o tamanho, em bytes, do hash especificado pelo parâmetro HashValue . Se o adaptador do mecanismo não der suporte à geração de hash, defina esse valor como zero.
[out] RejectDetail
Ponteiro para um valor de WINBIO_REJECT_DETAIL que recebe informações adicionais se uma falha de captura impedir que o mecanismo execute uma operação correspondente. Se a captura mais recente tiver sido bem-sucedida, defina esse parâmetro como zero. Os valores a seguir são definidos para captura de impressão digital
- 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
Retornar valor
Se a função for bem-sucedida, ela retornará S_OK. Se a função falhar, ela deverá retornar um dos seguintes valores HRESULT para indicar o erro.
| Código de retorno | Descrição |
|---|---|
|
Um parâmetro de ponteiro obrigatório é NULL. |
|
O valor especificado no parâmetro SubFactor não está correto. |
|
O conjunto de recursos não atendia aos requisitos internos do adaptador do mecanismo para uma operação de verificação. Mais informações sobre a falha são especificadas pelo parâmetro RejectDetail . |
|
O conjunto de recursos no pipeline corresponde a um armazenado no banco de dados, mas não corresponde à combinação de valores passados nos parâmetros Identity e SubFactor . |
Comentários
O parâmetro SubFactor especifica o subfator associado ao modelo biométrico. A Estrutura Biométrica do Windows dá suporte apenas à captura de impressão digital e pode usar as constantes a seguir para representar informações de subtipo.
- 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
Não tente validar o valor fornecido para o parâmetro SubFactor . O Serviço de Biometria do Windows validará o valor fornecido antes de passá-lo para sua implementação. Se o valor for WINBIO_SUBTYPE_NO_INFORMATION ou WINBIO_SUBTYPE_ANY, valide quando apropriado.
O valor de hash retornado por essa função, se houver, é o hash do modelo de registro encontrado no banco de dados, não o modelo correspondente anexado ao pipeline.
Os buffers PayloadBlob e HashValue são de propriedade e gerenciados pelo adaptador do mecanismo depois que a função EngineAdapterIdentifyFeatureSet retorna com êxito . O adaptador do mecanismo deve manter o endereço buffer válido para esse pipeline até a próxima chamada para EngineAdapterClearContext.
Exemplos
O pseudocódigo a seguir mostra uma possível implementação dessa função. O exemplo não é compilado. Você deve adaptá-lo para se adequar à sua finalidade.
//////////////////////////////////////////////////////////////////////////////////////////
//
// 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;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 7 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 R2 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbio_adapter.h (inclua Winbio_adapter.h) |