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

Artigo
03/09/2024

Chamado pela Estrutura Biométrica do Windows quando um adaptador de sensor é adicionado ao pipeline de processamento da unidade biométrica. A finalidade dessa função é executar qualquer inicialização necessária para operações biométricas posteriores.

Sintaxe

PIBIO_SENSOR_ATTACH_FN PibioSensorAttachFn;

HRESULT PibioSensorAttachFn(
  [in, out] PWINBIO_PIPELINE Pipeline
)
{...}

Parâmetros

[in, out] Pipeline

Ponteiro para a estrutura WINBIO_PIPELINE associada à unidade biométrica que executa a operação.

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_POINTER	O argumento Pipeline não pode ser NULL.
E_OUTOFMEMORY	A operação não pôde ser concluída devido à memória insuficiente.
WINBIO_E_INVALID_DEVICE_STATE	O membro SensorContext da estrutura WINBIO_PIPELINE apontada pelo argumento Pipeline não é NULL.

Comentários

Essa função é chamada antes que o mecanismo e os adaptadores de armazenamento sejam inicializados para a unidade biométrica. Portanto, essa função não deve chamar nenhuma função referenciada pelo WINBIO_ENGINE_INTERFACE ou pela estrutura WINBIO_STORAGE_INTERFACE apontada pelos membros EngineInterface e StorageInterface do objeto de pipeline.

Como o membro SensorHandle da estrutura WINBIO_PIPELINE conterá um identificador válido antes que esse método seja chamado, sua implementação de SensorAdapterAttach pode usar o identificador para acessar o dispositivo do sensor, se necessário.

Ao implementar essa função, você deve alocar e gerenciar todos os recursos exigidos pelo adaptador e anexá-los ao pipeline de unidade biométrica. Para fazer isso, aloque uma estrutura de WINBIO_SENSOR_CONTEXT privada no heap, inicialize-a e defina seu endereço no membro SensorContext do objeto de pipeline.

Se houver um erro durante a criação e inicialização dos recursos do adaptador de mecanismo usados por essa função, você deverá executar qualquer limpeza necessária antes de retornar.

Se o campo SensorContext não for NULL quando essa função for chamada, o pipeline não foi redefinido corretamente por uma chamada anterior a SensorAdapterDetach e você deverá retornar WINBIO_E_INVALID_DEVICE_STATE para notificar a Estrutura Biométrica do Windows sobre o problema.

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.

//////////////////////////////////////////////////////////////////////////////////////////
//
// SensorAdapterAttach
//
// Purpose:
//      Performs any initialization required for later biometric operations.
//
// Parameters:
//      Pipeline -  Pointer to a WINBIO_PIPELINE structure associated with 
//                  the biometric unit performing the operation.
//
static HRESULT
WINAPI
SensorAdapterAttach(
    __inout PWINBIO_PIPELINE Pipeline
    )
{
    HRESULT hr = S_OK;
    PWINBIO_SENSOR_CONTEXT newContext = NULL;

    // Verify that the Pipeline parameter is not NULL.
    if (!ARGUMENT_PRESENT(Pipeline))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Validate the current sensor state.
    if (Pipeline->SensorContext != NULL)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    // Use a custom function (_AdapterAlloc) to allocate memory for the 
    // sensor adapter context.
    newContext = (PWINBIO_SENSOR_CONTEXT)_AdapterAlloc(sizeof(WINBIO_SENSOR_CONTEXT));
    if (newContext == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }

    // Create a manual reset event to monitor overlapped I/O.
    newContext->Overlapped.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);
    if (newContext->Overlapped.hEvent == NULL)
    {
        hr = E_OUTOFMEMORY;
        goto cleanup;
    }

    // Initialize any required context fields. This example assumes that your
    // sensor context points to a capture buffer and an attributes buffer.
    newContext->CaptureBuffer = NULL;
    newContext->CaptureBufferSize = 0;

    newContext->AttributesBuffer = NULL;
    newContext->AttributesBufferSize = sizeof (WINBIO_SENSOR_ATTRIBUTES);

    // Transfer ownership of the new sensor context structure to the 
    // pipeline.
    Pipeline->SensorContext = newContext;
    newContext = NULL;

cleanup:

    if (FAILED(hr) && newContext != NULL)
    {
        CloseHandle( newContext->Overlapped.hEvent;
        _AdapterRelease( newContext );
        newContext = NULL;
    }
    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)