Funzione WdfIoQueueCreate (wdfio.h)

Articolo
03/22/2025

[Si applica a KMDF e UMDF]

Il metodo WdfIoQueueCreate crea e configura una coda di I/O per un dispositivo specificato.

Sintassi

NTSTATUS WdfIoQueueCreate(
  [in]            WDFDEVICE              Device,
  [in]            PWDF_IO_QUEUE_CONFIG   Config,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES QueueAttributes,
  [out, optional] WDFQUEUE               *Queue
);

Parametri

[in] Device

Handle per l'oggetto dispositivo framework a cui verrà associata la coda.

[in] Config

Puntatore a una struttura di WDF_IO_QUEUE_CONFIG allocata dal chiamante.

[in, optional] QueueAttributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES allocata dal chiamante che specifica gli attributi dell'oggetto per il nuovo oggetto. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[out, optional] Queue

Puntatore a una posizione che riceve un handle per un oggetto coda del framework.

Valore restituito

WdfIoQueueCreate 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_PARAMETER	Un parametro di input non è valido.
STATUS_INFO_LENGTH_MISMATCH	Le dimensioni della struttura WDF_IO_QUEUE_CONFIG non sono corrette.
STATUS_POWER_STATE_INVALID	Il framework esegue un'operazione di risparmio energia.
STATUS_INSUFFICIENT_RESOURCES	La quantità di memoria disponibile è troppo bassa.
STATUS_WDF_NO_CALLBACK	La struttura WDF_IO_QUEUE_CONFIG non specifica alcun gestore di richiesta e il metodo di invio non è WdfIoQueueDispatchManual.
STATUS_UNSUCCESSFUL	Il driver sta tentando di creare una coda predefinita mentre esiste già una coda predefinita per il dispositivo o si è verificato un errore interno.

Questo metodo potrebbe anche restituire altri valori NTSTATUS .

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

Osservazioni:

Ogni chiamata a WdfIoQueueCrea crea una coda di I/O per un dispositivo. Il driver può creare più code di I/O per ogni dispositivo.

I parametri config e queueAttributes specificano gli attributi di configurazione e oggetto della coda.

Per impostazione predefinita, l'oggetto dispositivo framework specificato dal parametro device diventa l'oggetto padre per il nuovo oggetto coda del framework. Se il driver specifica un oggetto padre nella struttura WDF_OBJECT_ATTRIBUTESmembro ParentObject, l'oggetto padre può essere un oggetto dispositivo framework o qualsiasi oggetto la cui catena di elementi padre conduce a un oggetto dispositivo framework. Il framework eliminerà l'oggetto queue quando elimina l'oggetto padre.

Se il driver fornisce EvtCleanupCallback o EvtDestroyCallback funzioni di callback per l'oggetto coda del framework, il framework chiama queste funzioni di callback in IRQL = PASSIVE_LEVEL.

Per altre informazioni su WdfIoQueueCreare, vedere Creazione di code di I/O.

Esempi

L'esempio di codice seguente è la sezione di un EvtDriverDeviceAdd funzione di callback che crea la coda di I/O predefinita di un dispositivo. Nell'esempio viene inizializzata una struttura di WDF_IO_QUEUE_CONFIG e quindi viene chiamato WdfIoQueueCreare.

NTSTATUS
MyEvtDriverDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_IO_QUEUE_CONFIG  ioQueueConfig;
    WDFQUEUE  hQueue;
...
    WDF_IO_QUEUE_CONFIG_INIT_DEFAULT_QUEUE(
                                           &ioQueueConfig,
                                           WdfIoQueueDispatchSequential
                                           );

    ioQueueConfig.EvtIoDefault = MyEvtIoDefault;

    status = WdfIoQueueCreate(
                              device,
                              &ioQueueConfig,
                              WDF_NO_OBJECT_ATTRIBUTES,
                              &hQueue
                              );
    if (!NT_SUCCESS (status)) {
        return status;
    }
...
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	2.0
intestazione	wdfio.h (include Wdf.h)
Biblioteca	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= LIVELLO_DI_INVIO
regole di conformità DDI	ChangeQueueState(kmdf), DriverCreate(kmdf), DrvAckIoStop(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)