WdfRequestCreate, fonction (wdfrequest.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfRequestCreate crée un objet de requête d’infrastructure vide.

Syntaxe

NTSTATUS WdfRequestCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in, optional] WDFIOTARGET            IoTarget,
  [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, optional] IoTarget

Handle pour un objet cible d’E/S de framework. Ce paramètre est facultatif et peut être NULL. Si la valeur n’est pas NULL, WdfRequestCreate vérifie que le pilote peut éventuellement envoyer la demande à la cible d’E/S spécifiée.

[out] Request

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

Valeur retournée

WdfRequestCreate 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_INSUFFICIENT_RESOURCES	Les ressources système sont insuffisantes pour terminer l’opération.
STATUS_REQUEST_NOT_ACCEPTED	Le tableau d’emplacements de la pile d’E/S de la demande n’est pas assez grand pour permettre au pilote d’envoyer la demande à la cible d’E/S spécifiée.

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

Un pilote basé sur l’infrastructure peut appeler WdfRequestCreate pour créer une nouvelle requête que le pilote transmet par la suite à d’autres fonctions d’infrastructure pour l’initialisation. Par exemple, un pilote pour un périphérique USB peut appeler WdfUsbTargetPipeFormatRequestForRead pour mettre en forme une nouvelle demande de lecture.

Un pilote basé sur l’infrastructure qui communique avec les pilotes WDM peut spécifier le contenu d’une requête en appelant WdfRequestCreateFromIrp.

Si un pilote appelle WdfRequestCreate 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. Pour plus d’informations, consultez Terminer les demandes d’E/S.

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 l’appel de WdfRequestCreate, consultez Création d’objets de requête d’infrastructure.

Exemples

L’exemple de code suivant crée un objet cible d’E/S, initialise une structure WDF_OBJECT_ATTRIBUTES et appelle WdfRequestCreate. Le parent du nouvel objet de requête est l’objet cible d’E/S.

WDF_OBJECT_ATTRIBUTES  attributes;
WDFREQUEST newRequest;
WDFIOTARGET ioTarget;
...
status = WdfIoTargetCreate(
                           Device,
                           WDF_NO_OBJECT_ATTRIBUTES,
                           &ioTarget
                           );
  ...
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = ioTarget;

status = WdfRequestCreate(
                          &attributes,
                          ioTarget,
                          &newRequest
                          );

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	wdfrequest.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReqDelete(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting2(kmdf)