Compartilhar via


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

Chamado pela Estrutura Biométrica do Windows para executar uma operação de controle definida pelo fornecedor que não exige privilégios elevados. Chame a função StorageAdapterControlUnitPrivileged para executar uma operação de controle definida pelo fornecedor que requer privilégios elevados.

Sintaxe

PIBIO_STORAGE_CONTROL_UNIT_FN PibioStorageControlUnitFn;

HRESULT PibioStorageControlUnitFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      ULONG ControlCode,
  [in]      PUCHAR SendBuffer,
  [in]      SIZE_T SendBufferSize,
  [in]      PUCHAR ReceiveBuffer,
  [in]      SIZE_T ReceiveBufferSize,
  [out]     PSIZE_T ReceiveDataSize,
  [out]     PULONG OperationStatus
)
{...}

Parâmetros

[in, out] Pipeline

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

[in] ControlCode

Um valor ULONG que especifica a operação definida pelo fornecedor a ser executada.

[in] SendBuffer

Ponteiro para um buffer que contém as informações de controle enviadas para o adaptador de armazenamento. O formato e o conteúdo do buffer são definidos pelo fornecedor.

[in] SendBufferSize

Tamanho, em bytes, do buffer especificado pelo parâmetro SendBuffer .

[in] ReceiveBuffer

Ponteiro para o buffer que recebe informações enviadas pelo adaptador de armazenamento em resposta à operação de controle. O formato do buffer é definido pelo fornecedor.

[in] ReceiveBufferSize

Tamanho, em bytes, do buffer especificado pelo parâmetro ReceiveBuffer .

[out] ReceiveDataSize

Ponteiro para uma variável que recebe o tamanho, em bytes, dos dados gravados no buffer especificado pelo parâmetro ReceiveBuffer .

[out] OperationStatus

Ponteiro para uma variável que recebe um código de status definido pelo fornecedor que especifica o resultado da operação de controle.

Valor retornado

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
Um argumento de ponteiro obrigatório é NULL.
E_INVALIDARG
O tamanho ou o formato do buffer especificado pelo parâmetro SendBuffer não está correto ou o valor especificado no parâmetro ControlCode não é reconhecido pelo adaptador.
E_NOT_SUFFICIENT_BUFFER
O buffer especificado pelo parâmetro ReceiveBuffer é muito pequeno.
WINBIO_E_CANCELED
A operação foi cancelada.
WINBIO_E_DEVICE_FAILURE
Houve uma falha de hardware.
WINBIO_E_INVALID_CONTROL_CODE
O valor especificado no parâmetro ControlCode não é reconhecido pelo adaptador.
Nota A partir do Windows 8, use apenas E_INVALIDARG para sinalizar essa condição.
 

Comentários

Sua implementação dessa função deve ser idêntica à implementação da função StorageAdapterControlUnitPrivileged , exceto que privilégios elevados não são necessários para executar as operações especificadas pelo parâmetro ControlCode . Você é responsável por definir as operações e decidir quais não exigirão privilégios elevados.

Essa função deve marcar o valor do parâmetro ReceiveBufferSize para ter certeza de que o buffer especificado pelo parâmetro ReceiveBuffer é grande o suficiente para conter os dados que estão sendo retornados.

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.

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterControlUnit
//
// Purpose:
//       Performs a vendor-defined control operation that does not require 
//       elevated privilege.
//
// Parameters:
//      Pipeline            - Pointer to a WINBIO_PIPELINE structure associated 
//                            with the biometric unit performing the operation.
//      ControlCode         - Specifies the vendor-defined operation to perform.
//      SendBuffer          - Contains the control information sent to the 
//                            storage adapter.
//      SendBufferSize      - Size, in bytes, of the buffer specified by the 
//                            SendBuffer parameter.
//      ReceiveBuffer       - Receives information returned by the storage adapter
//                            in response to the control operation.
//      ReceiveBufferSize   - Size, in bytes, of the buffer specified by the 
//                            ReceiveBuffer parameter.
//      ReceiveDataSize     - Receives the size, in bytes, of the data written to 
//                            the buffer specified by the ReceiveBuffer parameter.
//      OperationStatus     - Receives a vendor-defined status code that specifies 
//                            the outcome of the control operation.
//
//
static HRESULT
WINAPI
StorageAdapterControlUnit(
    __inout PWINBIO_PIPELINE Pipeline,
    __in ULONG ControlCode,
    __in PUCHAR SendBuffer,
    __in SIZE_T SendBufferSize,
    __in PUCHAR ReceiveBuffer,
    __in SIZE_T ReceiveBufferSize,
    __out PSIZE_T ReceiveDataSize,
    __out PULONG OperationStatus
    )
{
    HRESULT hr = S_OK;
    BOOL result = TRUE;

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

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

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

    switch (ControlCode)
    {
    case MY_NONPRIVILEGED_CTRL_CODE_NP1:
        {
            CTRL_CODE_NP1_SEND_BUFFER *sendBuffer = (CTRL_CODE_NP1_SEND_BUFFER*)SendBuffer;

            // Verify the size of the send buffer.
            if (SendBufferSize < sizeof(CTRL_CODE_NP1_SEND_BUFFER))
            {
                hr = E_INVALIDARG;
                break;
            }

            // Perform any other checks that may be required on the buffer 
            // contents. Return E_INVALIDARG if any of the checks fail.
            if (sendBuffer->SomeField != SomeSpecialValue ||
                sendBuffer->SomeOtherField != SomeOtherSpecialValue)
            {
                hr = E_INVALIDARG;
                break;
            }

            if (ReceiveBufferSize < sizeof(CTRL_CODE_NP1_RECEIVE_BUFFER))
            {
                hr = E_NOT_SUFFICIENT_BUFFER;
                break;
            }
        }

        // Fall through and perform the control operation after the switch
        // statement. Alternatively, depending on your requirements, you can 
        // perform the control operation here.
        break;

    case MY_NONPRIVILEGED_CTRL_CODE_NP2:
        // Continue testing for other non-privileged control codes that your
        // adapter supports.
        {
            CTRL_CODE_NP2_SEND_BUFFER *sendBuffer = (CTRL_CODE_NP2_SEND_BUFFER*)SendBuffer;

            // Verify the size of the send buffer.
            if (SendBufferSize < sizeof(CTRL_CODE_NP2_SEND_BUFFER))
            {
                hr = E_INVALIDARG;
                break;
            }

            // Perform any other checks that may be required on the buffer 
            // contents. Return E_INVALIDARG if any of the checks fail.
            if (sendBuffer->SomeField != SomeSpecialValue ||
                sendBuffer->SomeOtherField != SomeOtherSpecialValue)
            {
                hr = E_INVALIDARG;
                break;
            }

            if (ReceiveBufferSize < sizeof(CTRL_CODE_NP2_RECEIVE_BUFFER))
            {
                hr = E_NOT_SUFFICIENT_BUFFER;
                break;
            }
        }
        break;

    default:
        // All unrecognized control code values should return an error.
        hr = WINBIO_E_INVALID_CONTROL_CODE;
        break;
    }
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // If control code validation succeeds, perform the control operation. This
    // example assumes that your adapter has put an open handle to a storage 
    // device in the Pipeline structure. It also assumes that the driver performs
    // overlapped I/O and that a properly initialized OVERLAPPED structure is
    // contained in the storage context.
    result = DeviceIoControl(
                Pipeline->StorageHandle,
                ControlCode,
                SendBuffer,
                (DWORD)SendBufferSize,
                ReceiveBuffer,
                (DWORD)ReceiveBufferSize,
                (LPDWORD)ReceiveDataSize,
                &storageContext->Overlapped
                );
    if (result == FALSE && GetLastError() == ERROR_IO_PENDING)
    {
        SetLastError(ERROR_SUCCESS);

        result = GetOverlappedResult(
                    Pipeline->StorageHandle,
                    &storageContext->Overlapped,
                    (LPDWORD)ReceiveDataSize,
                    TRUE
                    );
    }
    *OperationStatus = GetLastError();

    if (!result)
    {
        hr = _AdapterGetHresultFromWin32(*OperationStatus);
    }

cleanup:

    return hr;
}

Requisitos

   
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

Funções de plug-in

StorageAdapterControlUnitPrivileged