Função WdfUsbTargetPipeFormatRequestForAbort (wdfusb.h)

[Aplica-se a KMDF e UMDF]

O método WdfUsbTargetPipeFormatRequestForAbort cria uma solicitação de anulação de um pipe USB especificado, mas não envia a solicitação.

Sintaxe

NTSTATUS WdfUsbTargetPipeFormatRequestForAbort(
  [in] WDFUSBPIPE Pipe,
  [in] WDFREQUEST Request
);

Parâmetros

[in] Pipe

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

[in] Request

Um identificador para um objeto de solicitação de estrutura. Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

WdfUsbTargetPipeFormatRequestForAbort retorna o valor de status de conclusão do destino de E/S 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_INVALID_PARAMETER	Um parâmetro inválido foi detectado.
STATUS_INSUFFICIENT_RESOURCES	Memória insuficiente disponível.
STATUS_REQUEST_NOT_ACCEPTED	O IRP (pacote de solicitação de E/S) que o parâmetro Request 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.

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

Comentários

Use WdfUsbTargetPipeFormatRequestForAbort, seguido por WdfRequestSend, para enviar uma solicitação de anulação USB de forma síncrona ou assíncrona. Como alternativa, use o método WdfUsbTargetPipeAbortSynchronously para enviar uma solicitação de forma síncrona.

Uma solicitação de anulação de USB faz com que o destino de E/S do driver cancele todas as solicitações de E/S que foram enviadas para um pipe. Quando um driver chama WdfRequestSend, a estrutura envia uma solicitação URB_FUNCTION_ABORT_PIPE para o destino de E/S. Para obter mais informações sobre como cancelar operações em um pipe USB (também chamado de "anular um pipe"), consulte a especificação USB.

Você pode encaminhar uma solicitação de E/S recebida pelo driver 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 Request do método WdfUsbTargetPipeFormatRequestForAbort.

Para criar uma nova solicitação de E/S, chame WdfRequestCreate para pré-alocar um objeto de solicitação. Forneça o identificador de solicitação para o parâmetro Request do método WdfUsbTargetPipeFormatRequestForAbort. Você pode reutilizar o objeto de solicitação chamando WdfRequestReuse. A função de retorno de chamada EvtDriverDeviceAdd do driver pode pré-alocar objetos de solicitação para um dispositivo.

Depois de chamar WdfUsbTargetPipeFormatRequestForAbort para formatar uma solicitação de E/S, o driver deve chamar WdfRequestSend para enviar a solicitação (de forma síncrona ou assíncrona) para um destino de E/S.

Várias chamadas para WdfUsbTargetPipeFormatRequestForAbort que usam a mesma solicitação não causam alocações de recursos adicionais. Portanto, para reduzir a chance de WdfRequestCreate retornar STATUS_INSUFFICIENT_RESOURCES, a função de retorno de chamada EvtDriverDeviceAdd do driver pode chamar WdfRequestCreate para pré-alocar um ou mais objetos de solicitação para um dispositivo. O driver pode reutilizar posteriormente (chamar WdfRequestReuse), reformat (chamar WdfUsbTargetPipeFormatRequestForAbort) e reenviar (chamar WdfRequestSend) cada objeto de solicitação sem arriscar uma STATUS_INSUFFICIENT_RESOURCES retornar valor de uma chamada posterior para WdfRequestCreate. Todas as chamadas subsequentes para WdfUsbTargetPipeFormatRequestForAbort para o objeto de solicitação reutilizado retornarão STATUS_SUCCESS, se os valores de parâmetro não forem alterados. (Se o driver não chamar o mesmo método de formatação de solicitação todas as vezes, recursos adicionais poderão ser alocados.)

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 WdfUsbTargetPipeFormatRequestForAbort e destinos de E/S USB, consulte Destinos de E/S USB.

Exemplos

O exemplo de código a seguir formata uma solicitação de anulação de um pipe USB, registra uma função de retorno de chamada CompletionRoutine e envia a solicitação.

status = WdfUsbTargetPipeFormatRequestForAbort(
                                               pipe,
                                               Request
                                               );
if (!NT_SUCCESS(status)) {
    goto Exit;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               AbortCompletionRoutine,
                               pipe
                               );

if (WdfRequestSend(
                   Request,
                   WdfUsbTargetPipeGetIoTarget(pipe),
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
    goto Exit;
}
Exit:
if (!NT_SUCCESS(status)) {
    WdfRequestCompleteWithInformation(
                                      Request,
                                      status,
                                      0
                                      );
}
return;

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), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Confira também

WdfUsbInterfaceGetConfiguredPipe