Funzione WdfUsbTargetDeviceFormatRequestForCyclePort (wdfusb.h)

[Si applica solo a KMDF]

Il metodo WdfUsbTargetDeviceFormatRequestForCyclePort compila una richiesta di ciclo di alimentazione per la porta a cui è collegato un dispositivo specificato, ma non invia la richiesta.

Sintassi

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

Parametri

[in] UsbDevice

Handle per un oggetto dispositivo USB ottenuto da una chiamata precedente a WdfUsbTargetDeviceCreateWithParameters.

[in] Request

Handle per un oggetto richiesta del framework. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

WdfUsbTargetDeviceFormatRequestForCyclePort restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo può restituire uno dei valori seguenti:

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Commenti

Usare WdfUsbTargetDeviceFormatRequestForCyclePort, seguito da WdfRequestSend, per inviare una richiesta di ciclo di alimentazione in modo sincrono o asincrono. In alternativa, usare il metodo WdfUsbTargetDeviceCyclePortSynchronously per inviare una richiesta in modo sincrono.

Prima che il driver chiami WdfRequestSend, deve chiamare WdfIoTargetStop e deve completare o annullare tutte le richieste di I/O inviate alla destinazione di I/O. Il driver non deve inviare richieste di I/O aggiuntive alla destinazione di I/O fino al completamento della richiesta di ciclo.

È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure creare e inviare una nuova richiesta.

Per inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O, specificare l'handle della richiesta ricevuta per il parametro Request del metodo WdfUsbTargetDeviceFormatRequestForCyclePort.

Per creare una nuova richiesta di I/O, chiamare WdfRequestCreate per preallocare un oggetto richiesta. Specificare l'handle di richiesta per il parametro Request del metodo WdfUsbTargetDeviceFormatRequestForCyclePort. È possibile riutilizzare l'oggetto richiesta chiamando WdfRequestReuse. La funzione di callback EvtDriverDeviceAdd del driver può preallocare oggetti richiesta per un dispositivo.

Dopo aver chiamato WdfUsbTargetDeviceFormatRequestForCyclePort per formattare una richiesta di I/O, il driver deve chiamare WdfRequestSend per inviare la richiesta (in modo sincrono o asincrono) a una destinazione di I/O. Questa chiamata a WdfRequestSend deve essere effettuata in IRQL = PASSIVE_LEVEL.

Più chiamate a WdfUsbTargetDeviceFormatRequestForCyclePort che usano la stessa richiesta non causano allocazioni di risorse aggiuntive. Pertanto, per ridurre la probabilità che WdfRequestCreate restituisca STATUS_INSUFFICIENT_RESOURCES, la funzione di callback EvtDriverDeviceAdd del driver può chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta per un dispositivo. Il driver può successivamente riutilizzare (chiamare WdfRequestReuse), riformattare (chiamare WdfUsbTargetDeviceFormatRequestForCyclePort) e inviare di nuovo (chiamare WdfRequestSend) ogni oggetto richiesta senza rischiare un valore restituito STATUS_INSUFFICIENT_RESOURCES da una chiamata successiva a WdfRequestCreate. Tutte le chiamate successive a WdfUsbTargetDeviceFormatRequestForCyclePort per l'oggetto richiesta riutilizzato restituiranno STATUS_SUCCESS, se i valori dei parametri non cambiano. Se il driver non chiama lo stesso metodo di formattazione delle richieste ogni volta, è possibile allocare risorse aggiuntive.

Per altre informazioni sul metodo WdfUsbTargetDeviceFormatRequestForCyclePort e sulle destinazioni di I/O USB, vedere Destinazioni di I/O USB.

Esempio

L'esempio di codice seguente formatta una richiesta di ciclo di alimentazione, registra una funzione di callback CompletionRoutine e invia la richiesta a una destinazione di I/O.

status = WdfUsbTargetDeviceFormatRequestForCyclePort(
                                            UsbDevice,
                                            request
                                            );
if (!NT_SUCCESS(status)){
    return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyCompletionRoutine,
                               NULL
                               );

if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

Requisiti

Vedi anche

EvtDriverDeviceAdd

WdfRequestReuse

WdfRequestSend

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceCyclePortSynchronously