Méthode IDataModelManager2 ::AcquireSubNamespace (dbgmodel.h)

Article
08/07/2023

La méthode AcquireSubNamespace permet de construire quelque chose qui peut ressembler plus traditionnellement à un espace de noms de langage qu’à un nouvel objet dans un langage dynamique. Si, par instance, un appelant souhaite catégoriser les propriétés d’un objet de processus afin de rendre l’objet de processus plus organisé et les propriétés plus faciles à découvrir, une méthode consiste à créer un sous-objet pour chaque catégorie sur l’objet de processus et à placer ces propriétés à l’intérieur de cet objet. Le problème avec cette notion est que le sous-objet a son propre contexte et les propriétés qui s’y trouvent sont passées comme pointeur instance au lieu de l’objet de processus lui-même. La méthode AcquireSubNamespace permet de créer un « sous-objet » de propriété partagée où le pointeur instance passé aux propriétés du sous-objet est l’objet parent.

Prenons l’exemple d’un objet de processus auquel nous voulons ajouter une propriété Tass représentant le tas de processus (et tous les autres tas personnalisés au sein du processus). Elle peut initialement apparaître comme suit :

    • Process [foo.exe] 
        o Heaps [3 heaps]

Étant donné que l’objet de processus peut avoir de nombreux autres champs et qu’il peut y avoir de nombreux éléments associés à la mémoire dans le processus, un meilleur paradigme peut être :

    • Process [foo.exe] 
        o Memory [A namespace of things associated with Memory in the process] 
             Heaps

Si l’objet Memory ci-dessus est simplement une propriété normale qui renvoie un nouvel objet, lorsqu’un appelant demande someProcess.Memory.Heaps, l’accesseur de propriété pour la propriété Heaps reçoit un objet de contexte (ce pointeur) de l’objet Memory nouvellement créé sans moyen simple de revenir à d’autres attributs du processus. Si l’objet Memory est créé à la place avec la méthode AcquireSubNamespace, le paradigme ressemble à ce qui précède, sauf que l’accesseur de propriété pour tout ce qui se trouve sur l’objet Memory sera plutôt l’objet de processus lui-même. Cela permet à l’implémentation de la propriété Tass de revenir facilement à d’autres attributs du processus. Ce style d’objet est un sous-espace de noms au lieu d’un sous-objet.

Il est important de noter que la méthode AcquireSubNamespace ne peut pas être effectuée avec d’autres méthodes. En fait, il s’agit d’une méthode d’assistance qui effectue les opérations suivantes :

    • Checks if there is a model registered under the name given by subNamespaceModelName. If so, returns it. If not, proceeds to: 

      o Creates and registers a new model under the name given by subNamespaceModelName
      o Acquires the model registered under the name given by modelName.
      o Adds a new property named according to accessName with metadata supplied by the metadata argument. The accessor for this property returns a new object with special properties: 
         The new object has the model created and registered under subNamespaceModelName attached as a parent.
         The parent model has a context adjustor. The context adjustor is a property.
         The context adjustor property getter returns the original process object.

Une fois qu’un sous-espace de noms est créé, sa propriété est considérée comme partagée entre tous les appelants potentiels de la méthode AcquireSubNamespace avec le même ensemble d’arguments. En tant que sémantique de propriété partagée, il est incorrect d’annuler arbitrairement l’inscription d’un sous-espace de noms.

Syntaxe

HRESULT AcquireSubNamespace(
  PCWSTR       modelName,
  PCWSTR       subNamespaceModelName,
  PCWSTR       accessName,
  IKeyStore    *metadata,
  IModelObject **namespaceModelObject
);

Paramètres

modelName

Nom du modèle de données qui est étendu avec un sous-espace de noms.

subNamespaceModelName

Nom du modèle de données qui représente le sous-espace de noms lui-même. Le sous-espace de noms nouvellement créé est un modèle de données qui sera inscrit sous ce nom.

accessName

Une propriété de ce nom est ajoutée au modèle de données inscrit sous le nom donné par l’argument modelName afin d’accéder au sous-espace de noms.

metadata

Métadonnées facultatives à associer à la clé donnée par accessName dans le cas où cet appel est celui qui crée le sous-espace de noms partagé.

namespaceModelObject

Le modèle de données représentant le sous-espace de noms est retourné ici. Ce modèle de données peut avoir été créé par un appel antérieur à la méthode AcquireSubNamespace ou par l’appel actuel. La propriété est considérée comme partagée entre tous les appelants.

Valeur retournée

Cette méthode retourne HRESULT.

Remarques

Exemple de Code

ComPtr<IDataModelManager> spManager;   /* get the data model manager */
ComPtr<IModelObject> spExtensionModel; /* get a data model you want to extend 
                                          some namespace with (see
                                          CreateDataModelObject) */

// Add a shared namespace called "Memory" to Process.  Then extend this namespace 
// with spExtensionModel
ComPtr<IModelObject> spProcessMemory;
if (SUCCEEDED(spManager->AcquireSubNamespace(
    L"Debugger.Models.Process", 
    L"Debugger.Models.Process.Memory", 
    L"Memory", 
    nullptr /* probably should have help metadata! */, 
    &spProcessMemory)))
{
    if (SUCCEEDED(spProcessMemory->AddParentModel(spExtensionModel.Get(), 
                                                  nullptr, 
                                                  false)))
    {
        // The properties on spExtensionModel are now in "Process.Memory.*"
        // In addition, the context (*this*) pointer passed to properties on
        // spExtensionModel is the process object itself, not some empty 
        // synthetic created for the namespace!
    }
}

Configuration requise

Condition requise	Valeur
En-tête	dbgmodel.h

Voir aussi

Interface IDataModelManager2

Partager via