Méthode IDebugHostSymbols ::CreateTypeSignature (dbgmodel.h)

Article
02/26/2024

La méthode CreateTypeSignature crée une signature qui peut être utilisée pour faire correspondre un ensemble de types concrets en contenant le module et le nom de type. Le format de la chaîne de signature de nom de type est spécifique à la langue en cours de débogage (et à l’hôte de débogage). Pour C/C++, la chaîne de signature équivaut à une spécification de type NatVis. Autrement dit, la chaîne de signature est un nom de type où les caractères génériques (spécifiés sous la forme *) sont autorisés pour les arguments de modèle.

Syntaxe

HRESULT CreateTypeSignature(
  PCWSTR                  signatureSpecification,
  IDebugHostModule        *module,
  IDebugHostTypeSignature **typeSignature
);

Paramètres

signatureSpecification

Chaîne de signature qui identifie les types auxquels cette signature s’applique. Le format de cette chaîne est spécifique à la langue en cours de débogage. Pour C/C++, cela équivaut à une spécification de type NatVis. Il s’agit d’un nom de type où les caractères génériques sont autorisés pour les arguments de modèle (spécifiés sous la forme d’un *).

module

S’ils sont spécifiés, seuls les types contenus dans le module donné correspondent à la signature. S’ils ne sont pas spécifiés, les types d’un module peuvent potentiellement correspondre à la signature.

typeSignature

L’objet de signature de type créé est retourné ici.

Valeur retournée

Cette méthode retourne HRESULT qui indique la réussite ou l’échec.

Remarques

Exemple de Code

ComPtr<IDebugHost> spHost; /* get the host */

ComPtr<IDebugHostSymbols> spSym;
if (SUCCEEDED(spHost.As(&spSym)))
{
    // Create a type signature for MyTemplateType<*>
    ComPtr<IDebugHostTypeSignature> spSig1;
    if (SUCCEEDED(spSym->CreateTypeSignature(L"MyTemplateType<*>", 
                                             nullptr, 
                                             &spSig1)))
    {
        // spSig1 is a type signature which will match any concrete template 
        // type with a base name of MyTemplateType and *ANY* template arguments.
        // This is true regardless of the module in which the type is contained.
    }

    ComPtr<IDebugHostModule> spMyModule;
    if (SUCCEEDED(spSym->FindModuleByName(USE_CURRENT_HOST_CONTEXT, 
                                          L"MyModule.dll", 
                                          &spMyModule)))
    {
        // Create a type signature for MyTemplateType<*> within MyModule.dll.
        ComPtr<IDebugHostTypeSignature> spSig2;
        if (SUCCEEDED(spSym->CreateTypeSignature(L"MyTemplateType<*>", 
                                                 nullptr, 
                                                 &spSig2)))
        {
            // spSig2 is a type signature which will match any concrete 
            // template type with a base name of MyTemplateType and *ANY* 
            // template arguments that is within the particular MyModule.dll 
            // that's in the current UI context (e.g.: process) of the debugger.
            // This means if the host is debugging multiple processes
            // and you switch processes, a MyTemplateType<*> in an identically
            // named and versioned MyModule.dll will *NOT* match this signature.
        }
    }
}

Différences dans la correspondance des modules de symboles dans FindModuleByName, CreateTypeSignature et CreateTypeSignatureForModuleRange

FindModuleByName permet au nom du module passé d’être le nom réel de l’image du module, par exemple My Module.dll, ou celui par lequel vous pouvez le référencer dans le moteur de débogueur (par exemple, MyModule ou MyModule_<hex_base>).

L’appel de CreateTypeSignatureForModuleRange et le passage d’un nom/nullptr/nullptr crée une signature qui correspond à n’importe quel module qui correspond au nom de n’importe quelle version.

Le nom du module passé aux fonctions CreateTypeSignature n’accepte que le nom réel de l’image du module (par exemple, MyModule.dll).

L’appel de FindModuleByName, puis CreateTypeSignature avec ce module crée une signature qui correspondra uniquement au instance particulier du module qui lui est passé. S’il y a deux copies d’un module qui est chargé (par exemple : ntdll dans un processus 32 bits s’exécutant sur Windows 64 bits), il correspond uniquement à la instance spécifique passée. Elle ne correspondrait plus non plus si cette DLL était déchargée et rechargée. La signature est associée à un instance spécifique d’un module tel que connu par le débogueur.