home *** CD-ROM | disk | FTP | other *** search
/ io Programmo 40 / IOPROG_40.ISO / SOFT / NETFrameworkSDK.exe / comsdk.cab / corsym.idl < prev    next >
Encoding:
Text File  |  2000-06-23  |  36.5 KB  |  963 lines
  1. /*****************************************************************************
  2.  **                                                                         **
  3.  ** Corsym.idl - COM+ Runtime Debugging Symbol                              **
  4.  **              Reader/Wrier/Binder Interfaces.                            **
  5.  **                                                                         **
  6.  ** Copyright (c) 1996-2000 Microsoft Corporation.  All Rights Reserved.    **
  7.  **                                                                         **
  8.  *****************************************************************************/
  9.  
  10.  
  11. /* ------------------------------------------------------------------------- *
  12.  * Imported types
  13.  * ------------------------------------------------------------------------- */
  14.  
  15. #if !DUMMY_DEFINITIONS_BECAUSE_I_CANT_FIGURE_OUT_HOW_TO_IMPORT_THESE
  16. cpp_quote("#if 0")
  17. #ifdef _WIN64
  18. import "unknwn.idl";
  19. #else
  20. #include "basetsd.h"
  21. #endif
  22.  
  23. typedef UINT32 mdToken;
  24. typedef mdToken mdTypeDef;
  25. typedef mdToken mdMethodDef;
  26. typedef SIZE_T IMAGE_DEBUG_DIRECTORY;
  27.  
  28. cpp_quote("#endif")
  29. #endif
  30.  
  31. /* ------------------------------------------------------------------------- *
  32.  * Guids for known languages, language vendors, and document types
  33.  * ------------------------------------------------------------------------- */
  34.  
  35. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_C = { 0x63a08714, 0xfc37, 0x11d2, { 0x90, 0x4c, 0x0, 0xc0, 0x4f, 0xa3, 0x02, 0xa1 } };")
  36. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_CPlusPlus = { 0x3a12d0b7, 0xc26c, 0x11d0, { 0xb4, 0x42, 0x0, 0xa0, 0x24, 0x4a, 0x1d, 0xd2 } };")
  37. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_CSharp = { 0x3f5162f8, 0x07c6, 0x11d3, { 0x90, 0x53, 0x0, 0xc0, 0x4f, 0xa3, 0x02, 0xa1 } };")
  38. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_Basic = { 0x3a12d0b8, 0xc26c, 0x11d0, { 0xb4, 0x42, 0x0, 0xa0, 0x24, 0x4a, 0x1d, 0xd2 } };")
  39. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_Java = { 0x3a12d0b4, 0xc26c, 0x11d0, { 0xb4, 0x42, 0x0, 0xa0, 0x24, 0x4a, 0x1d, 0xd2 } };")
  40. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_Cobol = { 0xaf046cd1, 0xd0e1, 0x11d2, { 0x97, 0x7c, 0x0, 0xa0, 0xc9, 0xb4, 0xd5, 0xc } };")
  41. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_Pascal = { 0xaf046cd2, 0xd0e1, 0x11d2, { 0x97, 0x7c, 0x0, 0xa0, 0xc9, 0xb4, 0xd5, 0xc } };")
  42. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_ILAssembly = { 0xaf046cd3, 0xd0e1, 0x11d2, { 0x97, 0x7c, 0x0, 0xa0, 0xc9, 0xb4, 0xd5, 0xc } };")
  43. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_JScript = { 0x3a12d0b6, 0xc26c, 0x11d0, { 0xb4, 0x42, 0x00, 0xa0, 0x24, 0x4a, 0x1d, 0xd2 } };")
  44. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_SMC = { 0xd9b9f7b, 0x6611, 0x11d3, { 0xbd, 0x2a, 0x0, 0x0, 0xf8, 0x8, 0x49, 0xbd } };")
  45. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageType_MCPlusPlus = { 0x4b35fde8, 0x07c6, 0x11d3, { 0x90, 0x53, 0x0, 0xc0, 0x4f, 0xa3, 0x02, 0xa1 } };")
  46. cpp_quote("extern GUID __declspec(selectany) CorSym_LanguageVendor_Microsoft = { 0x994b45c4, 0xe6e9, 0x11d2, { 0x90, 0x3f, 0x00, 0xc0, 0x4f, 0xa3, 0x02, 0xa1 } };")
  47. cpp_quote("extern GUID __declspec(selectany) CorSym_DocumentType_Text = { 0x5a869d0b, 0x6611, 0x11d3, { 0xbd, 0x2a, 0x0, 0x0, 0xf8, 0x8, 0x49, 0xbd } };")
  48. cpp_quote("extern GUID __declspec(selectany) CorSym_DocumentType_MC =   { 0xeb40cb65, 0x3c1f, 0x4352, { 0x9d, 0x7b, 0xba, 0xf, 0xc4, 0x7a, 0x9d, 0x77 } };")
  49.  
  50. /* ------------------------------------------------------------------------- *
  51.  * Forward declarations
  52.  * ------------------------------------------------------------------------- */
  53.  
  54. interface ISymUnmanagedDocument;
  55. interface ISymUnmanagedDocumentWriter;
  56. interface ISymUnmanagedMethod;
  57. interface ISymUnmanagedNamespace;
  58. interface ISymUnmanagedReader;
  59. interface ISymUnmanagedScope;
  60. interface ISymUnmanagedVariable;
  61. interface ISymUnmanagedWriter;
  62. interface ISymUnmanagedBinder;
  63.  
  64. /* ------------------------------------------------------------------------- *
  65.  * CorSymAddrKind -- specifies the kinds of addresses used by the interfaces
  66.  * ------------------------------------------------------------------------- */
  67.  
  68. typedef enum CorSymAddrKind
  69. {
  70.     /*
  71.      * ADDR_IL_OFFSET: addr1 = IL local var or param index.
  72.      */
  73.     ADDR_IL_OFFSET = 1,
  74.  
  75.     /*
  76.      * ADDR_NATIVE_RVA: addr1 = RVA into module.
  77.      */
  78.     ADDR_NATIVE_RVA = 2,
  79.  
  80.     /*
  81.      * ADDR_NATIVE_REGISTER: addr1 = register the var is stored in.
  82.      */
  83.     ADDR_NATIVE_REGISTER = 3,
  84.  
  85.     /*
  86.      * ADDR_NATIVE_REGREL: addr1 = register, addr2 = offset.
  87.      */
  88.     ADDR_NATIVE_REGREL = 4,
  89.  
  90.     /*
  91.      * ADDR_NATIVE_OFFSET: addr1 = offset from start of parent.
  92.      */
  93.     ADDR_NATIVE_OFFSET = 5,
  94.  
  95.     /*
  96.      * ADDR_NATIVE_REGREG: addr1 = reg low, addr2 = reg high.
  97.      */
  98.     ADDR_NATIVE_REGREG = 6,
  99.  
  100.     /*
  101.      * ADDR_NATIVE_REGSTK: addr1 = reg low, addr2 = reg stk, addr3 = offset.
  102.      */
  103.     ADDR_NATIVE_REGSTK = 7,
  104.  
  105.     /*
  106.      * ADDR_NATIVE_STKREG: addr1 = reg stk, addr2 = offset, addr3 = reg high.
  107.      */
  108.     ADDR_NATIVE_STKREG = 8,
  109.  
  110.     /*
  111.      * ADDR_BITFIELD: addr1 = field start, addr = field length.
  112.      */
  113.     ADDR_BITFIELD = 9
  114. } CorSymAddrKind;
  115.  
  116. /* ------------------------------------------------------------------------- *
  117.  * Library defintion
  118.  * ------------------------------------------------------------------------- */
  119.  
  120. [
  121.   uuid(7E348441-7E1F-380E-A0F6-22668F0F9E4B),
  122.   version(1.0),
  123.   helpstring("Com+ Runtime Symbol Store 1.0 Type Library")
  124. ]
  125. library CorSymLib
  126. {
  127.     importlib("STDOLE2.TLB");
  128.  
  129.     [
  130.         uuid(108296C1-281E-11d3-BD22-0000F80849BD)
  131.     ]
  132.     coclass CorSymWriter
  133.     {
  134.         [default] interface ISymUnmanagedWriter;
  135.     };
  136.  
  137.     [
  138.         uuid(108296C2-281E-11d3-BD22-0000F80849BD)
  139.     ]
  140.     coclass CorSymReader
  141.     {
  142.         [default] interface ISymUnmanagedReader;
  143.     };
  144.  
  145.     [
  146.         uuid(AA544D41-28CB-11d3-BD22-0000F80849BD)
  147.     ]
  148.     coclass CorSymBinder
  149.     {
  150.         [default] interface ISymUnmanagedBinder;
  151.     };
  152. };
  153.  
  154. /* ------------------------------------------------------------------------- *
  155.  * ISymUnmanagedBinder interface
  156.  * ------------------------------------------------------------------------- */
  157.  
  158. [
  159.  object,
  160.  uuid(AA544D42-28CB-11d3-BD22-0000F80849BD),
  161.  pointer_default(unique)
  162. ]
  163. interface ISymUnmanagedBinder : IUnknown
  164. {
  165.     /*
  166.      * Given a metadata interface and a file name, returns the
  167.      * correct ISymUnmanagedReader that will read the debugging symbols
  168.      * associated with the module.
  169.      *
  170.      * The searchPath parameter is optional.
  171.      */
  172.     HRESULT GetReaderForFile([in] IUnknown *importer,
  173.                              [in] const WCHAR *fileName,
  174.                              [in] const WCHAR *searchPath,
  175.                              [out, retval] ISymUnmanagedReader **pRetVal);
  176.     HRESULT GetReaderFromStream([in] IUnknown *importer,
  177.                                 [in] IStream *pstream,
  178.                                 [out,retval] ISymUnmanagedReader **pRetVal);
  179. };
  180.  
  181. /* ------------------------------------------------------------------------- *
  182.  * ISymUnmanagedDocument interface
  183.  * ------------------------------------------------------------------------- */
  184.  
  185. [
  186.  object,
  187.  uuid(40DE4037-7C81-3E1E-B022-AE1ABFF2CA08),
  188.  pointer_default(unique)
  189. ]
  190. interface ISymUnmanagedDocument : IUnknown
  191. {
  192.     /*
  193.      * Return the URL for this document.
  194.      */
  195.     HRESULT GetURL([in] ULONG32 cchUrl,
  196.                    [out] ULONG32 *pcchUrl,
  197.                    [out, size_is(cchUrl),
  198.                    length_is(*pcchUrl)] WCHAR szUrl[]);
  199.  
  200.     /*
  201.      * Get the document type of this document.
  202.      */
  203.     HRESULT GetDocumentType([out, retval] GUID* pRetVal);
  204.  
  205.     /*
  206.      * Get the language id of this document.
  207.      */
  208.     HRESULT GetLanguage([out, retval] GUID* pRetVal);
  209.  
  210.     /*
  211.      * Get the language vendor of this document.
  212.      */
  213.     HRESULT GetLanguageVendor([out, retval] GUID* pRetVal);
  214.  
  215.     /*
  216.      * Get the check sum algorithm id. Returns a guid of all zeros if
  217.      * there is no checksum.
  218.      */
  219.     HRESULT GetCheckSumAlgorithmId([out, retval] GUID* pRetVal);
  220.  
  221.     /*
  222.      * Get the check sum.
  223.      */
  224.     HRESULT GetCheckSum([in] ULONG32 cData,
  225.                         [out] ULONG32 *pcData,
  226.                         [out, size_is(cData),
  227.                         length_is(*pcData)] BYTE data[]);
  228.  
  229.     /*
  230.      * Given a line in this document that may or may not be a sequence
  231.      * point, return the closest line that is a sequence point.  */
  232.     HRESULT FindClosestLine([in] ULONG32 line, 
  233.                             [out, retval] ULONG32* pRetVal);
  234.  
  235.     /*
  236.      * Returns true if the document has source embedded in the
  237.      * debugging symbols.
  238.      */
  239.     HRESULT HasEmbeddedSource([out, retval] BOOL *pRetVal);
  240.  
  241.     /*
  242.      * Returns the length, in bytes, of the embedded source.
  243.      */
  244.     HRESULT GetSourceLength([out, retval] ULONG32* pRetVal);
  245.  
  246.     /*
  247.      * Returns the embedded source into the given buffer. The buffer must
  248.      * be large enough to hold the source.
  249.      */
  250.     HRESULT GetSourceRange([in] ULONG32 startLine, 
  251.                            [in] ULONG32 startColumn, 
  252.                            [in] ULONG32 endLine, 
  253.                            [in] ULONG32 endColumn,
  254.                            [in] ULONG32 cSourceBytes,
  255.                            [out] ULONG32 *pcSourceBytes,
  256.                            [out, size_is(cSourceBytes),
  257.                            length_is(*pcSourceBytes)] BYTE source[]);
  258. };
  259.  
  260. /* ------------------------------------------------------------------------- *
  261.  * ISymUnmanagedDocumentWriter interface
  262.  * ------------------------------------------------------------------------- */
  263.  
  264. [
  265.  object,
  266.  uuid(B01FAFEB-C450-3A4D-BEEC-B4CEEC01E006),
  267.  pointer_default(unique)
  268. ]
  269. interface ISymUnmanagedDocumentWriter : IUnknown
  270. {
  271.     /*
  272.      * Sets embedded source for a document being written.
  273.      */
  274.     HRESULT SetSource([in] ULONG32 sourceSize,
  275.                       [in, size_is(sourceSize)] BYTE source[]);
  276.  
  277.     /*
  278.      * Sets check sum info.
  279.      */
  280.     HRESULT SetCheckSum([in] GUID algorithmId,
  281.                         [in] ULONG32 checkSumSize,
  282.                         [in, size_is(checkSumSize)] BYTE checkSum[]);
  283. };
  284.  
  285. /* ------------------------------------------------------------------------- *
  286.  * ISymUnmanagedMethod interface
  287.  * ------------------------------------------------------------------------- */
  288.  
  289. [
  290.  object,
  291.  uuid(B62B923C-B500-3158-A543-24F307A8B7E1),
  292.  pointer_default(unique)
  293. ]
  294. interface ISymUnmanagedMethod : IUnknown
  295. {
  296.     /*
  297.      * Return the metadata token for this method.
  298.      */
  299.     HRESULT GetToken([out, retval] mdMethodDef *pToken);
  300.  
  301.     /*
  302.      * Get the count of sequence points within this method.
  303.      */
  304.     HRESULT GetSequencePointCount([out, retval] ULONG32* pRetVal);
  305.  
  306.     /*
  307.      * Get the root lexical scope within this method.
  308.      */
  309.     HRESULT GetRootScope([out, retval] ISymUnmanagedScope** pRetVal);
  310.  
  311.     /*
  312.      * Get the most enclosing lexical scope within this method that
  313.      * encloses the given offset.
  314.      */
  315.     HRESULT GetScopeFromOffset([in] ULONG32 offset, 
  316.                                [out, retval] ISymUnmanagedScope** pRetVal);
  317.  
  318.     /*
  319.      * Given a position within a document, return the offset within
  320.      * this method that cooresponds to the position.
  321.      */
  322.     HRESULT GetOffset([in] ISymUnmanagedDocument* document, 
  323.                       [in] ULONG32 line, 
  324.                       [in] ULONG32 column, 
  325.                       [out, retval] ULONG32* pRetVal);
  326.  
  327.     /*
  328.      * Given a position in a document, return an array of start/end
  329.      * offset paris that correspond to the ranges of IL that the
  330.      * position covers within this method. The array is an array of
  331.      * integers and is [start,end,start,end]. The number of range
  332.      * pairs is the length of the array / 2.
  333.      */
  334.     HRESULT GetRanges([in] ISymUnmanagedDocument* document, 
  335.                       [in] ULONG32 line, 
  336.                       [in] ULONG32 column,
  337.                       [in] ULONG32 cRanges,
  338.                       [out] ULONG32 *pcRanges,
  339.                       [out, size_is(cRanges),
  340.                       length_is(*pcRanges)] ULONG32 ranges[]);
  341.  
  342.     /*
  343.      * Get the parameters for this method. The parameters are returned
  344.      * in the order they are defined within the method's signature.
  345.      */
  346.     HRESULT GetParameters([in] ULONG32 cParams,
  347.                           [out] ULONG32 *pcParams,
  348.                           [out, size_is(cParams),
  349.                           length_is(*pcParams)] ISymUnmanagedVariable* params[]);
  350.  
  351.     /*
  352.      * Get the namespace that this method is defined within.
  353.      */
  354.     HRESULT GetNamespace([out] ISymUnmanagedNamespace **pRetVal);
  355.  
  356.     /*
  357.      * Get the start/end document positions for the source of this
  358.      * method. The first array position is the start while the second
  359.      * is the end. Returns true if positions were defined, false
  360.      * otherwise.
  361.      */
  362.     HRESULT GetSourceStartEnd([in] ISymUnmanagedDocument *docs[2],
  363.                               [in] ULONG32 lines[2],
  364.                               [in] ULONG32 columns[2],
  365.                               [out] BOOL *pRetVal);
  366.  
  367.     /*
  368.      * Get all the sequence points within this method.
  369.      */
  370.     HRESULT GetSequencePoints([in] ULONG32 cPoints,
  371.                               [out] ULONG32 *pcPoints,
  372.                               [in, size_is(cPoints)] ULONG32 offsets[], 
  373.                               [in, size_is(cPoints)] ISymUnmanagedDocument* documents[], 
  374.                               [in, size_is(cPoints)] ULONG32 lines[], 
  375.                               [in, size_is(cPoints)] ULONG32 columns[],
  376.                               [in, size_is(cPoints)] ULONG32 endLines[], 
  377.                               [in, size_is(cPoints)] ULONG32 endColumns[]);
  378.  
  379. };
  380.  
  381. /* ------------------------------------------------------------------------- *
  382.  * ISymUnmanagedNamespace interface
  383.  * ------------------------------------------------------------------------- */
  384.  
  385. [
  386.  object,
  387.  uuid(0DFF7289-54F8-11d3-BD28-0000F80849BD),
  388.  pointer_default(unique)
  389. ]
  390. interface ISymUnmanagedNamespace : IUnknown
  391. {
  392.     /*
  393.      * Get the name of this namespace.
  394.      */
  395.     HRESULT GetName([in] ULONG32 cchName,
  396.                     [out] ULONG32 *pcchName,
  397.                     [out, size_is(cchName),
  398.                     length_is(*pcchName)] WCHAR szName[]);
  399.  
  400.     /*
  401.      * Get the children of this namespace.
  402.      */
  403.     HRESULT GetNamespaces([in] ULONG32 cNameSpaces,
  404.                           [out] ULONG32 *pcNameSpaces,
  405.                           [out, size_is(cNameSpaces),
  406.                           length_is(*pcNameSpaces)]
  407.                           ISymUnmanagedNamespace* namespaces[]);
  408.  
  409.     /*
  410.      * Return all variables defined at global scope within this namespace.
  411.      */
  412.     HRESULT GetVariables([in] ULONG32 cVars,
  413.                          [out] ULONG32 *pcVars,
  414.                          [out, size_is(cVars),
  415.                          length_is(*pcVars)] ISymUnmanagedVariable *pVars[]);
  416. };
  417.  
  418. /* ------------------------------------------------------------------------- *
  419.  * ISymUnmanagedReader interface
  420.  * ------------------------------------------------------------------------- */
  421.  
  422. [
  423.  object,
  424.  uuid(B4CE6286-2A6B-3712-A3B7-1EE1DAD467B5),
  425.  pointer_default(unique)
  426. ]
  427. interface ISymUnmanagedReader : IUnknown
  428. {
  429.     /*
  430.      * Find a document. Language, vendor, and document type are optional.
  431.      */
  432.     HRESULT GetDocument([in] WCHAR *url, 
  433.                         [in] GUID language, 
  434.                         [in] GUID languageVendor, 
  435.                         [in] GUID documentType, 
  436.                         [out, retval] ISymUnmanagedDocument** pRetVal);
  437.  
  438.     /*
  439.      * Return an array of all the documents defined in the symbol store.
  440.      */
  441.     HRESULT GetDocuments([in] ULONG32 cDocs,
  442.                          [out] ULONG32 *pcDocs,
  443.                          [out, size_is(cDocs),
  444.                          length_is(*pcDocs)] ISymUnmanagedDocument *pDocs[]);
  445.  
  446.     /*
  447.      * Return the method that was specified as the user entry point
  448.      * for the module, if any. This would be, perhaps, the user's main
  449.      * method rather than compiler generated stubs before main.
  450.      */
  451.     HRESULT GetUserEntryPoint([out, retval] mdMethodDef *pToken);
  452.  
  453.     /*
  454.      * Get a symbol reader method given a method token.
  455.      */
  456.     HRESULT GetMethod([in] mdMethodDef token, 
  457.                       [out, retval] ISymUnmanagedMethod** pRetVal);
  458.  
  459.     /*
  460.      * Get a symbol reader method given a method token and an E&C
  461.      * version number. Version numbers start at 1 and are incremented
  462.      * each time the method is changed due to an E&C operation.
  463.      */
  464.     HRESULT GetMethodByVersion([in] mdMethodDef token,
  465.                                [in] int version,
  466.                                [out, retval] ISymUnmanagedMethod** pRetVal);
  467.  
  468.     /*
  469.      * Return a non-local variable given its parent and name.
  470.      */
  471.     HRESULT GetVariables([in] mdToken parent, 
  472.                          [in] ULONG32 cVars,
  473.                          [out] ULONG32 *pcVars,
  474.                          [out, size_is(cVars),
  475.                          length_is(*pcVars)] ISymUnmanagedVariable *pVars[]);
  476.     /*
  477.      * Return all global variables.
  478.      */
  479.     HRESULT GetGlobalVariables([in] ULONG32 cVars,
  480.                                [out] ULONG32 *pcVars,
  481.                                [out, size_is(cVars),
  482.                                length_is(*pcVars)] ISymUnmanagedVariable *pVars[]);
  483.  
  484.     /*
  485.      * Given a position in a document, return the ISymUnmanagedMethod that
  486.      * contains that position.
  487.      */
  488.     HRESULT GetMethodFromDocumentPosition([in] ISymUnmanagedDocument* document, 
  489.                                           [in] ULONG32 line, 
  490.                                           [in] ULONG32 column, 
  491.                                           [out, retval] ISymUnmanagedMethod** pRetVal);
  492.  
  493.     /*
  494.      * Gets a custom attribute based upon its name. Not to be
  495.      * confused with Metadata custom attributes, these attributes are
  496.      * held in the symbol store.
  497.      */
  498.     HRESULT GetSymAttribute([in] mdToken parent, 
  499.                             [in] WCHAR *name,
  500.                             [in] ULONG32 cBuffer,
  501.                             [out] ULONG32 *pcBuffer,
  502.                             [out, size_is(cBuffer),
  503.                             length_is(*pcBuffer)] BYTE buffer[]);
  504.  
  505.     /*
  506.      * Get the namespaces defined at global scope within this symbol store.
  507.      */
  508.     HRESULT GetNamespaces([in] ULONG32 cNameSpaces,
  509.                           [out] ULONG32 *pcNameSpaces,
  510.                           [out, size_is(cNameSpaces),
  511.                           length_is(*pcNameSpaces)]
  512.                           ISymUnmanagedNamespace* namespaces[]);
  513.  
  514.     /*
  515.      * Initialize the symbol reader with the metadata importer interface
  516.      * that this reader will be associated with, along with the filename
  517.      * of the module. This can only be called once, and must be called
  518.      * before any other reader methods are called.
  519.      *
  520.      * Note: you need only specify one of the filename or the pIStream,
  521.      * not both. The searchPath parameter is optional.
  522.      */
  523.     HRESULT Initialize([in] IUnknown *importer,
  524.                        [in] const WCHAR *filename,
  525.                        [in] const WCHAR *searchPath,
  526.                        [in] IStream *pIStream);
  527.  
  528.     /*
  529.      * Update the existing symbol reader with a delta symbol store. This
  530.      * is used in EnC scenarios as a way to update the symbol store to
  531.      * match deltas to the original PE file.
  532.      *
  533.      * Only one of the filename or pIStream parameters need be specified.
  534.      * If a filename is specified, the symbol store will be updated with
  535.      * the symbols in that file. If a IStream is specified, the store will
  536.      * be updated with the data from the IStream.
  537.      */
  538.     HRESULT UpdateSymbolStore([in] const WCHAR *filename,
  539.                               [in] IStream *pIStream);
  540.  
  541.     /*
  542.      * Update the existing symbol reader with a delta symbol
  543.      * store. This is much like UpdateSymbolStore, but the given detla
  544.      * acts as a complete replacement rather than an update.
  545.      *
  546.      * Only one of the filename or pIStream parameters need be specified.
  547.      * If a filename is specified, the symbol store will be updated with
  548.      * the symbols in that file. If a IStream is specified, the store will
  549.      * be updated with the data from the IStream.
  550.      */
  551.     HRESULT ReplaceSymbolStore([in] const WCHAR *filename,
  552.                                [in] IStream *pIStream);
  553.  
  554.     HRESULT GetSymbolStoreFileName( [in] ULONG32 cchName,
  555.                                     [out] ULONG32 *pcchName,
  556.                        [out, size_is(cchName),
  557.                                     length_is(*pcchName)]  WCHAR szName[]);
  558.  
  559. };
  560.  
  561. /* ------------------------------------------------------------------------- *
  562.  * ISymUnmanagedScope interface
  563.  * ------------------------------------------------------------------------- */
  564.  
  565. [
  566.  object,
  567.  uuid(68005D0F-B8E0-3B01-84D5-A11A94154942),
  568.  pointer_default(unique)
  569. ]
  570. interface ISymUnmanagedScope : IUnknown
  571. {
  572.     /*
  573.      * Get the method that contains this scope.
  574.      */
  575.     HRESULT GetMethod([out, retval] ISymUnmanagedMethod** pRetVal);
  576.  
  577.     /*
  578.      * Get the parent scope of this scope.
  579.      */
  580.     HRESULT GetParent([out, retval] ISymUnmanagedScope** pRetVal);
  581.  
  582.     /*
  583.      * Get the children of this scope.
  584.      */
  585.     HRESULT GetChildren([in] ULONG32 cChildren,
  586.                         [out] ULONG32 *pcChildren,
  587.                         [out, size_is(cChildren),
  588.                         length_is(*pcChildren)] ISymUnmanagedScope* children[]);
  589.  
  590.     /*
  591.      * Get the start offset for this scope,
  592.      */
  593.     HRESULT GetStartOffset([out, retval] ULONG32* pRetVal);
  594.  
  595.     /*
  596.      * Get the end offset for this scope.
  597.      */
  598.     HRESULT GetEndOffset([out, retval] ULONG32* pRetVal);
  599.  
  600.     /*
  601.      * Get a count of the number of local variables defined within this
  602.      * scope.
  603.      */
  604.     HRESULT GetLocalCount([out, retval] ULONG32 *pRetVal);
  605.  
  606.     /*
  607.      * Get the local variables defined within this scope.
  608.      */
  609.     HRESULT GetLocals([in] ULONG32 cLocals,
  610.                       [out] ULONG32 *pcLocals,
  611.                       [out, size_is(cLocals),
  612.                       length_is(*pcLocals)] ISymUnmanagedVariable* locals[]);
  613.  
  614.     /*
  615.      * Get the namespaces that are being "used" within this scope.
  616.      */
  617.     HRESULT GetNamespaces([in] ULONG32 cNameSpaces,
  618.                           [out] ULONG32 *pcNameSpaces,
  619.                           [out, size_is(cNameSpaces),
  620.                           length_is(*pcNameSpaces)]
  621.                           ISymUnmanagedNamespace* namespaces[]);
  622. };
  623.  
  624. /* ------------------------------------------------------------------------- *
  625.  * ISymUnmanagedVariable interface
  626.  * ------------------------------------------------------------------------- */
  627.  
  628. [
  629.  object,
  630.  uuid(9F60EEBE-2D9A-3F7C-BF58-80BC991C60BB),
  631.  pointer_default(unique)
  632. ]
  633. interface ISymUnmanagedVariable : IUnknown
  634. {
  635.     /*
  636.      * Get the name of this variable.
  637.      */
  638.     HRESULT GetName([in] ULONG32 cchName,
  639.                     [out] ULONG32 *pcchName,
  640.                     [out, size_is(cchName),
  641.                     length_is(*pcchName)] WCHAR szName[]);
  642.  
  643.     /*
  644.      * Get the attribute flags for this variable.
  645.      */
  646.     HRESULT GetAttributes([out, retval] ULONG32* pRetVal);
  647.  
  648.     /*
  649.      * Get the signature of this variable.
  650.      */
  651.     HRESULT GetSignature([in] ULONG32 cSig,
  652.                          [out] ULONG32 *pcSig,
  653.                          [out, size_is(cSig),
  654.                          length_is(*pcSig)] BYTE sig[]);
  655.  
  656.     /*
  657.      * Get the kind of address of this variable
  658.      */
  659.     HRESULT GetAddressKind([out, retval] ULONG32* pRetVal);
  660.  
  661.     /*
  662.      * Get the first address field for this variable. Its meaning depends
  663.      * on the address kind.
  664.      */
  665.     HRESULT GetAddressField1([out, retval] ULONG32* pRetVal);
  666.  
  667.     /*
  668.      * Get the second address field for this variable. Its meaning depends
  669.      * on the address kind.
  670.      */
  671.     HRESULT GetAddressField2([out, retval] ULONG32* pRetVal);
  672.  
  673.     /*
  674.      * Get the third address field for this variable. Its meaning depends
  675.      * on the address kind.
  676.      */
  677.     HRESULT GetAddressField3([out, retval] ULONG32* pRetVal);
  678.  
  679.     /*
  680.      * Get the start offset of this variable within its parent. If this is
  681.      * a local variable within a scope, this fill fall within the offsets
  682.      * defined for the scope.
  683.      */
  684.     HRESULT GetStartOffset([out, retval] ULONG32* pRetVal);
  685.  
  686.     /*
  687.      * Get the end offset of this variable within its parent. If this is
  688.      * a local variable within a scope, this fill fall within the offsets
  689.      * defined for the scope.
  690.      */
  691.     HRESULT GetEndOffset([out, retval] ULONG32* pRetVal);
  692. };
  693.  
  694. /* ------------------------------------------------------------------------- *
  695.  * ISymUnmanagedWriter interface
  696.  * ------------------------------------------------------------------------- */
  697.  
  698. [
  699.  object,
  700.  uuid(2DE91396-3844-3B1D-8E91-41C24FD672EA),
  701.  pointer_default(unique)
  702. ]
  703. interface ISymUnmanagedWriter : IUnknown
  704. {
  705.     /*
  706.      * Define a source document. Guid's will be provided for languages,
  707.      * vendors, and document types that we currently know about.
  708.      */
  709.     HRESULT DefineDocument([in] const WCHAR *url, 
  710.                            [in] const GUID *language, 
  711.                            [in] const GUID *languageVendor, 
  712.                            [in] const GUID *documentType, 
  713.                            [out, retval] ISymUnmanagedDocumentWriter** pRetVal);
  714.  
  715.     /*
  716.      * Define the method that the user has defined as their entrypoint
  717.      * for this module. This would be, perhaps, the user's main method
  718.      * rather than compiler generated stubs before main.
  719.      */
  720.     HRESULT SetUserEntryPoint([in] mdMethodDef entryMethod);
  721.  
  722.     /*
  723.      * Open a method to emit symbol information into. The given method
  724.      * becomes the current method for calls do define sequence points,
  725.      * parameters and lexical scopes. There is an implicit lexical
  726.      * scope around the entire method. Re-opening a method that has
  727.      * been previously closed effectivley erases any previously
  728.      * defined symbols for that method.
  729.      *
  730.      * There can be only one open method at a time.
  731.      */
  732.     HRESULT OpenMethod([in] mdMethodDef method);
  733.  
  734.     /*
  735.      * Close the current method. Once a method is closed, no more
  736.      * symbols can be defined within it.
  737.      */
  738.     HRESULT CloseMethod();
  739.  
  740.     /*
  741.      * Open a new lexical scope in the current method. The scope
  742.      * becomes the new current scope and is effectivley pushed onto a
  743.      * stack of scopes. startOffset is the offset, in bytes from the
  744.      * beginning of the method, of the first instruction in the
  745.      * lexical scope. Scopes must form a hierarchy. Siblings are not
  746.      * allowed to overlap.
  747.      *
  748.      * OpenScope returns an opaque scope id that can be used with
  749.      * SetScopeRange to define a scope's start/end offset at a later
  750.      * time. In this case, the offsets passed to OpenScope and
  751.      * CloseScope are ignored.
  752.      *
  753.      * Note: scope id's are only valid in the current method.
  754.      */
  755.     HRESULT OpenScope([in] ULONG32 startOffset, 
  756.                       [out, retval] ULONG32* pRetVal);
  757.  
  758.     /*
  759.      * Close the current lexical scope. Once a scope is closed no more
  760.      * variables can be defined within it. endOffset points past the
  761.      * last instruction in the scope.
  762.      */
  763.     HRESULT CloseScope([in] ULONG32 endOffset);
  764.  
  765.     /*
  766.      * Define the offset range for a given lexical scope.
  767.      */
  768.     HRESULT SetScopeRange([in] ULONG32 scopeID, 
  769.                           [in] ULONG32 startOffset, 
  770.                           [in] ULONG32 endOffset);
  771.  
  772.     /*
  773.      * Define a single variable in the current lexical
  774.      * scope. startOffset and endOffset are optional. If 0, then they
  775.      * are ignored and the variable is defined over the entire
  776.      * scope. If non-zero, then they must fall within the offsets of
  777.      * the current scope. This can be called multiple times for a
  778.      * variable of the same name that has multiple homes throughout a
  779.      * scope. (Note: start/end offsets must not overlap in such a
  780.      * case.)
  781.      */
  782.     HRESULT DefineLocalVariable([in] const WCHAR *name, 
  783.                                 [in] ULONG32 attributes,
  784.                                 [in] ULONG32 cSig,
  785.                                 [in, size_is(cSig)] unsigned char signature[],
  786.                                 [in] ULONG32 addrKind, 
  787.                                 [in] ULONG32 addr1, 
  788.                                 [in] ULONG32 addr2, 
  789.                                 [in] ULONG32 addr3, 
  790.                                 [in] ULONG32 startOffset, 
  791.                                 [in] ULONG32 endOffset);
  792.  
  793.     /*
  794.      * Define a single parameter in the current method. The type of
  795.      * each parameter is taken from its position (sequence) within the
  796.      * method's signature.
  797.      *
  798.      * Note: if parameters are defined in the metadata for a given
  799.      * method, then clearly one would not have to define them again
  800.      * with calls to this method. The symbol readers will have to be
  801.      * smart enough to check the normal metadata for these first then
  802.      * fall back to the symbol store.
  803.      */
  804.     HRESULT DefineParameter([in] const WCHAR *name, 
  805.                             [in] ULONG32 attributes, 
  806.                             [in] ULONG32 sequence, 
  807.                             [in] ULONG32 addrKind, 
  808.                             [in] ULONG32 addr1, 
  809.                             [in] ULONG32 addr2,
  810.                             [in] ULONG32 addr3);
  811.  
  812.     /*
  813.      * Define a single variable not within a method. This is used for
  814.      * certian fields in classes, bitfields, etc.
  815.      */
  816.     HRESULT DefineField([in] mdTypeDef parent, 
  817.                         [in] const WCHAR *name, 
  818.                         [in] ULONG32 attributes,
  819.                         [in] ULONG32 cSig,
  820.                         [in, size_is(cSig)] unsigned char signature[], 
  821.                         [in] ULONG32 addrKind, 
  822.                         [in] ULONG32 addr1, 
  823.                         [in] ULONG32 addr2,
  824.                         [in] ULONG32 addr3);
  825.  
  826.     /*
  827.      * Define a single global variable.
  828.      */
  829.     HRESULT DefineGlobalVariable([in] const WCHAR *name, 
  830.                                  [in] ULONG32 attributes,
  831.                                  [in] ULONG32 cSig,
  832.                                  [in, size_is(cSig)] unsigned char signature[], 
  833.                                  [in] ULONG32 addrKind, 
  834.                                  [in] ULONG32 addr1, 
  835.                                  [in] ULONG32 addr2,
  836.                                  [in] ULONG32 addr3);
  837.  
  838.     /*
  839.      * Close will close the ISymUnmanagedWriter and commit the symbols
  840.      * to the symbol store. The ISymUnmanagedWriter becomes invalid
  841.      * after this call for further updates.
  842.      */
  843.     HRESULT Close();
  844.  
  845.     /*
  846.      * Defines a custom attribute based upon its name. Not to be
  847.      * confused with Metadata custom attributes, these attributes are
  848.      * held in the symbol store.
  849.      */
  850.     HRESULT SetSymAttribute([in] mdToken parent, 
  851.                             [in] const WCHAR *name,
  852.                             [in] ULONG32 cData,
  853.                             [in, size_is(cData)] unsigned char data[]);
  854.  
  855.     /*
  856.      * Opens a new namespace. Call this before defining methods or
  857.      * variables that live within a namespace. Namespaces can be nested.
  858.      */
  859.     HRESULT OpenNamespace([in] const WCHAR *name);
  860.  
  861.     /*
  862.      * Close the most recently opened namespace.
  863.      */
  864.     HRESULT CloseNamespace();
  865.  
  866.     /*
  867.      * Specifies that the given, fully qualified namespace name is
  868.      * being used within the currently open lexical scope. Closing the
  869.      * current scope will also stop using the namespace, and the
  870.      * namespace will be in use in all scopes that inherit from the
  871.      * currently open scope.
  872.      */
  873.     HRESULT UsingNamespace([in] const WCHAR *fullName);
  874.  
  875.     /*
  876.      * Specifies the true start and end of a method within a source
  877.      * file. Use this to specify the extent of a method independently
  878.      * of what sequence points exist within the method.
  879.      */
  880.     HRESULT SetMethodSourceRange([in] ISymUnmanagedDocumentWriter *startDoc,
  881.                                  [in] ULONG32 startLine,
  882.                                  [in] ULONG32 startColumn,
  883.                                  [in] ISymUnmanagedDocumentWriter *endDoc,
  884.                                  [in] ULONG32 endLine,
  885.                                  [in] ULONG32 endColumn);
  886.  
  887.     /*
  888.      * Sets the metadata emitter interface that this writer will be
  889.      * associated with. Also sets the output filename of where the
  890.      * debugging symbols will be written. This can only be called once,
  891.      * and must be called before any other writer methods are called.
  892.      *
  893.      * Some writers may require a filename, while others may not. A
  894.      * filename can always be passed to this method, however, with
  895.      * no ill effects on writers that do not use it.
  896.      *
  897.      * The pIStream parameter is optional. If specified, the symbol
  898.      * writer will emit the symbols into the given IStream rather than
  899.      * to the file specified in filename.
  900.      *
  901.      * The fFullBuild parameter indicates to the symbol writer whether
  902.      * this is a full build or an incremental build.
  903.      */
  904.     HRESULT Initialize([in] IUnknown *emitter,
  905.                        [in] const WCHAR *filename,
  906.                        [in] IStream *pIStream,
  907.                        [in] BOOL fFullBuild);
  908.  
  909.     /*
  910.      * Returns the necessary info for a compiler to write the
  911.      * necessary debug directory entry into the PE header.
  912.      *
  913.      * pIID should point to a IMAGE_DEBUG_DIRECTORY that the symbol
  914.      * writer will fill out. All fields except for TimeDateStamp and
  915.      * PointerToRawData will be filled out by the symbol writer. (The
  916.      * compiler is responsible for setting TimeDateStamp and
  917.      * PointerToRawData appropiatley.)
  918.      *
  919.      * data should point to a buffer large enough to hold the debug
  920.      * data for the symbol store.
  921.      *
  922.      * A compiler should call this method, then emit the data blob to
  923.      * the PE file and set the PointerToRawData field in the
  924.      * IMAGE_DEBUG_DIRECTORY to point to the emitted data. Then, the
  925.      * IMAGE_DEBUG_DIRECTORY should be written to the PE file. The
  926.      * compiler should also set the TimeDateStamp field to equal the
  927.      * TimeDateStamp of the PE file being generated.
  928.      */
  929.     HRESULT GetDebugInfo([in, out] IMAGE_DEBUG_DIRECTORY *pIDD,
  930.                          [in] DWORD cData,
  931.                          [out] DWORD *pcData,
  932.                          [out, size_is(cData),
  933.                          length_is(*pcData)] BYTE data[]);
  934.  
  935.     /*
  936.      * Define a group of sequence points within the current method.
  937.      * Each line/column defines the start of a statement within a
  938.      * method. Each end line/column defines the end of a statement
  939.      * with a method. (End line/column is optional.) The arrays should
  940.      * be sorted by offset. The offset is always the offset from the
  941.      * start of the method, in bytes.
  942.      */
  943.     HRESULT DefineSequencePoints([in] ISymUnmanagedDocumentWriter* document,
  944.                                  [in] ULONG32 spCount,
  945.                                  [in, size_is(spCount)] ULONG32 offsets[], 
  946.                                  [in, size_is(spCount)] ULONG32 lines[], 
  947.                                  [in, size_is(spCount)] ULONG32 columns[],
  948.                                  [in, size_is(spCount)] ULONG32 endLines[], 
  949.                                  [in, size_is(spCount)] ULONG32 endColumns[]);
  950.  
  951.     /*
  952.      * This method tells the symbol writer that a metadata token has
  953.      * been remapped as the metadata was emitted. If the symbol writer
  954.      * has stored the old token within the symbol store, it must
  955.      * either update the stored token to the new value, or persist the
  956.      * map for the corresponding symbol reader to remap during the
  957.      * read phase.
  958.      */
  959.     HRESULT RemapToken([in] mdToken oldToken,
  960.                        [in] mdToken newToken);
  961. };
  962.  
  963.