WdfRequestCreateFromIrp, fonction (wdfrequest.h)

Article
02/27/2024

[S’applique à KMDF uniquement]

La méthode WdfRequestCreateFromIrp crée un objet de requête d’infrastructure à partir d’un IRP WDM spécifié.

Syntaxe

NTSTATUS WdfRequestCreateFromIrp(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in]           PIRP                   Irp,
  [in]           BOOLEAN                RequestFreesIrp,
  [out]          WDFREQUEST             *Request
);

Paramètres

[in, optional] RequestAttributes

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

[in] Irp

Pointeur vers une structure IRP qui contient un paquet de requête d’E/S WDM.

[in] RequestFreesIrp

Valeur booléenne qui, si elle est TRUE, indique que l’infrastructure supprime l’IRP lorsque le handle de requête est détruit. Si la valeur est FALSE, le pilote doit appeler IoFreeIrp pour supprimer l’IRP, en suivant les étapes décrites dans la section Exemples suivante.

[out] Request

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

Valeur retournée

WdfRequestCreateFromIrp retourne STATUS_SUCCESS si l’opération réussit. Pour obtenir la liste des valeurs de retour supplémentaires, consultez Erreurs de création d’objets framework.

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

Remarques

En règle générale, les pilotes basés sur l’infrastructure appellent WdfRequestCreateFromIrp uniquement s’ils reçoivent des IRP WDM dans une routine de distribution WDM, puis transfèrent les demandes aux cibles d’E/S du framework.

Si un pilote appelle WdfRequestCreateFromIrp pour créer un objet de requête, il ne doit pas appeler WdfRequestComplete pour l’objet de requête. Au lieu de cela, le pilote doit appeler WdfObjectDelete lorsqu’il a terminé d’utiliser l’objet de requête.

En outre, le pilote ne doit pas appeler WdfRequestRetrieveOutputMemory, WdfRequestRetrieveOutputBuffer, WdfRequestRetrieveInputBuffer ou WdfRequestRetrieveInputMemory avec le nouvel objet request.

Par défaut, le parent du nouvel objet de requête est l’objet du pilote d’infrastructure créé par la méthode WdfDriverCreate . Vous pouvez utiliser le membre ParentObject de la structure WDF_OBJECT_ATTRIBUTES pour spécifier un autre parent. L’infrastructure supprime l’objet de requête lorsqu’il supprime l’objet parent. Si votre pilote ne modifie pas le parent par défaut, il doit supprimer l’objet de requête lorsqu’il a terminé d’utiliser l’objet ; sinon, l’objet de requête restera jusqu’à ce que le gestionnaire d’E/S décharge votre pilote.

Pour plus d’informations sur la création d’objets de requête d’infrastructure, consultez Création d’objets de requête d’infrastructure.

Les pilotes basés sur l’infrastructure ne doivent pas utiliser le membre Tail.Overlay.DriverContext de la structure IRP , car l’infrastructure utilise ce membre.

Exemples

Exemple 1

L’exemple de code suivant crée un objet de demande d’infrastructure à partir d’un IRP WDM spécifié, puis le supprime. Cet exemple définit le paramètre RequestFreesIrp sur TRUE, de sorte que l’infrastructure supprime l’IRP lorsque le handle de requête est détruit.

WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 TRUE,
                                 &request
                                 );
...
//Deletion
WdfObjectDelete(request);

Exemple 2

L’exemple de code suivant crée également un objet de demande d’infrastructure à partir d’un IRP WDM spécifié, puis le supprime. Cet exemple définit le paramètre RequestFreesIrp sur FALSE. Le pilote doit donc appeler IoFreeIrp pour supprimer l’IRP. Tous les appels de fonction dans l’exemple sont obligatoires.

WDF_REQUEST_REUSE_PARAMS params;
WDFREQUEST request;
PIRP irp;

//Creation
status = WdfRequestCreateFromIrp(
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 irp,
                                 FALSE,
                                 &request
                                 );
...
//Deletion
WDF_REQUEST_REUSE_PARAMS_INIT(
                              &params,
                              WDF_REQUEST_REUSE_NO_FLAGS,
                              STATUS_SUCCESS
                              );
WDF_REQUEST_REUSE_PARAMS_SET_NEW_IRP(
                                     &params,
                                     NULL
                                     );
status = WdfRequestReuse(
                         request,
                         &params
                         );
ASSERT(NT_SUCCESS(status));
IoFreeIrp(irp);
WdfObjectDelete(request);

Configuration requise

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