Funzione WdfIoQueueCreate (wdfio.h)

Articolo
08/08/2023

[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 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 a 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 delle richieste 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 restituire anche altri valori NTSTATUS.

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

Commenti

Ogni chiamata a WdfIoQueueCreate 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 nel membro ParentObject della struttura di WDF_OBJECT_ATTRIBUTES, l'oggetto padre può essere un oggetto dispositivo framework o qualsiasi oggetto la cui catena di genitori porta a un oggetto dispositivo framework. Il framework eliminerà l'oggetto coda quando elimina l'oggetto padre.

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

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

Esempio

L'esempio di codice seguente è la sezione di una funzione evtDriverDeviceAdd callback che crea la coda di I/O predefinita di un dispositivo. L'esempio inizializza una struttura WDF_IO_QUEUE_CONFIG e quindi chiama WdfIoQueueCreate.

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 KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfio.h (includere Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Regole di conformità DDI	ChangeQueueState(kmdf), DriverCreate(kmdf), DrvAckIoStop(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)