Funzione WdfIoQueueAssignForwardProgressPolicy (wdfio.h)

Articolo
03/22/2025

[Si applica solo a KMDF]

Il metodo WdfIoQueueAssignForwardProgressPolicy consente al framework di garantire lo stato di avanzamento per una coda di I/O specificata.

Sintassi

NTSTATUS WdfIoQueueAssignForwardProgressPolicy(
  [in] WDFQUEUE                              Queue,
  [in] PWDF_IO_QUEUE_FORWARD_PROGRESS_POLICY ForwardProgressPolicy
);

Parametri

[in] Queue

Handle per un oggetto coda del framework.

[in] ForwardProgressPolicy

Puntatore a una struttura WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY allocata dal driver.

Valore restituito

WdfIoQueueAssignForwardProgressPolicy restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno di questi valori:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Un parametro di input non è valido.
STATUS_INFO_LENGTH_MISMATCH	Le dimensioni della struttura WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY non sono corrette.
STATUS_INSUFFICIENT_RESOURCES	La quantità di memoria disponibile è troppo bassa.

Questo metodo potrebbe anche restituire altri valori NTSTATUS . Inoltre, se la funzione di callback del driver EvtIoAllocateResourcesForReservedRequest restituisce un valore di stato di errore, WdfIoQueueAssignForwardProgressPolicy restituisce tale valore.

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

Osservazioni:

Il metodoWdfIoQueueAssignForwardProgressPolicy crea oggetti richiesta che il framework riserva per situazioni di memoria insufficiente e registra funzioni di callback chiamate dal framework per gestire situazioni di memoria insufficiente.

In KMDF versione 1.9, la coda di I/O rappresentata dal parametro coda deve essere una coda di I/O predefinita di un dispositivo o una coda per cui il driver ha chiamato WdfDeviceConfigureRequestDispatching. Il driver può chiamare WdfIoQueueAssignForwardProgressPolicy ogni volta dopo aver chiamato WdfDeviceConfigureRequestDispatching.

In KMDF versioni 1.11 e successive, la coda di I/O rappresentata dal parametro coda può essere qualsiasi coda che riceve una richiesta direttamente dal framework. Ad esempio, il driver potrebbe specificare una coda a cui i runtime di integrazione in avanti dinamicamente.

Prima di restituisce il WdfIoQueueAssignForwardProgressPolicy, il framework esegue le operazioni seguenti:

Crea e archivia il numero di oggetti richiesta specificati dal driver per il TotalForwardProgressRequests membro della struttura WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY.
Se il driver precedentemente chiamato WdfDeviceInitSetRequestAttributes, ogni allocazione include lo spazio di contesto che WdfDeviceInitSetRequestAttributes specificato.
Chiama il evtIoAllocateResourcesForReservedRequest del driver funzione di callback per ogni oggetto richiesta creato dal framework.

Dopo che il driver ha chiamato WdfIoQueueAssignForwardProgressPolicy per creare oggetti richiesta riservati, il framework usa tali oggetti riservati ogni volta che il tentativo di creare un nuovo oggetto richiesta non riesce. In genere, tali errori sono causati da situazioni di memoria insufficiente.

Il framework elimina gli oggetti richiesta riservati solo quando elimina l'oggetto coda del framework a cui appartengono. Se il driver chiama WdfDeviceInitSetRequestAttributes e specifica un EvtCleanupCallback o EvtDestroyCallback funzione di callback per i relativi oggetti richiesta, il framework chiama queste funzioni di callback per gli oggetti richiesta riservati quando elimina gli oggetti.

Per altre informazioni sul metodo di WdfIoQueueAssignForwardProgressPolicy e su come usare la funzionalità di avanzamento forward garantito del framework, vedere Garanzia dello stato di avanzamento delle operazioni di I/O.

Esempi

Questo esempio di codice configura una coda di I/O creata in precedenza per ricevere le richieste di scrittura e quindi abilita lo stato di avanzamento garantito per la coda.

#define MAX_RESERVED_REQUESTS 10

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY queueForwardProgressPolicy;
WDFQUEUE writeQueue;
NTSTATUS status = STATUS_SUCCESS;
...
status = WdfDeviceConfigureRequestDispatching(
             device,
             writeQueue,
             WdfRequestTypeWrite
             );
if(!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY_DEFAULT_INIT(
    &queueForwardProgressPolicy,
    MAX_RESERVED_REQUESTS
    );
status = WdfIoQueueAssignForwardProgressPolicy(
             writeQueue,
             &queueForwardProgressPolicy
             );
if(!NT_SUCCESS(status)) {
    return status;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
versione minima di KMDF	1.9
intestazione	wdfio.h (include Wdf.h)
Biblioteca	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	PASSIVE_LEVEL
regole di conformità DDI	DriverCreate(kmdf)

Vedere anche

EvtIoAllocateResourcesForReservedRequest

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY

WdfDeviceConfigureRequestDispatching

Condividi tramite