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

Artigo
02/07/2025

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

O método ConfigureContinuousReader configura a estrutura para leitura contínua 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 pelo valor de deslocamento. Em outras palavras, esse espaço precede o transferLengthespaço dimensionado 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 transferLengthespaço dimensionado 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 de 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 de 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 o do driver IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion função de retorno de chamada.

[in, optional] pOnFailure

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

Valor de retorno

ConfigureContinuousReader retornará S_OK se a operação for bem-sucedida. Caso contrário, esse método poderá 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 de interrupção.
E_OUTOFMEMORY	Falha na tentativa da estrutura de alocar um buffer.
ERROR_ARITHMETIC_OVERFLOW	O parâmetro TransferLength, HeaderLengthou TrailerLength especificou um tamanho muito grande ou inválido.

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

Observações

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 parar 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 função de retorno de chamada IWDFIoTargetStateManagement::Start de dentro de seu IPnpCallback::OnD0Entry função de retorno de chamada e deve chamar IWDFIoTargetStateManagement::Stop de dentro de sua função de retorno de chamada IPnpCallback::OnD0Exit.

Sempre que o destino de E/S do pipe concluir com êxito uma solicitação de leitura, a estrutura chamará o do driver IUsbTargetPipeContinuousReaderCallbackReadComplete::OnReaderCompletion função de retorno de chamada. 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 função de retorno de chamada após todas as solicitações de leitura terem sido concluídas. (Portanto, a função OnReaderCompletion de retorno de chamada 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 fornece 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 fornece os dados.
Defina NumPendingReads para um número que atenda aos requisitos de desempenho do dispositivo, com base em medidas de desempenho completas.
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::Enviar para enviar solicitações de E/S para o pipe, a menos que a função de retorno de chamada do driver seja chamada e retorne FALSE.

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

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 da interface do pipe de destino para o parâmetro pCompletionContext, de modo que o OnReaderCompletion função de retorno de chamada pode 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.
da Plataforma de Destino	Área de trabalho
versão mínima do UMDF	1.9
cabeçalho	wudfusb.h (inclua Wudfusb.h)
de DLL	WUDFx.dll