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

Artigo
08/27/2023

Chamado pela Estrutura Biométrica do Windows ou pelo adaptador do mecanismo para localizar modelos que correspondam a uma identidade e um subfator especificados.

Sintaxe

PIBIO_STORAGE_QUERY_BY_SUBJECT_FN PibioStorageQueryBySubjectFn;

HRESULT PibioStorageQueryBySubjectFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      PWINBIO_IDENTITY Identity,
  [in]      WINBIO_BIOMETRIC_SUBTYPE SubFactor
)
{...}

Parâmetros

[in, out] Pipeline

Ponteiro para a estrutura de 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 a ser localizado. Se o campo Tipo dessa estrutura contiver WINBIO_IDENTITY_TYPE_WILDCARD, a consulta retornará todos os modelos que correspondem ao parâmetro SubFactor .

[in] SubFactor

Um valor WINBIO_BIOMETRIC_SUBTYPE que especifica o subfator a ser localizado. Se esse valor for WINBIO_SUBTYPE_ANY, a consulta retornará todos os modelos que correspondem ao parâmetro Identity .

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
E_INVALIDARG	O argumento especificado pelo parâmetro SubFactor não é válido ou um membro da estrutura especificada pelo parâmetro Identity não é válido.
E_POINTER	Um argumento de ponteiro obrigatório é NULL.
WINBIO_E_DATABASE_NO_RESULTS	A consulta foi bem-sucedida, mas nenhum registro correspondente foi encontrado.
WINBIO_E_DATABASE_LOCKED	O banco de dados está bloqueado.
WINBIO_E_DATABASE_READ_ERROR	Ocorreu um problema não especificado.
WINBIO_E_INVALID_DEVICE_STATE	O membro StorageContext do objeto pipeline é NULL ou o membro FileHandle não é válido.

Comentários

Se esse método retornar com êxito, o conjunto de resultados no pipeline será substituído pelos resultados da consulta, mesmo que a consulta retorne um conjunto vazio.

Os chamadores dessa função devem ser capazes de recuperar todos os registros:

Passando uma estrutura WINBIO_IDENTITY no parâmetro Identity com o campo Tipo definido como WINBIO_IDENTITY_TYPE_WILDCARD.
Passando WINBIO_SUBTYPE_ANY no parâmetro SubFactor .

Após uma chamada bem-sucedida para essa função, o cursor do conjunto de resultados deve ser posicionado no primeiro registro do conjunto.

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 possível implementação dessa função. O exemplo não é compilado. Você deve adaptá-lo para se adequar à sua finalidade.

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterQueryBySubject
//
// Purpose:
//      Locates templates that match a specified identity and sub-factor.
//
// Parameters:
//      Pipeline  -  Pointer to a WINBIO_PIPELINE structure associated with 
//                   the biometric unit performing the operation.
//      Identity  -  Pointer to a WINBIO_IDENTITY structure that contains the GUID 
//                   or SID to be located.
//      SubFactor -  A WINBIO_BIOMETRIC_SUBTYPE value that specifies the sub-factor 
//                   to be located.
//
static HRESULT
WINAPI
StorageAdapterQueryBySubject(
    __inout PWINBIO_PIPELINE Pipeline,
    __in PWINBIO_IDENTITY Identity,
    __in WINBIO_BIOMETRIC_SUBTYPE SubFactor
    )
{
    HRESULT hr = S_OK;
    SIZE_T recordCount = 0;

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

    // Retrieve the context from the pipeline.
    PWINBIO_STORAGE_CONTEXT storageContext = (PWINBIO_STORAGE_CONTEXT)Pipeline->StorageContext;

    // Verify the pipeline state.
    if (storageContext == NULL || storageContext->FileHandle == INVALID_HANDLE_VALUE)
    {
        hr =  WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Verify the Identity argument.
    if (Identity->Type != WINBIO_ID_TYPE_GUID &&
        Identity->Type != WINBIO_ID_TYPE_SID &&
        Identity->Type != WINBIO_ID_TYPE_WILDCARD)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    if (Identity->Type == WINBIO_ID_TYPE_WILDCARD &&
        Identity->Value.Wildcard != WINBIO_IDENTITY_WILDCARD)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // WINBIO_SUBTYPE_ANY is a valid sub-factor.
    // WINBIO_SUBTYPE_NO_INFORMATION is not a valid sub-factor.
    if (SubFactor == WINBIO_SUBTYPE_NO_INFORMATION)
    {
        hr = E_INVALIDARG;
        goto cleanup;
    }

    // Call a custom function (_FindAllMatchingRecords) that compares the 
    // identity and sub-factor values from the caller to the identity and
    // sub-factor values of every record in the database and adds the matching
    // database records to the result set in the pipeline.
    hr = _FindAllMatchingRecords( 
            Pipeline,
            Identity,
            SubFactor,
            &recordCount
            );
    if (FAILED(hr))
    {
        goto cleanup;
    }
    if (recordCount == 0)
    {
        hr = WINBIO_E_DATABASE_NO_RESULTS;
        goto cleanup;
    }

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)