The Labs \ Source Viewer \ SSCLI \ System.Diagnostics.SymbolStore \ ISymbolWriter

  1. // ==++==
  2. //
  3. //
  4. // Copyright (c) 2006 Microsoft Corporation. All rights reserved.
  5. //
  6. // The use and distribution terms for this software are contained in the file
  7. // named license.txt, which can be found in the root of this distribution.
  8. // By using this software in any fashion, you are agreeing to be bound by the
  9. // terms of this license.
  10. //
  11. // You must not remove this notice, or any other, from this software.
  12. //
  13. //
  14. // ==--==
  15. /*============================================================
  16. **
  17. ** Class:  ISymbolWriter
  18. **
  19. **
  20. ** Represents a symbol writer for managed code. Provides methods to
  21. ** define documents, sequence points, lexical scopes, and variables.
  22. **
  23. **
  24. ===========================================================*/
  25. namespace System.Diagnostics.SymbolStore
  26. {
  27.    
  28.     using System;
  29.     using System.Text;
  30.     using System.Reflection;
  31.     using System.Runtime.InteropServices;
  32.    
  33.     // Interface does not need to be marked with the serializable attribute
  34.     [System.Runtime.InteropServices.ComVisible(true)]
  35.     public interface ISymbolWriter
  36.     {
  37.         // Set the IMetadataEmitter that this symbol writer is associated
  38.         // with. This must be done only once before any other ISymbolWriter
  39.         // methods are called.
  40.         void Initialize(IntPtr emitter, string filename, bool fFullBuild);
  41.        
  42.         // Define a source document. Guid's will be provided for the
  43.         // languages, vendors, and document types that we currently know
  44.         // about.
  45.         ISymbolDocumentWriter DefineDocument(string url, Guid language, Guid languageVendor, Guid documentType);
  46.        
  47.         // Define the method that the user has defined as their entrypoint
  48.         // for this module. This would be, perhaps, the user's main method
  49.         // rather than compiler generated stubs before main.
  50.         void SetUserEntryPoint(SymbolToken entryMethod);
  51.        
  52.         // Open a method to emit symbol information into. The given method
  53.         // becomes the current method for calls do define sequence points,
  54.         // parameters and lexical scopes. There is an implicit lexical
  55.         // scope around the entire method. Re-opening a method that has
  56.         // been previously closed effectivley erases any previously
  57.         // defined symbols for that method.
  58.         //
  59.         // There can be only one open method at a time.
  60.         void OpenMethod(SymbolToken method);
  61.        
  62.         // Close the current method. Once a method is closed, no more
  63.         // symbols can be defined within it.
  64.         void CloseMethod();
  65.        
  66.         // Define a group of sequence points within the current method.
  67.         // Each line/column defines the start of a statement within a
  68.         // method. The arrays should be sorted by offset. The offset is
  69.         // always the offset from the start of the method, in bytes.
  70.         void DefineSequencePoints(ISymbolDocumentWriter document, int[] offsets, int[] lines, int[] columns, int[] endLines, int[] endColumns);
  71.        
  72.         // Open a new lexical scope in the current method. The scope
  73.         // becomes the new current scope and is effectivley pushed onto a
  74.         // stack of scopes. startOffset is the offset, in bytes from the
  75.         // beginning of the method, of the first instruction in the
  76.         // lexical scope. Scopes must form a hierarchy. Siblings are not
  77.         // allowed to overlap.
  78.         //
  79.         // OpenScope returns an opaque scope id that can be used with
  80.         // SetScopeRange to define a scope's start/end offset at a later
  81.         // time. In this case, the offsets passed to OpenScope and
  82.         // CloseScope are ignored.
  83.         //
  84.         // Note: scope id's are only valid in the current method.
  85.         //
  86.         int OpenScope(int startOffset);
  87.        
  88.         // Close the current lexical scope. Once a scope is closed no more
  89.         // variables can be defined within it. endOffset points past the
  90.         // last instruction in the scope.
  91.         void CloseScope(int endOffset);
  92.        
  93.         // Define the offset range for a given lexical scope.
  94.         void SetScopeRange(int scopeID, int startOffset, int endOffset);
  95.        
  96.         // Define a single variable in the current lexical
  97.         // scope. startOffset and endOffset are optional. If 0, then they
  98.         // are ignored and the variable is defined over the entire
  99.         // scope. If non-zero, then they must fall within the offsets of
  100.         // the current scope. This can be called multiple times for a
  101.         // variable of the same name that has multiple homes throughout a
  102.         // scope. (Note: start/end offsets must not overlap in such a
  103.         // case.)
  104.         void DefineLocalVariable(string name, FieldAttributes attributes, byte[] signature, SymAddressKind addrKind, int addr1, int addr2, int addr3, int startOffset, int endOffset);
  105.        
  106.         // Define a single parameter in the current method. The type of
  107.         // each parameter is taken from its position (sequence) within the
  108.         // method's signature.
  109.         //
  110.         // Note: if parameters are defined in the metadata for a given
  111.         // method, then clearly one would not have to define them again
  112.         // with calls to this method. The symbol readers will have to be
  113.         // smart enough to check the normal metadata for these first then
  114.         // fall back to the symbol store.
  115.         void DefineParameter(string name, ParameterAttributes attributes, int sequence, SymAddressKind addrKind, int addr1, int addr2, int addr3);
  116.        
  117.         // Define a single variable not within a method. This is used for
  118.         // certian fields in classes, bitfields, etc.
  119.         void DefineField(SymbolToken parent, string name, FieldAttributes attributes, byte[] signature, SymAddressKind addrKind, int addr1, int addr2, int addr3);
  120.        
  121.         // Define a single global variable.
  122.         void DefineGlobalVariable(string name, FieldAttributes attributes, byte[] signature, SymAddressKind addrKind, int addr1, int addr2, int addr3);
  123.        
  124.         // Close will close the ISymbolWriter and commit the symbols
  125.         // to the symbol store. The ISymbolWriter becomes invalid
  126.         // after this call for further updates.
  127.         void Close();
  128.        
  129.         // Defines a custom attribute based upon its name. Not to be
  130.         // confused with Metadata custom attributes, these attributes are
  131.         // held in the symbol store.
  132.         void SetSymAttribute(SymbolToken parent, string name, byte[] data);
  133.        
  134.         // Opens a new namespace. Call this before defining methods or
  135.         // variables that live within a namespace. Namespaces can be nested.
  136.         void OpenNamespace(string name);
  137.        
  138.         // Close the most recently opened namespace.
  139.         void CloseNamespace();
  140.        
  141.         // Specifies that the given, fully qualified namespace name is
  142.         // being used within the currently open lexical scope. Closing the
  143.         // current scope will also stop using the namespace, and the
  144.         // namespace will be in use in all scopes that inherit from the
  145.         // currently open scope.
  146.         void UsingNamespace(string fullName);
  147.        
  148.         // Specifies the true start and end of a method within a source
  149.         // file. Use this to specify the extent of a method independently
  150.         // of what sequence points exist within the method.
  151.         void SetMethodSourceRange(ISymbolDocumentWriter startDoc, int startLine, int startColumn, ISymbolDocumentWriter endDoc, int endLine, int endColumn);
  152.        
  153.         // Used to set the underlying ISymUnmanagedWriter that a
  154.         // managed ISymbolWriter may use to emit symbols with.
  155.         void SetUnderlyingWriter(IntPtr underlyingWriter);
  156.     }
  157.    
  158. }

Developer Fusion