Espace du contexte de l’objet Framework

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

Les pilotes basés sur un Framework 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 d’appareil Framework. Dans l’espace de contexte, le pilote peut stocker ces informations spécifiques à l’appareil comme les structures USB_DEVICE_DESCRIPTOR et 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 passe pas d’objets Framework d’un pilote à un autre. par conséquent, vous ne pouvez 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 utilise chaque membre de structure pour stocker une partie des 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 l’espace de contexte. 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 allouer à l’infrastructure pour l’objet.

Pour ajouter un espace de contexte supplémentaire à 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.

Lorsque l’infrastructure ou un pilote supprime un objet Framework, le Framework supprime tout l’espace de contexte de l’objet.

Si votre pilote utilise l’espace de contexte pour stocker les pointeurs vers les mémoires tampons que le pilote alloue lorsqu’il crée un objet, le pilote doit fournir une fonction EvtCleanupCallback qui libère les mémoires 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 que votre pilote crée, votre pilote doit suivre 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 périphériques 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 de contexte 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 de 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, le pilote peut appeler WdfObjectAllocateContext à tout moment pour ajouter un espace de contexte supplémentaire à l’objet.

Étant donné que les étapes 1 et 2 définissent les 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 dans les 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, tel qu’une fonction de rappel EvtDriverDeviceAdd qui appelle WdfDeviceCreate.

L’infrastructure peut créer deux types d’objets : les objets de requête de l’infrastructure et les objets de fichiers d’infrastructure, pour le compte de votre pilote. Votre pilote peut inscrire l’espace de contexte pour ces objets en appelant WdfDeviceInitSetRequestAttributes et WdfDeviceInitSetFileObjectConfig, respectivement. Votre pilote peut également appeler WdfObjectAllocateContext pour allouer de l’espace de contexte pour 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.