Método IWDFUsbTargetPipe2::ConfigureContinuousReader (wudfusb.h)

Artigo
03/08/2023

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Drivers universais do Windows devem usar UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

O método ConfigureContinuousReader configura a estrutura para ler continuamente de um pipe USB.

Sintaxe

HRESULT ConfigureContinuousReader(
  [in]           SIZE_T                                              TransferLength,
  [in]           SIZE_T                                              HeaderLength,
  [in]           SIZE_T                                              TrailerLength,
  [in]           UCHAR                                               NumPendingReads,
  [in, optional] IUnknown                                            *pMemoryCleanupCallbackInterface,
  [in]           IUsbTargetPipeContinuousReaderCallbackReadComplete  *pOnCompletion,
  [in, optional] PVOID                                               pCompletionContext,
  [in, optional] IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailure
);

Parâmetros

[in] TransferLength

O comprimento máximo, em bytes, dos dados que podem ser recebidos do dispositivo.

[in] HeaderLength

Um deslocamento, em bytes, para o buffer que recebe dados do dispositivo. A estrutura armazenará dados do dispositivo em um buffer de leitura, começando com o valor de deslocamento. Em outras palavras, esse espaço precede o espaço do tamanho transferLength no qual a estrutura armazena dados do dispositivo.

[in] TrailerLength

O comprimento, em bytes, de um espaço de buffer à direita. Esse espaço segue o espaço do tamanho transferLength no qual a estrutura armazena dados do dispositivo.

[in] NumPendingReads

O número de solicitações de leitura que a estrutura fará fila para receber dados do destino de E/S. Se esse valor for zero, a estrutura usará um número padrão de solicitações de leitura. Se o valor especificado for maior que o valor máximo permitido, a estrutura usará o valor máximo permitido. Para obter mais informações sobre o parâmetro NumPendingReads , consulte a seção Comentários a seguir.

[in, optional] pMemoryCleanupCallbackInterface

Um ponteiro para uma interface IUnkown fornecida pelo driver que a estrutura usa para acessar uma função de retorno de chamada IObjectCleanup::OnCleanup opcional. A estrutura chama a função de retorno de chamada quando desaloca o buffer de leitura que ele cria para lidar com a operação de leitura contínua. Esse parâmetro é opcional e pode ser NULL.

[in] pOnCompletion

Um ponteiro para uma interface IUsbTargetPipeContinuousReaderCallbackReadComplete fornecida pelo driver que fornece uma função de retorno de chamada OnReaderCompletion .

[in, optional] pCompletionContext

Um ponteiro não tipado para informações de contexto definidas pelo driver que a estrutura passa para a função de retorno de chamada IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion do driver.

[in, optional] pOnFailure

Um ponteiro para uma interface IUsbTargetPipeContinuousReaderCallbackReadersFailed fornecida pelo driver que fornece uma função de retorno de chamada OnReaderFailure .

Retornar valor

ConfigureContinuousReader retornará S_OK se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	O driver já configurou um leitor contínuo para o pipe USB. O pipe USB não está configurado para transferências de entrada em massa ou interrupção.
E_OUTOFMEMORY	Falha na tentativa da estrutura de alocar um buffer.
ERROR_ARITHMETIC_OVERFLOW	O parâmetro TransferLength, HeaderLength ou TrailerLength especificou um tamanho muito grande ou inválido.

Esse método pode retornar um dos outros valores que Winerror.h contém.

Comentários

Você pode configurar um leitor contínuo para um pipe em massa ou um pipe de interrupção. O pipe deve ter um ponto de extremidade de entrada.

Depois de chamar ConfigureContinuousReader para configurar um leitor contínuo, seu driver deve chamar IWDFIoTargetStateManagement::Start para iniciar o leitor. Para interromper o leitor, o driver deve chamar IWDFIoTargetStateManagement::Stop.

Normalmente, um driver chama ConfigureContinuousReader de dentro de sua função de retorno de chamada IPnpCallbackHardware::OnPrepareHardware . O driver deve chamar IWDFIoTargetStateManagement::Start de dentro de sua função de retorno de chamada IPnpCallback::OnD0Entry e deve chamar IWDFIoTargetStateManagement::Stop de dentro de sua função de retorno de chamada IPnpCallback::OnD0Exit .

