Função WdfUsbTargetPipeResetSynchronously (wdfusb.h)

Artigo
07/16/2024

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetPipeResetSynchronously cria uma solicitação de redefinição e a envia de forma síncrona para um pipe USB especificado.

Sintaxe

NTSTATUS WdfUsbTargetPipeResetSynchronously(
  [in]           WDFUSBPIPE                Pipe,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions
);

Parâmetros

[in] Pipe

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

[in, optional] Request

Um identificador para um objeto de solicitação de estrutura. Esse parâmetro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários a seguir.

[in, optional] RequestOptions

Um ponteiro para uma estrutura de WDF_REQUEST_SEND_OPTIONS alocada pelo chamador que especifica opções para a solicitação. Esse ponteiro é opcional e pode ser NULL. Para obter mais informações, consulte a seção Comentários a seguir.

Valor de retorno

WdfUsbTargetPipeResetSynchronously retorna o valor de status de conclusão do destino de E/S USB 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
STATUS_INFO_LENGTH_MISMATCH	O tamanho da estrutura de WDF_REQUEST_SEND_OPTIONS que o parâmetro RequestOptions especificado estava incorreto.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_INSUFFICIENT_RESOURCES	Memória insuficiente estava disponível.
STATUS_INVALID_DEVICE_REQUEST	O IRQL do chamador não foi PASSIVE_LEVEL ou a solicitação de E/S de que o parâmetro de solicitação de especificado já estava na fila para um destino de E/S.
STATUS_IO_TIMEOUT	O driver forneceu um valor de tempo limite e a solicitação não foi concluída dentro do tempo alocado.
STATUS_REQUEST_NOT_ACCEPTED	O pacote de solicitação de E/S (IRP) que o parâmetro de solicitação de representa não fornece estruturas de IO_STACK_LOCATION suficientes para permitir que o driver encaminhe a solicitação.

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

Uma verificação de bug ocorre se o driver fornece um identificador de objeto inválido.

Observações

Use o método WdfUsbTargetPipeResetSynchronously para enviar uma solicitação de redefinição USB de forma síncrona. Para enviar essas solicitações de forma assíncrona, use WdfUsbTargetPipeFormatRequestForReset, seguido por WdfRequestSend.

Antes que a estrutura redefina o pipe USB do destino de E/S, ele cancela todas as solicitações de E/S que permanecem na fila do destino de E/S. O driver não deve enviar solicitações de E/S adicionais para o destino de E/S até WdfUsbTargetPipeResetSynchronously retorna.

O driver deve chamar WdfIoTargetStop antes de chamar WdfUsbTargetPipeResetSynchronously. Depois que wdfUsbTargetPipeResetSynchronously retorna, o driver pode chamar WdfIoTargetStart.

Quando um driver chama WdfUsbTargetPipeResetSynchronously, a estrutura envia uma solicitação URB_FUNCTION_RESET_PIPE para o destino de E/S. Para obter mais informações sobre como redefinir um pipe USB, consulte a especificação USB.

O método WdfUsbTargetPipeResetSynchronously não retorna até que a solicitação seja concluída, a menos que o driver forneça um valor de tempo limite na estrutura WDF_REQUEST_SEND_OPTIONS à qual o RequestOptions parâmetro aponta ou a menos que um erro seja detectado.

Você pode encaminhar uma solicitação de E/S que seu driver recebeu em uma fila de E/S ou pode criar e enviar uma nova solicitação.

Para encaminhar uma solicitação de E/S recebida pelo driver em uma fila de E/S, especifique o identificador da solicitação recebida para o parâmetro WdfUsbTargetPipeResetSynchronously parâmetro de solicitação de do método.

Para criar e enviar uma nova solicitação, forneça um identificador de solicitação NULL para o parâmetro solicitação ou crie um novo objeto de solicitação e forneça seu identificador:

Se você fornecer um identificador de solicitação NULL, a estrutura usará um objeto de solicitação interno. Essa técnica é simples de usar, mas o driver não pode cancelar a solicitação.
Se você chamar WdfRequestCreate para criar um ou mais objetos de solicitação, você poderá reutilizar esses objetos de solicitação chamando WdfRequestReuse. Essa técnica permite que o do driver EvtDriverDeviceAdd função de retorno de chamada para pré-alocar objetos de solicitação para um dispositivo. Além disso, outro thread de driver pode chamar WdfRequestCancelSentRequest para cancelar a solicitação, se necessário.

O driver pode especificar um parâmetroNULL nãoRequestOptions, independentemente de o driver fornecer uma NULL nãoou um parâmetro de solicitação deNULL . Você pode, por exemplo, usar o parâmetro RequestOptions para especificar um valor de tempo limite.

Para obter informações sobre como obter informações de status após a conclusão de uma solicitação de E/S, consulte Obtendo informações de conclusão.

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

Exemplos

O exemplo de código a seguir envia uma solicitação de redefinição para o pipe de um dispositivo USB.

NTSTATUS  status;

status = WdfUsbTargetPipeResetSynchronously(
                                            Pipe, 
                                            WDF_NO_HANDLE,
                                            NULL
                                            );

Requisitos

Requisito	Valor
da 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	PASSIVE_LEVEL
regras de conformidade de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestforUrbXrb(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Consulte também

WdfObjectDereference

WdfRequestCancelSentRequest

WdfRequestSend

WdfUsbTargetPipeAbortSynchronously

Compartilhar via