Funzione WdfRequestForwardToIoQueue (wdfrequest.h)

Articolo
02/27/2024

[Si applica a KMDF e UMDF]

Il metodo WdfRequestForwardToIoQueue esegue nuovamente una richiesta di I/O a una delle code I/O del driver chiamante.

Sintassi

NTSTATUS WdfRequestForwardToIoQueue(
  [in] WDFREQUEST Request,
  [in] WDFQUEUE   DestinationQueue
);

Parametri

[in] Request

Handle per un oggetto richiesta framework.

[in] DestinationQueue

Handle a un oggetto code del framework.

Valore restituito

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

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	Questo valore viene restituito se si verifica una delle operazioni seguenti: Il driver non ha ottenuto la richiesta da una coda di I/O. Le code di origine e di destinazione sono uguali. Le code di origine e di destinazione non appartengono allo stesso dispositivo. Il driver non possiede la richiesta. La richiesta è annullabile.
STATUS_WDF_BUSY	La coda di destinazione non accetta nuove richieste.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Il driver deve avere la richiesta di I/O e deve avere ottenuto la richiesta da una delle relative code di I/O.

Le code di origine e di destinazione non possono essere uguali. In altre parole, il driver non può chiamare WdfRequestForwardToIoQueue per restituire una richiesta alla coda da cui proviene. Per riassegnare una richiesta alla stessa coda, usare WdfRequestRequeue.

Sia le code di origine che di destinazione devono appartenere allo stesso dispositivo.

La richiesta non deve essere annullabile. Se il driver ha chiamato WdfRequestMarkCancelable o WdfRequestMarkCancelableEx per rendere la richiesta annullabile, deve chiamare WdfRequestUnmarkCancelable prima di chiamare WdfRewardToIoQueue.

Dopo che il driver chiama WdfRequestForwardToIoQueue, il driver non possiede la richiesta riqueued finché il framework non recapita la richiesta dalla nuova coda al driver. Mentre la richiesta si trova nella nuova coda, il framework possiede la richiesta e può annullarla senza notificare il driver.

Prima che WdfRequestForwardToIoQueue restituisca, gli eventi seguenti possono verificarsi:

Se la coda di destinazione è vuota, il framework può recapitare la richiesta di I/O riqueued a uno dei gestori delle richieste della coda di destinazione.
Se il metodo di invio della coda di origine è sequenziale o parallelo, il framework può recapitare un'altra richiesta a uno dei gestori delle richieste della coda di origine.

Per altre informazioni su WdfRequestForwardToIoQueue, vedere Ripetizione delle richieste di I/O e gestione delle code di I/O.

Esempio

L'esempio di codice seguente è una funzione di callback EvtIoDeviceControl dal driver di esempio PCIDRV . Se una richiesta ricevuta contiene un codice di controllo I/O di IOCTL_NDISPROT_INDICATE_STATUS, il driver chiama WdfRequestForwardToIoQueue per spostare la richiesta in una coda di I/O diversa.

VOID
PciDrvEvtIoDeviceControl(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  OutputBufferLength,
    IN size_t  InputBufferLength,
    IN ULONG  IoControlCode
    )
{
    NTSTATUS  status= STATUS_SUCCESS;
    PFDO_DATA  fdoData = NULL;
    WDFDEVICE  hDevice;
    WDF_REQUEST_PARAMETERS  params;

    UNREFERENCED_PARAMETER(OutputBufferLength);
    UNREFERENCED_PARAMETER(InputBufferLength);

    hDevice = WdfIoQueueGetDevice(Queue);
    fdoData = FdoGetData(hDevice);

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );

    switch (IoControlCode)
    {
        case IOCTL_NDISPROT_QUERY_OID_VALUE:
            NICHandleQueryOidRequest(
                                     Queue,
                                     Request,
                                     &params
                                     );
            break;

        case IOCTL_NDISPROT_SET_OID_VALUE:
            NICHandleSetOidRequest(
                                   Queue,
                                   Request,
                                   &params
                                   );
            break;

        case IOCTL_NDISPROT_INDICATE_STATUS:
            status = WdfRequestForwardToIoQueue(
                                                Request,
                                                fdoData->PendingIoctlQueue
                                                );
            if(!NT_SUCCESS(status)){
                WdfRequestComplete(
                                   Request,
                                   status
                                   );
                break;
            }
            break;

        default:
            WdfRequestComplete(
                               Request,
                               STATUS_INVALID_DEVICE_REQUEST
                               );
            break;
    }
    return;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfrequest.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InvalidReqAccess(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)