Funzione WdfDeviceEnqueueRequest (wdfdevice.h)

Articolo
02/07/2025

[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 .

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

Osservazioni

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

Il metodo WdfDeviceEnqueueRequest aggiunge la richiesta alla coda di I/O specifica del tipo di richiesta 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.

Mentre 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 accettare un riferimento alla 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 EvtIoInCallerContext.

Per altre informazioni sul metodo WdfDeviceEnqueueRequest, vedere Managing I/O Queues.

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

Esempi

L'esempio di codice seguente è un EvtIoInCallerContext funzione di callback che cerca le richieste che contengono il codice di controllo I/O personalizzato IOCTL_NONPNP_METHOD_NEITHER. Se il codice di controllo di I/O non viene trovato, la funzione di callback restituisce semplicemente la richiesta al framework. Se la funzione di callback trova il codice di controllo I/O, pre-elabora la richiesta e 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;
}

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
intestazione	wdfdevice.h (include Wdf.h)
libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
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)

Vedere anche

WDF_REQUEST_PARAMETERS_INIT

WdfRequestComplete

WdfRequestGetParameters

Condividi tramite