Funzione WdfDeviceEnqueueRequest (wdfdevice.h)

Articolo
02/27/2024

[Si applica solo a KMDF]

Il metodo WdfDeviceEnqueueRequest recapita una richiesta di I/O specificata al framework, in modo che il framework possa successivamente aggiungere la richiesta a una delle code di I/O create dal driver per il dispositivo specificato.

Sintassi

NTSTATUS WdfDeviceEnqueueRequest(
  [in] WDFDEVICE  Device,
  [in] WDFREQUEST Request
);

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] Request

Handle per un oggetto richiesta framework.

Valore restituito

Se l'operazione ha esito positivo, il metodo restituisce STATUS_SUCCESS. I valori restituiti aggiuntivi includono:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	La quantità di memoria disponibile è bassa.
STATUS_INVALID_DEVICE_REQUEST	Il driver non ha creato code di I/O per il dispositivo e il driver non è un driver di filtro.
STATUS_WDF_BUSY	La coda di I/O del dispositivo non accetta richieste.

Il metodo potrebbe restituire altri valori NTSTATUS.

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

Commenti

Il driver può chiamare WdfDeviceEnqueueRequest solo da una funzione di callback EvtIoInCallerContext .

Il metodo WdfDeviceEnqueueRequest aggiunge la richiesta alla coda di I/O specifica del driver per il dispositivo, se il driver ne ha creato uno. In caso contrario, il metodo aggiunge la richiesta alla coda predefinita del dispositivo, se il driver ne ha creato uno.

Se il driver non ha creato code di I/O per il dispositivo, WdfDeviceEnqueueRequest esegue le operazioni seguenti:

Se il driver è un driver di filtro, WdfDeviceEnqueueRequest invia la richiesta alla destinazione I/O del driver.
Se il driver non è un driver di filtro, WdfDeviceEnqueueRequest restituisce STATUS_INVALID_DEVICE_REQUEST.

Durante l'esecuzione di WdfDeviceEnqueueRequest , è possibile che il driver riceva e completi o annulla la richiesta.

Di conseguenza, se il driver deve usare la richiesta o il relativo contesto dopo aver chiamato WdfDeviceEnqueueRequest, deve prendere un riferimento nella richiesta prima di chiamare WdfDeviceEnqueueRequest.

A tale scopo, il driver può chiamare WdfObjectReference prima e quindi WdfObjectDereference dopo la chiamata a WdfDeviceEnqueueRequest. Il driver deve dereferenziare la richiesta prima di uscire da EvtIoInCallerContext.

Per altre informazioni sul metodo WdfDeviceEnqueueRequest , vedere Gestione delle code di I/O.

Per le versioni 1.0 e 1.5 di KMDF, è necessario chiamare WdfDeviceEnqueueRequest in PASSIVE_LEVEL. Per le versioni 1.7 e successive, WdfDeviceEnqueueRequest può essere chiamato in IRQL <= DISPATCH_LEVEL.

Esempio

L'esempio di codice seguente è una funzione di callback EvtIoInCallerContext che cerca le richieste che contengono il codice di controllo I/O personalizzato, IOCTL_NONPNP_METHOD_NEITHER. Se il codice di controllo I/O non viene trovato, la funzione di callback restituisce solo la richiesta al framework. Se la funzione di callback trova il codice di controllo I/O, pre-elabora la richiesta e quindi la restituisce al framework. Se viene rilevato un errore, la funzione di callback completa la richiesta.

VOID
MyEvtDeviceIoInCallerContext(
    IN WDFDEVICE  Device,
    IN WDFREQUEST Request
    )
{
    NTSTATUS  status = STATUS_SUCCESS;
    WDF_REQUEST_PARAMETERS  params;

    WDF_REQUEST_PARAMETERS_INIT(&params);
    WdfRequestGetParameters(
                            Request,
                            &params
                            );
    if(!(params.Type == WdfRequestTypeDeviceControl &&
         params.Parameters.DeviceIoControl.IoControlCode == IOCTL_NONPNP_METHOD_NEITHER)) {
        status = WdfDeviceEnqueueRequest(
                                         Device,
                                         Request
                                         );
        if(!NT_SUCCESS(status)) {
            goto End;
        }
        return;
    }
    //
    // Found a match for the control code. Preprocess the request, and then
    // return the request to the framework.
    //

    //...(Preprocess the request here.)

    status = WdfDeviceEnqueueRequest(
                                     Device,
                                     Request
                                     );
    if(!NT_SUCCESS(status)) {
        goto End;
    }
    return;
End:
    WdfRequestComplete(
                       Request,
                       status
                       );
    return;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Intestazione	wdfdevice.h (includere Wdf.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	<= DISPATCH_LEVEL (vedere la sezione osservazioni)
Regole di conformità DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)

Vedi anche

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters

Condividi tramite