Função WdfUsbTargetPipeConfigContinuousReader (wdfusb.h)

Artigo
08/08/2023

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetPipeConfigContinuousReader configura a estrutura para leitura contínua de um pipe USB especificado.

Sintaxe

NTSTATUS WdfUsbTargetPipeConfigContinuousReader(
  [in] WDFUSBPIPE                        Pipe,
  [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config
);

Parâmetros

[in] Pipe

Um identificador para um objeto de pipe de estrutura que foi obtido chamando WdfUsbInterfaceGetConfiguredPipe.

[in] Config

Um ponteiro para uma estrutura de WDF_USB_CONTINUOUS_READER_CONFIG alocada pelo chamador.

Retornar valor

WdfUsbTargetPipeConfigContinuousReader retornará STATUS_SUCCESS 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
STATUS_INFO_LENGTH_MISMATCH	O tamanho da estrutura WDF_USB_CONTINUOUS_READER_CONFIG que o parâmetro Config especificou estava incorreto.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_INSUFFICIENT_RESOURCES	Memória insuficiente disponível.
STATUS_INVALID_DEVICE_REQUEST	O tipo do pipe não era válido.
STATUS_INTEGER_OVERFLOW	O membro HeaderLength, TransferLength ou TrailerLength da estrutura WDF_USB_CONTINUOUS_READER_CONFIG que o parâmetro Config especificou um tamanho muito grande ou inválido.
STATUS_INVALID_BUFFER_SIZE	O tamanho do buffer de leitura não era um múltiplo do tamanho máximo do pacote do pipe.

Para obter uma lista de outros valores retornados que o método WdfUsbTargetPipeConfigContinuousReader pode retornar, consulte Erros de criação de objeto da estrutura.

Esse método também pode retornar outros valores NTSTATUS.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

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 WdfUsbTargetPipeConfigContinuousReader para configurar um leitor contínuo, seu driver deve chamar WdfIoTargetStart para iniciar o leitor. Para parar o leitor, o driver deve chamar WdfIoTargetStop.

Normalmente, um driver chama WdfUsbTargetPipeConfigContinuousReader de dentro de sua função de retorno de chamada EvtDevicePrepareHardware . O driver deve chamar WdfIoTargetStart de dentro de sua função de retorno de chamada EvtDeviceD0Entry e deve chamar WdfIoTargetStop de dentro de sua função de retorno de chamada EvtDeviceD0Exit .

Sempre que o destino de E/S do pipe for concluído com êxito, a estrutura chamará a função de retorno de chamada EvtUsbTargetPipeReadComplete 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 EvtUsbTargetPipeReadersFailed do driver depois que todas as solicitações de leitura forem concluídas. (Portanto, a função de retorno de chamada EvtUsbTargetPipeReadComplete não será chamada enquanto a função de retorno de chamada EvtUsbTargetPipeReadersFailed estiver em execução).

Se você não fornecer o retorno de chamada EvtUsbTargetPipeReadersFailed opcional, a estrutura responderá a uma tentativa de leitura com falha enviando outra solicitação de leitura. Portanto, se o barramento estiver em um estado em que não está aceitando leituras, a estrutura envia continuamente novas solicitações para se recuperar de uma leitura com falha.

Depois que um driver tiver chamado WdfUsbTargetPipeConfigContinuousReader, o driver não poderá usar WdfUsbTargetPipeReadSynchronously ou WdfRequestSend para enviar solicitações de E/S para o pipe, a menos que o leitor contínuo tenha sido interrompido. Para interromper o leitor, o driver pode chamar WdfIoTargetStop ou retornar FALSE de sua função de retorno de chamada EvtUsbTargetPipeReadersFailed . Se o driver chamar WdfUsbTargetPipeReadSynchronously enquanto o leitor for interrompido, ele deverá definir o sinalizador WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE no membro Flags do parâmetro RequestOptions . Caso contrário, a solicitação será pendente até que o destino seja reiniciado.

A estrutura define o sinalizador USBD_SHORT_TRANSFER_OK em seu URB interno. Definir esse sinalizador permite que o último pacote de uma transferência de dados seja menor que o tamanho máximo do pacote.

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

Exemplos

O exemplo de código a seguir inicializa uma estrutura WDF_USB_CONTINUOUS_READER_CONFIG e chama WdfUsbTargetPipeConfigContinuousReader.

WDF_USB_CONTINUOUS_READER_CONFIG  contReaderConfig;
NTSTATUS  status;

WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
                                      &contReaderConfig,
                                      OsrFxEvtUsbInterruptPipeReadComplete,
                                      DeviceContext,
                                      sizeof(UCHAR)
                                      );
status = WdfUsbTargetPipeConfigContinuousReader(
                                      Pipe,
                                      &contReaderConfig
                                      );

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Versão mínima do UMDF	2,0
Cabeçalho	wdfusb.h (inclua Wdfusb.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regras de conformidade de DDI	DriverCreate(kmdf), FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbContReader(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)