Función WdfUsbTargetDeviceFormatRequestForCyclePort (wdfusb.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfUsbTargetDeviceFormatRequestForCyclePort crea una solicitud de ciclo de energía para el puerto al que está conectado un dispositivo especificado, pero no envía la solicitud.

Sintaxis

NTSTATUS WdfUsbTargetDeviceFormatRequestForCyclePort(
  [in] WDFUSBDEVICE UsbDevice,
  [in] WDFREQUEST   Request
);

Parámetros

[in] UsbDevice

Identificador de un objeto de dispositivo USB obtenido de una llamada anterior a WdfUsbTargetDeviceCreateWithParameters.

[in] Request

Identificador de un objeto de solicitud de marco. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

Valor devuelto

WdfUsbTargetDeviceFormatRequestForCyclePort devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método puede devolver uno de los valores siguientes:

Código devuelto	Descripción
STATUS_INVALID_DEVICE_STATE	El dispositivo USB del dispositivo no estaba disponible.
STATUS_INSUFFICIENT_RESOURCES	Memoria insuficiente disponible.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Comentarios

Use WdfUsbTargetDeviceFormatRequestForCyclePort, seguido de WdfRequestSend, para enviar una solicitud de ciclo de energía de forma sincrónica o asincrónica. Como alternativa, use el método WdfUsbTargetDeviceCyclePortSynchronously para enviar una solicitud de forma sincrónica.

Antes de que el controlador llame a WdfRequestSend, debe llamar a WdfIoTargetStop y debe completar o cancelar todas las solicitudes de E/S que ha enviado al destino de E/S. El controlador no debe enviar solicitudes de E/S adicionales al destino de E/S hasta que se complete la solicitud de ciclo.

Puede reenviar una solicitud de E/S que el controlador recibió en una cola de E/S o puede crear y enviar una nueva solicitud.

Para reenviar una solicitud de E/S que el controlador recibió en una cola de E/S, especifique el identificador de la solicitud recibida para el parámetro Request del método WdfUsbTargetDeviceFormatRequestForCyclePort.

Para crear una nueva solicitud de E/S, llame a WdfRequestCreate para prealcalizar un objeto de solicitud. Proporcione el identificador de solicitud para el parámetro Request del método WdfUsbTargetDeviceFormatRequestForCyclePort. Puede reutilizar el objeto de solicitud llamando a WdfRequestReuse. La función de devolución de llamada EvtDriverDeviceAdd del controlador puede asignar previamente objetos de solicitud para un dispositivo.

Después de llamar a WdfUsbTargetDeviceFormatRequestForCyclePort para dar formato a una solicitud de E/S, el controlador debe llamar a WdfRequestSend para enviar la solicitud (ya sea de forma sincrónica o asincrónica) a un destino de E/S. Esta llamada a WdfRequestSend debe realizarse en IRQL = PASSIVE_LEVEL.

Varias llamadas a WdfUsbTargetDeviceFormatRequestForCyclePort que usan la misma solicitud no provocan asignaciones de recursos adicionales. Por lo tanto, para reducir la posibilidad de que WdfRequestCreate devuelva STATUS_INSUFFICIENT_RESOURCES, la función de devolución de llamada EvtDriverDeviceAdd del controlador puede llamar a WdfRequestCreate para asignar previamente uno o varios objetos de solicitud para un dispositivo. Posteriormente, el controlador puede reutilizar (llamar a WdfRequestReuse), formatear (llamar a WdfUsbTargetDeviceFormatRequestForCyclePort) y reenviar (llamar a WdfRequestSend) cada objeto de solicitud sin arriesgar un valor devuelto STATUS_INSUFFICIENT_RESOURCES desde una llamada posterior a WdfRequestCreate. Todas las llamadas posteriores a WdfUsbTargetDeviceFormatRequestForCyclePort para el objeto de solicitud reutilizado devolverán STATUS_SUCCESS, si los valores de parámetro no cambian. (Si el controlador no llama al mismo método de formato de solicitud cada vez, se pueden asignar recursos adicionales).

Para obtener más información sobre el método WdfUsbTargetDeviceFormatRequestForCyclePort y los destinos de E/S USB, consulte Destinos de E/S USB.

Ejemplos

En el ejemplo de código siguiente se da formato a una solicitud de ciclo de energía, se registra una función de devolución de llamada CompletionRoutine y se envía la solicitud a un 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	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Encabezado	wdfusb.h (incluya Wdfusb.h)
Library	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
IRQL	<=DISPATCH_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)