Cada vez que o destino de E/S do pipe conclui com êxito uma solicitação de leitura, a estrutura chama a função de retorno de chamada IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion do driver. Se o destino de E/S relatar uma falha ao processar uma solicitação, a estrutura chamará a função de retorno de chamada IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure do driver depois que todas as solicitações de leitura forem concluídas. (Portanto, a função de retorno de chamada OnReaderCompletion não será chamada enquanto a função de retorno de chamada OnReaderFailure estiver em execução.)

Use as seguintes diretrizes para escolher um valor para o parâmetro NumPendingReads :

Defina NumPendingReads como zero se quiser que o driver use o valor padrão da estrutura.
O valor padrão é maior que um e fornece um desempenho razoavelmente bom para muitos dispositivos em muitas configurações de processador.
Defina NumPendingReads como um se for importante que o driver receba buffers de dados na ordem exata em que o dispositivo entrega os dados.
Se a estrutura enfileirar mais de uma solicitação de leitura, o driver poderá não receber os buffers de dados na mesma ordem em que o dispositivo entrega os dados.
Defina NumPendingReads como um número que atenda aos requisitos de desempenho do seu dispositivo, com base em medidas completas de desempenho.
Primeiro, teste seu dispositivo com o valor padrão (0) para NumPendingReads. Seus testes devem incluir várias configurações de hardware, incluindo diferentes tipos e números de processadores e diferentes controladores de host USB e configurações USB. Em seguida, você pode experimentar valores mais altos usando os mesmos testes. Um driver que pode exigir um valor mais alto é um para um dispositivo que tem uma alta taxa de interrupção, em que os dados podem ser perdidos se as interrupções não forem atendidas rapidamente.

Um valor NumPendingReads muito grande pode diminuir o desempenho de um sistema. Você deve usar o valor mais baixo que atenda aos seus requisitos de desempenho. Normalmente, valores maiores que três ou quatro não melhoram a taxa de transferência de dados. Mas valores mais altos podem reduzir a latência ou a chance de dados ausentes em um pipe de alta frequência.

Depois que um driver tiver chamado ConfigureContinuousReader, o driver não poderá usar IWDFIoRequest::Send para enviar solicitações de E/S para o pipe, a menos que a função de retorno de chamada IUsbTargetPipeContinuousReaderCallbackReadersFailed::OnReaderFailure do driver seja chamada e retorne FALSE.

Para obter mais informações sobre o método ConfigureContinuousReader e destinos de E/S USB, consulte Lendo de um pipe UMDF-USB.

Exemplos

O exemplo de código a seguir configura um leitor contínuo. Neste exemplo, o tamanho máximo do buffer é o tamanho de um buffer definido pelo driver. Os deslocamentos de cabeçalho e buffer de trailer são definidos como zero e o número de operações de leitura pendentes é definido como dois. O exemplo usa o ponteiro de interface do pipe de destino para o parâmetro pCompletionContext , para que a função de retorno de chamada OnReaderCompletion possa determinar o pipe no qual a operação de leitura foi concluída.

HRESULT hr, hrQI;
IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletionCallback = NULL;
IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailureCallback= NULL;
IWDFUsbTargetPipe2 * pIUsbInterruptPipe2;

//
// Obtain interfaces.
//
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnFailureCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = m_pIUsbInterruptPipe->QueryInterface(IID_PPV_ARGS(&pIUsbInterruptPipe2));
if (!SUCCEEDED(hrQI)) goto Error;

//
// Configure the reader.
//
hr = pIUsbInterruptPipe2->ConfigureContinuousReader(
                                                    sizeof(m_MyBuffer), 
                                                    0,
                                                    0,
                                                    2, 
                                                    NULL,
                                                    pOnCompletionCallback,
                                                    m_pIUsbTargetPipe,
                                                    pOnFailureCallback
                                                    );
...

Requisitos

Requisito	Valor
Fim do suporte	Indisponível no UMDF 2.0 e posterior.
Plataforma de Destino	Área de Trabalho
Versão mínima do UMDF	1,9
Cabeçalho	wudfusb.h (include Wudfusb.h)
DLL	WUDFx.dll