Espace de contexte de l’objet framework

  • Article

L’espace de contexte d’objet est un espace mémoire supplémentaire, non modifiable, qu’un pilote peut allouer et affecter à un objet. Chaque pilote basé sur l’infrastructure peut créer un ou plusieurs espaces de contexte spécifiques à l’objet pour chaque objet d’infrastructure que le pilote reçoit ou crée.

Les pilotes basés sur l’infrastructure doivent stocker toutes les données spécifiques à l’objet, par valeur ou par pointeur, dans l’espace de contexte de l’objet auquel les données appartiennent.

Par exemple, un pilote pour les périphériques USB peut créer un espace de contexte pour ses objets de périphérique d’infrastructure. Dans l’espace de contexte, le pilote peut stocker des informations spécifiques au périphérique telles que les structures de USB_DEVICE_DESCRIPTOR et de USB_CONFIGURATION_DESCRIPTOR de l’appareil, ainsi qu’un handle vers un objet de collection qui représente les canaux d’une interface de périphérique.

L’infrastructure ne transmet pas d’objets d’infrastructure d’un pilote à un autre. Vous ne pouvez donc pas utiliser l’espace de contexte d’un objet pour passer des données entre deux pilotes.

Pour définir l’espace de contexte d’un objet, vous devez créer une ou plusieurs structures. Chaque structure représente un espace de contexte distinct. Votre pilote utilisera chaque membre de structure pour stocker un élément d’informations spécifiques à l’objet. En outre, votre pilote doit demander à l’infrastructure de générer une méthode d’accesseur pour chaque structure. Cette méthode d’accesseur accepte un handle d’objet comme entrée et retourne l’adresse de l’espace de contexte de l’objet.

Chaque fois que votre pilote appelle une méthode de création d’objet, telle que WdfDeviceCreate, la méthode alloue éventuellement de l’espace contextuel. Toutes les méthodes de création d’objet acceptent une structure WDF_OBJECT_ATTRIBUTES facultative comme entrée. Cette structure décrit l’espace de contexte que vous souhaitez que l’infrastructure alloue à l’objet .

Pour ajouter de l’espace contextuel à un objet après que le pilote a appelé la méthode de création de l’objet, le pilote peut appeler la méthode WdfObjectAllocateContext qui, comme les méthodes de création d’objet, accepte une structure WDF_OBJECT_ATTRIBUTES comme entrée.

Lorsque l’infrastructure alloue de l’espace de contexte pour un objet, elle initialise également l’espace de contexte à zéro.

Quand l’infrastructure ou un pilote supprime un objet framework, l’infrastructure supprime tout l’espace de contexte de l’objet.

Si votre pilote utilise l’espace contextuel pour stocker les pointeurs vers les mémoires tampons qu’il alloue lorsqu’il crée un objet, il doit fournir une fonction EvtCleanupCallback qui libère les tampons lorsque l’objet est supprimé.

Pour définir la structure d’espace de contexte et la méthode d’accesseur d’un objet pour les objets créés par votre pilote, votre pilote doit effectuer les étapes suivantes :

  1. Définissez une structure qui décrit les données que vous souhaitez stocker. Par exemple, si vous souhaitez créer des données de contexte pour les objets de périphérique de votre pilote, votre pilote peut définir une structure appelée MY_DEVICE_CONTEXT.

  2. Utilisez la macro WDF_DECLARE_CONTEXT_TYPE ou la macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME . Ces deux macros effectuent les opérations suivantes :

    • Créez et initialisez une structure WDF_OBJECT_CONTEXT_TYPE_INFO .
    • Définissez une méthode d’accesseur que votre pilote utilisera ultérieurement pour accéder à l’espace contextuel d’un objet. La valeur de retour de la méthode d’accesseur est un pointeur vers l’espace de contexte de l’objet.

    La macro WDF_DECLARE_CONTEXT_TYPE crée le nom de la méthode d’accesseur à partir du nom de votre structure. Par exemple, si le nom de votre structure de contexte est MY_DEVICE_CONTEXT, la macro crée une méthode d’accesseur nommée WdfObjectGet_MY_DEVICE_CONTEXT.

    La macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME vous permet de spécifier le nom de la méthode d’accesseur. Par exemple, vous pouvez spécifier GetMyDeviceContext comme nom de votre méthode d’accesseur de contexte pour les objets d’appareil.

  3. Appelez WDF_OBJECT_ATTRIBUTES_INIT pour initialiser la structure WDF_OBJECT_ATTRIBUTES de l’objet .

  4. Utilisez la macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE pour définir le membre ContextTypeInfo de la structure WDF_OBJECT_ATTRIBUTES sur l’adresse de la structure WDF_OBJECT_CONTEXT_TYPE_INFO.

  5. Appelez une méthode de création d’objet, telle que WdfDeviceCreate.

Une fois que votre pilote a créé un objet, il peut appeler WdfObjectAllocateContext à tout moment pour ajouter de l’espace contextuel supplémentaire à l’objet.

Étant donné que les étapes 1 et 2 définissent des structures de données globales et créent une routine pouvant être appelée par un pilote, votre pilote doit effectuer ces étapes dans une zone du pilote qui déclare des données globales, généralement un fichier d’en-tête. Ces étapes ne doivent pas être effectuées à partir des routines de votre pilote.

Votre pilote doit effectuer les étapes 3, 4 et 5 à partir d’une routine de pilote qui crée un objet, comme une fonction de rappel EvtDriverDeviceAdd qui appelle WdfDeviceCreate.

L’infrastructure peut créer deux types d’objets : les objets de requête d’infrastructure et les objets de fichier d’infrastructure pour le compte de votre pilote. Votre pilote peut inscrire l’espace de contexte pour ces objets en appelant respectivement WdfDeviceInitSetRequestAttributes et WdfDeviceInitSetFileObjectConfig. Votre pilote peut également appeler WdfObjectAllocateContext pour allouer de l’espace contextuel à ces objets.

Une fois qu’un objet a été créé, le pilote peut obtenir un pointeur vers l’espace de contexte de l’objet à l’aide de l’une des techniques suivantes :

Si votre pilote a un pointeur d’espace de contexte, il peut trouver l’objet auquel appartient l’espace de contexte en appelant WdfObjectContextGetObject.