Função WdfUsbTargetPipeFormatRequestForReset (wdfusb.h)
[Aplica-se a KMDF e UMDF]
O método WdfUsbTargetPipeFormatRequestForReset cria uma solicitação de redefinição para um pipe USB especificado, mas não envia a solicitação.
Sintaxe
NTSTATUS WdfUsbTargetPipeFormatRequestForReset(
[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
WdfUsbTargetPipeFormatRequestForReset 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 pode retornar um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
|
Um parâmetro inválido foi detectado. |
|
Memória insuficiente disponível. |
|
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 WdfUsbTargetPipeFormatRequestForReset, seguido por WdfRequestSend, para enviar uma solicitação de redefinição de USB de forma síncrona ou assíncrona. Como alternativa, use o método WdfUsbTargetPipeResetSynchronously para enviar uma solicitação de forma síncrona.
Antes que o driver chame WdfRequestSend, ele deve chamar WdfIoTargetStop e deve concluir ou cancelar todas as solicitações de E/S enviadas para o destino de E/S. O driver não deve enviar solicitações de E/S adicionais para o destino de E/S até que a solicitação de redefinição seja concluída.
Quando um driver chama WdfRequestSend, a estrutura envia uma solicitação de 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.
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 WdfUsbTargetPipeFormatRequestForReset.
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 WdfUsbTargetPipeFormatRequestForReset. 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 WdfUsbTargetPipeFormatRequestForReset 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 WdfUsbTargetPipeFormatRequestForReset 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 (chamar WdfRequestReuse), reformatar (chamar WdfUsbTargetPipeFormatRequestForReset) e reenviar (chamar WdfRequestSend) cada objeto de solicitação sem arriscar um valor retornado STATUS_INSUFFICIENT_RESOURCES de uma chamada posterior para WdfRequestCreate. Todas as chamadas subsequentes para WdfUsbTargetPipeFormatRequestForReset 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 a cada vez, 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 WdfUsbTargetPipeFormatRequestForReset 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 redefinição para um pipe USB, registra uma função de retorno de chamada CompletionRoutine e envia a solicitação.
status = WdfUsbTargetPipeFormatRequestForReset(
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 (include Wdfusb.h) |
| Biblioteca | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Regras de conformidade da DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |