PIBIO_ENGINE_COMMIT_ENROLLMENT_FN função de retorno de chamada (winbio_adapter.h)

  • Artigo

Chamado pela Estrutura Biométrica do Windows para finalizar o objeto de registro, convertê-lo em um modelo e salvar o modelo no banco de dados.

Sintaxe

PIBIO_ENGINE_COMMIT_ENROLLMENT_FN PibioEngineCommitEnrollmentFn;

HRESULT PibioEngineCommitEnrollmentFn(
  [in, out]      PWINBIO_PIPELINE Pipeline,
  [in]           PWINBIO_IDENTITY Identity,
  [in]           WINBIO_BIOMETRIC_SUBTYPE SubFactor,
  [in, optional] PUCHAR PayloadBlob,
  [in]           SIZE_T PayloadBlobSize
)
{...}

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 o GUID ou SID do modelo a ser armazenado no banco de dados.

[in] SubFactor

Um valor WINBIO_BIOMETRIC_SUBTYPE que especifica o subfator associado ao modelo a ser armazenado no banco de dados.

[in, optional] PayloadBlob

Um ponteiro opcional para uma matriz de bytes que contêm uma assinatura de verificação gerada pela Estrutura Biométrica do Windows.

[in] PayloadBlobSize

O tamanho, em bytes, da matriz de caracteres apontada pelo parâmetro PayloadBlob . Esse valor deverá ser zero se o parâmetro PayloadBlob for NULL.

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 ou qualquer valor retornado pelo adaptador de armazenamento.

Código de retorno Descrição
E_POINTER
 Um argumento de ponteiro obrigatório é NULL.
E_INVALIDARG
 O valor especificado pelo parâmetro Identity ou pelo parâmetro SubFactor não é válido.
WINBIO_E_DUPLICATE_ENROLLMENT
 O modelo especificado pelos parâmetros Identity e SubFactor já está salvo no banco de dados.
WINBIO_E_INVALID_DEVICE_STATE
 Não há nenhum modelo anexado ao pipeline.

Comentários

Se essa função for bem-sucedida, ela deverá liberar o modelo de registro do pipeline. O resultado dessa ação deve ser equivalente a chamar EngineAdapterClearContext.

Se essa função falhar, ela não deverá alterar o estado do contexto do mecanismo. Em particular, se houver um modelo concluído anexado ao pipeline, deverá ser possível chamar essa função novamente (após os motivos para qualquer falha ter sido resolvida) para confirmar o modelo no banco de dados.

Os adaptadores de mecanismo que dão suporte à autenticação de pré-inicialização devem confirmar o registro não apenas para o adaptador de armazenamento anexado ao pipeline, mas também para a área de armazenamento de pré-inicialização. Os detalhes de como isso deve ser feito são deixados para o fornecedor.

Importante  

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.

 

Exemplos

O pseudocódigo a seguir mostra uma implementação possível dessa função. O exemplo não é compilado. Você deve adaptá-lo para se adequar ao seu propósito.

//////////////////////////////////////////////////////////////////////////////////////////
//
// EngineAdapterCommitEnrollment
//
// Purpose:
//      Finalizes the enrollment object, converts it to a template, and saves 
//      the template in the database.
//
// Parameters:
//      Pipeline        - Pointer to a WINBIO_PIPELINE structure associated 
//                        with the biometric unit performing the operation
//      Identity        - GUID or SID of the template to be stored in the 
//                        database
//      SubFactor       - Sub-factor associated with the template to be stored
//                        in the database
//      PayloadBlob     - Optional pointer to an array of bytes that contain a 
//                        verification signature generated by the Windows Biometric
//                        Framework
//      PayloadBlobSize - Size, in bytes, of the character array pointed to by 
//                        the PayloadBlob parameter
//

static HRESULT
WINAPI
EngineAdapterCommitEnrollment(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor,
    __in PUCHAR PayloadBlob,
    __in SIZE_T PayloadBlobSize
    )
{
    HRESULT hr = S_OK;
    DWORD indexVector[NUMBER_OF_TEMPLATE_BINS] = {0};
    WINBIO_REJECT_DETAIL rejectDetail = 0;
    WINBIO_STORAGE_RECORD newTemplate = {0};

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

    if (ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize == 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }
    
    if (!ARGUMENT_PRESENT(PayloadBlob) && PayloadBlobSize > 0)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // TODO: Verify that the SubFactor and Identity arguments are valid.

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

    // Return if an enrollment is not in progress. This example assumes that 
    // an enrollment object is part of your engine context structure.
    if (context->Enrollment.InProgress != TRUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        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 enrollment object.
    hr = _AdapterCreateIndexVector(
                context, 
                context->Enrollment.Template, 
                context->Enrollment.TemplateSize,
                indexVector, 
                NUMBER_OF_TEMPLATE_BINS, 
                &rejectDetail
                );
    if (FAILED(hr))
    {
        goto cleanup;
    }

    newTemplate.Identity = Identity;
    newTemplate.SubFactor = SubFactor;
    newTemplate.IndexVector = indexVector;
    newTemplate.IndexElementCount = NUMBER_OF_TEMPLATE_BINS;
    newTemplate.TemplateBlob = context->Enrollment.Template;
    newTemplate.TemplateBlobSize = context->Enrollment.TemplateSize;
    newTemplate.PayloadBlob = PayloadBlob;
    newTemplate.PayloadBlobSize = PayloadBlobSize;

    hr = WbioStorageAddRecord(
                Pipeline,
                &newTemplate
                );

    if (FAILED(hr))
    {
        goto cleanup;
    }

    // Call a custom function (_AdapterDestroyEnrollmentTemplate) to release
    // any resources held by the enrollment object.
    _AdapterDestroyEnrollmentTemplate(
        context,
        &context->Enrollment
        );

    // Specify that the enrollment process has been completed.
    context->Enrollment.InProgress = FALSE;

cleanup:

    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)

Confira também

EngineAdapterClearContext

Funções de plug-in