WdfRequestForwardToParentDeviceIoQueue, fonction (wdfrequest.h)

Article
05/23/2024

[S’applique uniquement à KMDF]

La méthode WdfRequestForwardToParentDeviceIoQueue met en file d’attente d’E/S une requête d’E/S de la file d’attente d’E/S d’un appareil enfant vers une file d’E/S spécifiée de l’appareil parent de l’enfant.

Syntaxe

NTSTATUS WdfRequestForwardToParentDeviceIoQueue(
  [in] WDFREQUEST                   Request,
  [in] WDFQUEUE                     ParentDeviceQueue,
  [in] PWDF_REQUEST_FORWARD_OPTIONS ForwardOptions
);

Paramètres

[in] Request

Handle d’un objet de requête d’infrastructure.

[in] ParentDeviceQueue

Handle d’un objet de file d’attente d’infrastructure.

[in] ForwardOptions

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

Valeur retournée

WdfRequestForwardToParentDeviceIoQueue 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_INFO_LENGTH_MISMATCH	La taille de la structure WDF_REQUEST_FORWARD_OPTIONS fournie n’est pas valide.
STATUS_INVALID_PARAMETER	Un membre de la structure de WDF_REQUEST_FORWARD_OPTIONS fournie contient une valeur non valide.
STATUS_INVALID_DEVICE_REQUEST	Cette valeur est retournée si l’une des opérations suivantes se produit : Le pilote n’a pas obtenu la demande d’E/S à partir d’une file d’attente d’E/S. Les files d’attente d’E/S source et de destination sont identiques. La file d’attente d’E/S spécifiée n’appartient pas à l’appareil parent. Le pilote a activé la progression vers l’avant garantie et la demande d’E/S spécifiée est réservée aux situations de faible mémoire. Le pilote n’a pas appelé WdfPdoInitAllowForwardingRequestToParent.
STATUS_WDF_BUSY	La file d’attente d’E/S spécifiée n’accepte pas de nouvelles demandes.

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

Avant qu’un pilote puisse appeler WdfRequestForwardToParentDeviceIoQueue, il doit appeler WdfPdoInitAllowForwardingRequestToParent.

Le pilote doit utiliser la même méthode pour accéder aux mémoires tampons de données (mises en mémoire tampon, directes ou non) pour l’appareil parent et l’appareil enfant.

Si votre pilote appelle WdfRequestForwardToParentDeviceIoQueue pour mettre en file d’attente une demande d’E/S, le pilote ne doit pas utiliser l’objet request comme parent d’autres objets framework, tels que des objets de minuteur ou des objets d’élément de travail.

Si votre pilote a appelé WdfDeviceInitSetRequestAttributes pour spécifier l’espace de contexte pour les objets de requête de l’appareil parent , l’infrastructure n’ajoute pas cet espace de contexte pour demander les objets que le pilote reçoit dans la file d’attente d’un appareil enfant. Le pilote peut appeler WdfObjectAllocateContext pour ajouter l’espace de contexte à un objet de requête avant que le pilote n’appelle WdfRequestForwardToParentDeviceIoQueue. En revanche, si le pilote a appelé WdfDeviceInitSetRequestAttributes pour les objets de requête de l’appareil enfant et si les objets de requête de l’appareil parent utilisent un espace de contexte égal ou inférieur à l’espace de contexte de l’appareil enfant, le pilote peut utiliser l’espace de contexte de l’objet de requête sans appeler WdfObjectAllocateContext.

Actuellement, le pilote doit utiliser l’option d’envoi et d’oubli pour toutes les demandes d’E/S reléguées. Par conséquent, n’oubliez pas qu’au moment où l’infrastructure supprime un objet de requête en file d’attente, il se peut qu’elle ait déjà supprimé l’appareil enfant qui a reçu à l’origine l’objet de demande. Par conséquent, le pilote ne doit pas utiliser la fonction EvtCleanupCallback ou EvtDestroyCallback d’un objet de requête en file d’attente pour accéder aux ressources d’appareil enfants, car les ressources peuvent être supprimées avant l’exécution de la fonction EvtCleanupCallback ou EvtDestroyCallback .

Pour plus d’informations sur WdfRequestForwardToParentDeviceIoQueue, consultez Nouvelle file d’attente de demandes d’E/S.

Exemples

L’exemple de code suivant détermine d’abord l’appareil parent d’un appareil qui a reçu une demande d’E/S, puis il met la demande d’E/S en file d’attente d’E/S par défaut de l’appareil parent.

WDFDEVICE device, parentDevice;
WDF_REQUEST_FORWARD_OPTIONS forwardOptions;
NTSTATUS status;

device = WdfIoQueueGetDevice(WdfRequestGetIoQueue(Request));
parentDevice = WdfPdoGetParent(device);

WDF_REQUEST_FORWARD_OPTIONS_INIT(&forwardOptions);
status = WdfRequestForwardToParentDeviceIoQueue(
             Request,
             WdfDeviceGetDefaultQueue(parentDevice),
             &forwardOptions
             );
if (!NT_SUCCESS(status)) {
    WdfRequestComplete(
                       Request,
                       status
                       );
  }

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1,9
En-tête	wdfrequest.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion de version de la bibliothèque d’infrastructure.)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf)

Voir aussi

WdfPdoInitAllowForwardingRequestToParent

Partager via