Função WdfUsbTargetDeviceFormatRequestForCyclePort (wdfusb.h)
[Aplica-se somente ao KMDF]
O método WdfUsbTargetDeviceFormatRequestForCyclePort cria uma solicitação de ciclo de energia para a porta à qual um dispositivo especificado está anexado, mas não envia a solicitação.
Sintaxe
NTSTATUS WdfUsbTargetDeviceFormatRequestForCyclePort(
[in] WDFUSBDEVICE UsbDevice,
[in] WDFREQUEST Request
);
Parâmetros
[in] UsbDevice
Um identificador para um objeto de dispositivo USB que foi obtido de uma chamada anterior para WdfUsbTargetDeviceCreateWithParameters.
[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
WdfUsbTargetDeviceFormatRequestForCyclePort 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 |
|---|---|
|
O dispositivo USB do dispositivo não estava disponível. |
|
Memória insuficiente disponível. |
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 WdfUsbTargetDeviceFormatRequestForCyclePort, seguido por WdfRequestSend, para enviar uma solicitação de ciclo de energia de forma síncrona ou assíncrona. Como alternativa, use o método WdfUsbTargetDeviceCyclePortSynchronously 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 ciclo seja concluída.
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 WdfUsbTargetDeviceFormatRequestForCyclePort.
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 WdfUsbTargetDeviceFormatRequestForCyclePort. 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 WdfUsbTargetDeviceFormatRequestForCyclePort 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. Essa chamada para WdfRequestSend deve ser feita em IRQL = PASSIVE_LEVEL.
Várias chamadas para WdfUsbTargetDeviceFormatRequestForCyclePort 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 WdfUsbTargetDeviceFormatRequestForCyclePort) 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 WdfUsbTargetDeviceFormatRequestForCyclePort 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 mais informações sobre o método WdfUsbTargetDeviceFormatRequestForCyclePort 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 ciclo de energia, registra uma função de retorno de chamada CompletionRoutine e envia a solicitação para um destino de E/S.
status = WdfUsbTargetDeviceFormatRequestForCyclePort(
UsbDevice,
request
);
if (!NT_SUCCESS(status)){
return status;
}
WdfRequestSetCompletionRoutine(
request,
MyCompletionRoutine,
NULL
);
if (WdfRequestSend(
request,
WdfUsbTargetDeviceGetIoTarget(UsbDevice),
NULL
) == FALSE) {
status = WdfRequestGetStatus(request);
}
Requisitos
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Versão mínima do KMDF | 1.0 |
| Cabeçalho | wdfusb.h (include Wdfusb.h) |
| Biblioteca | Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.) |
| IRQL | <=DISPATCH_LEVEL |
| Regras de conformidade da DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |