WdfIoQueueCreate, fonction (wdfio.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfIoQueueCreate crée et configure une file d’attente d’E/S pour un appareil spécifié.

Syntaxe

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

Paramètres

[in] Device

Handle de l’objet d’appareil framework auquel la file d’attente sera associée.

[in] Config

Pointeur vers une structure de WDF_IO_QUEUE_CONFIG allouée par l’appelant.

[in, optional] QueueAttributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES allouée par l’appelant qui spécifie les attributs d’objet pour le nouvel objet. Ce paramètre est facultatif et peut être WDF_NO_OBJECT_ATTRIBUTES.

[out, optional] Queue

Pointeur vers un emplacement qui reçoit un handle vers un objet de file d’attente d’infrastructure.

Valeur retournée

WdfIoQueueCreate retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre d’entrée n’est pas valide.
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_IO_QUEUE_CONFIG est incorrecte.
STATUS_POWER_STATE_INVALID	L’infrastructure effectue une opération de gestion de l’alimentation.
STATUS_INSUFFICIENT_RESOURCES	La quantité de mémoire disponible est trop faible.
STATUS_WDF_NO_CALLBACK	La structure WDF_IO_QUEUE_CONFIG ne spécifie aucun gestionnaire de requête et la méthode de répartition n’est pas WdfIoQueueDispatchManual.
STATUS_UNSUCCESSFUL	Le pilote tente de créer une file d’attente par défaut alors qu’une file d’attente par défaut existe déjà pour l’appareil, ou qu’une erreur interne s’est produite.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Chaque appel à WdfIoQueueCreate crée une file d’attente d’E/S pour un appareil. Votre pilote peut créer plusieurs files d’attente d’E/S pour chaque appareil.

Les paramètres Config et QueueAttributes spécifient les attributs de configuration et d’objet de la file d’attente.

Par défaut, l’objet d’appareil framework spécifié par le paramètre Device devient l’objet parent pour le nouvel objet de file d’attente d’infrastructure. Si le pilote spécifie un objet parent dans le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES, l’objet parent peut être un objet d’appareil framework ou tout objet dont la chaîne de parents conduit à un objet d’appareil framework. L’infrastructure supprime l’objet file d’attente lorsqu’il supprime l’objet parent.

Si votre pilote fournit des fonctions de rappel EvtCleanupCallback ou EvtDestroyCallback pour l’objet de file d’attente du framework, l’infrastructure appelle ces fonctions de rappel à l’adresse IRQL = PASSIVE_LEVEL.

Pour plus d’informations sur WdfIoQueueCreate, consultez Création de files d’attente d’E/S.

Exemples

L’exemple de code suivant est la section d’une fonction de rappel EvtDriverDeviceAdd qui crée la file d’attente d’E/S par défaut d’un appareil. L’exemple initialise une structure WDF_IO_QUEUE_CONFIG , puis appelle 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;
    }
...
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfio.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	ChangeQueueState(kmdf),DriverCreate(kmdf), DrvAckIoStop(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)