WDF_OBJECT_ATTRIBUTES structure (wdfobject.h)

Article
02/29/2024

[S’applique à KMDF et UMDF]

La structure WDF_OBJECT_ATTRIBUTES décrit les attributs qui peuvent être associés à n’importe quel objet framework.

Syntaxe

typedef struct _WDF_OBJECT_ATTRIBUTES {
  ULONG                          Size;
  PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
  PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
  WDF_EXECUTION_LEVEL            ExecutionLevel;
  WDF_SYNCHRONIZATION_SCOPE      SynchronizationScope;
  WDFOBJECT                      ParentObject;
  size_t                         ContextSizeOverride;
  PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
} WDF_OBJECT_ATTRIBUTES, *PWDF_OBJECT_ATTRIBUTES;

Membres

Size

Taille, en octets, de cette structure.

EvtCleanupCallback

Pointeur vers la fonction de rappel EvtCleanupCallback du pilote, ou NULL.

EvtDestroyCallback

Pointeur vers la fonction de rappel EvtDestroyCallback du pilote, ou NULL.

ExecutionLevel

Valeur de type WDF_EXECUTION_LEVEL qui spécifie l’IRQL maximal auquel l’infrastructure appellera les fonctions de rappel d’événement de l’objet. Pour obtenir la liste des objets d’infrastructure pour lesquels le pilote peut spécifier une valeur ExecutionLevel , consultez WDF_EXECUTION_LEVEL.

SynchronizationScope

Valeur de type WDF_SYNCHRONIZATION_SCOPE qui spécifie comment l’infrastructure synchronisera l’exécution des fonctions de rappel d’événement de l’objet. Pour obtenir la liste des objets d’infrastructure pour lesquels le pilote peut spécifier une valeur SynchronizationScope , consultez WDF_SYNCHRONIZATION_SCOPE.

ParentObject

Handle de l’objet parent de l’objet, ou NULL si l’objet n’a pas de parent spécifié par le pilote.

Consultez Résumé des objets d’infrastructure pour obtenir un tableau montrant les objets qui autorisent un parent spécifié par un pilote. Le tableau affiche également le parent par défaut de chaque objet.

ContextSizeOverride

Si elle n’est pas égale à zéro, cette valeur remplace le membre ContextSize de la structure WDF_OBJECT_CONTEXT_TYPE_INFO que le membre ContextTypeInfo référence. Cette valeur est facultative et peut être égale à zéro. Si la valeur n’est pas égale à zéro, elle doit spécifier une taille, en octets, supérieure à la valeur spécifiée pour le membre ContextSize de la structure WDF_OBJECT_CONTEXT_TYPE_INFO. Pour plus d'informations, consultez la section Notes qui suit.

ContextTypeInfo

Pointeur vers une structure WDF_OBJECT_CONTEXT_TYPE_INFO . La macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE définit ce pointeur.

Remarques

La structure WDF_OBJECT_ATTRIBUTES est utilisée comme argument d’entrée pour plusieurs méthodes qui créent des objets framework.

Pour initialiser une structure WDF_OBJECT_ATTRIBUTES, le pilote doit appeler WDF_OBJECT_ATTRIBUTES_INIT.

En outre, si vous définissez des informations de contexte spécifiques à un objet pour un objet, vous devez utiliser la macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE .

Vous pouvez également utiliser la macro WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE au lieu des macros WDF_OBJECT_ATTRIBUTES_INIT et WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE.

Pour plus d’informations sur l’utilisation de ces macros, consultez Framework Object Context Space.

Utilisez le membre ContextSizeOverride de WDF_OBJECT_ATTRIBUTES si vous souhaitez créer un espace de contexte d’objet dont la longueur est variable. Par exemple, vous pouvez définir une structure d’espace de contexte qui contient un tableau, comme suit :

typedef struct _MY_REQUEST_CONTEXT {
  ULONG  ByteCount;
  BYTE  Bytes[1];
} MY_REQUEST_CONTEXT, *PMY_REQUEST_CONTEXT;

WDF_DECLARE_CONTEXT_TYPE(MY_REQUEST_CONTEXT);

Lorsque votre pilote crée un objet qui utilise la structure d’espace de contexte, il peut utiliser le membre ContextSizeOverride pour spécifier la taille de contexte nécessaire pour chaque objet individuel. Par exemple, votre pilote peut calculer le nombre d’octets nécessaires dans le tableau à partir de l’exemple précédent, puis utiliser ContextSizeOverride pour spécifier les octets supplémentaires, comme suit :

WDF_OBJECT_ATTRIBUTES MyRequestObjectAttributes;
PMY_REQUEST_CONTEXT pMyContext;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &MyRequestObjectAttributes,
                                        MY_REQUEST_CONTEXT
                                        );
MyRequestObjectAttributes.ContextSizeOverride =
                          sizeof(MY_REQUEST_CONTEXT) + Num_Extra_Bytes - 1;

Le pilote peut ensuite créer un objet avec une taille de contexte personnalisée.

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

Pour plus d’informations sur les règles de nettoyage d’une hiérarchie d’objets d’infrastructure, consultez Framework Object Life Cycle.