developer/VSSDK/VisualStudioIntegration/Common/IDL/encbuild.idl

   1 ////////////////////////////////////////////////////////////////////////////////
   2 // ENCbuild.IDL
   3 //
   4 // Interface definitions for Edit 'N Continue & Project system interactions
   5 ////////////////////////////////////////////////////////////////////////////////
   6
   7 #ifndef INTEROPLIB
   8 import "oleidl.idl";
   9 import "vsshell.idl";
  10 #endif
  11
  12 // see IVsENCRebuildableProjectCfg
  13 // specify the exact reason for calling IVsENCRebuildableProjectCfg::BelongToProject
  14 enum tagENC_REASON {
  15
  16         ENCReason_Precompile,
  17         ENCReason_Rebuild
  18 };
  19 typedef enum tagENC_REASON ENC_REASON;
  20
  21 #ifdef INTEROPLIB
  22 // When we are building the interop assemblies the values inside the cpp_quote statements are
  23 // lost, so we have to define them here as enum.
  24 enum ENC_RETURNCODES
  25 {
  26     S_ENC_NOT_SUPPORTED = 0x00040001,
  27     E_STATEMENT_DELETED = 0x80040001
  28 };
  29 #else
  30 // see IVsENCRebuildableProjectCfg::BelongToProject
  31 cpp_quote("#define S_ENC_NOT_SUPPORTED                 MAKE_HRESULT(0, FACILITY_ITF, 0x0001)")
  32
  33 // HRESULT returned by GetCurrentActiveStatementPosition
  34 cpp_quote("#define E_STATEMENT_DELETED                 MAKE_HRESULT(1, FACILITY_ITF, 0x0001)")
  35 #endif
  36
  37 //=======================================================================
  38 // Project interfaces.
  39 //=======================================================================
  40
  41 //
  42 // IVsENCRebuildableProjectCfg
  43 //
  44 [
  45         uuid(BF031840-AFB9-11d2-AE14-00A0C9110055)
  46 ]
  47
  48 interface IVsENCRebuildableProjectCfg : IUnknown
  49 {
  50         // This method call is synchronous
  51         // Return codes;
  52         //      S_FALSE: this project doesn't need rebuilding in this program
  53         //  S_OK: rebuild succeeded must set out_ppUpdate
  54         //  Any FAILED(hr): build errors
  55     HRESULT ENCRebuild
  56         (
  57                 [in] IUnknown* in_pProgram,     //IDebugProgram2* pProgram,
  58                 [out] IUnknown** out_ppSnapshot //IDebugENCSnapshot2* ppUpdate
  59         );
  60
  61         // This method will get called when:
  62         // 1) user selects "Cancel ApplyCodeChange" menu-item, or
  63         // 2) one of the Project/Build systems fails to rebuild during ENCMGR's ENC Reubild phase.
  64         //              [note: ENCMGR is implementing all-or-nothing semantics on ENC Rebuild]
  65         HRESULT CancelENC
  66         (
  67                 void
  68         );
  69
  70         HRESULT ENCRelink
  71         (
  72                 [in] IUnknown* pENCRelinkInfo   // IEnumDebugENCRelinkInfo *
  73         );
  74
  75         HRESULT StartDebugging(void);
  76
  77         HRESULT StopDebugging(void);
  78
  79         // semantics: BelongToProject
  80         // in_szFileName specifies the fully-qualified filename whose content is dirtied by user-edits
  81         // in_ENCReason specifies the reason why ENCMGR is calling.
  82         // in_fOnContinue, a hack for managed only ENC
  83         // [because managed ENC can't do ApplyCodeChange without a subsequent debugger step]
  84         // [the method always returns S_FALSE when !in_fOnContinue]
  85         //
  86         // further note: disable managed ENC in VS7.0
  87         // for managed ENC project/build system, it will return S_ENC_NOT_SUPPORTED when
  88         // 1) in_fOnContinue is true
  89         // 2) in_szFileName belongs to this project/build system.
  90         HRESULT BelongToProject
  91         (
  92                 [in] LPCOLESTR in_szFileName,
  93                 [in] ENC_REASON in_ENCReason,
  94                 [in] BOOL in_fOnContinue
  95         );
  96
  97         HRESULT SetENCProjectBuildOption
  98         (
  99                 [in] REFGUID in_guidOption,
 100                 [in] LPCOLESTR in_szOptionValue
 101         );
 102
 103     HRESULT ENCComplete
 104         (
 105                 [in] BOOL in_fENCSuccess
 106         );
 107 }
 108
 109 // {D13E943A-9EE0-457f-8766-7D8B6BC06565}
 110 // IVsENCRebuildableProjectCfg2
 111 //
 112 [
 113     object,
 114         uuid(D13E943A-9EE0-457f-8766-7D8B6BC06565),
 115         pointer_default(unique)
 116 ]
 117 interface IVsENCRebuildableProjectCfg2 : IUnknown
 118 {
 119         enum enum_ENC_BREAKSTATE_REASON
 120         {
 121                 ENC_BREAK_NORMAL,     // Normal break track active statements, provide exception spans, track rude edits
 122                 ENC_BREAK_EXCEPTION  // Stopped at Exception, an unwind is required before ENC is allowed.  All edits are rude.  No tracking required.
 123         };
 124         typedef DWORD ENC_BREAKSTATE_REASON;
 125
 126         enum enum_ASINFO
 127         {
 128                 ASINFO_NONE         = 0x00000000,
 129                 ASINFO_LEAF         = 0x00000001, // The Active Statement is in a leaf frame
 130                 ASINFO_MIDSTATEMENT = 0x00000002, // The Active Statement is partially executed
 131                 ASINFO_NONUSER      = 0x00000004, // The Active Statement IL is not in user code
 132         };
 133         typedef DWORD ASINFO;
 134
 135         enum enum_POSITION_TYPE
 136         {
 137                 TEXT_POSITION_ACTIVE_STATEMENT = 1,     // Filename and position mark the Active statement
 138                 TEXT_POSITION_NEARBY_STATEMENT  = 2,    // Filename and position mark the statement associated with
 139                                                                                                 // some line in the method.
 140                                                                                                 // This is currently the line associated with
 141                                                                                                 // offset 0, but may change.
 142                                                                                                 // (The intent is to provide the language service
 143                                                                                                 // a hint on where to find the method  in source.)
 144                                                                                                 // asInfo must have ASINFO_NONUSER set.
 145                 TEXT_POSITION_NONE = 3                          // Filename and position are not meaningful.
 146                                                                                                 // (e.g. a generated function with no source.)
 147                                                                                                 // asInfo must have ASINFO_NONUSER set.
 148         };
 149         typedef DWORD POSITION_TYPE;
 150
 151         typedef struct _ACTVSTMT
 152         {
 153                 UINT32 id;          // ID for Active Statement unique
 154                 UINT32 methodToken; // Token of the Active Method
 155                 TextSpan tsPosition;// TextSpan for the active statment
 156                 BSTR filename;  // Filename for the active statement (filename as in the pdb)
 157                 ASINFO asInfo; // Flags with extra info about the state
 158                 POSITION_TYPE posType; // Determines meaning of tsPosition and filename.  See enum_POSITION_TYPE
 159         } ENC_ACTIVE_STATEMENT;
 160
 161         typedef enum
 162         {
 163                 ENC_NOT_MODIFIED,         // No user edits have occured
 164                 ENC_NONCONTINUABLE_ERRORS,// Rude ENC edits are present
 165                 ENC_COMPILE_ERRORS,       // Compile errors are present
 166                 ENC_APPLY_READY,          // Edits exist, no errors exist
 167         } ENC_BUILD_STATE;
 168
 169         typedef struct _EXCEPTIONSPAN
 170         {
 171                 UINT32 id;              // ID for exception handler assigned by lang service/compiler
 172                 UINT32 methodToken;
 173                 TextSpan tsPosition;
 174         } ENC_EXCEPTION_SPAN;
 175
 176         // Event to notify the LangSvc that we have started debugging.
 177         HRESULT StartDebuggingPE(void);
 178
 179         //
 180         // Event to notify the LangSvc that we are stopped at a valid state
 181         // for ENC.  The LangSvc must track Active Statements, and be capable
 182         // of providing ExceptionSpans after recieving this event until the next
 183         // ExitBreakStateOnPE event when encBreakReason is ENC_BREAK_NORMAL.
 184         //
 185         //
 186         HRESULT EnterBreakStateOnPE(
 187                 [in] ENC_BREAKSTATE_REASON encBreakReason,
 188                 [in] ENC_ACTIVE_STATEMENT* pActiveStatements,
 189                 [in] UINT32 cActiveStatements);
 190
 191         // QI for IDebugUpdateInMemoryPE
 192         HRESULT BuildForEnc(
 193                 [in] IUnknown* pUpdatePE);
 194
 195         // Event to notify the LangSvc that the debugger has returned to run mode.
 196         HRESULT ExitBreakStateOnPE(void);
 197
 198         // Event to notify the LangSvc that the debugger has stopped debugging
 199         HRESULT StopDebuggingPE(void);
 200
 201         // The language service must synchronize all pending changes and provide
 202         // an accurate build state when this is called.
 203         HRESULT GetENCBuildState(
 204                 [out] ENC_BUILD_STATE* pENCBuildState);
 205
 206         // The language service is responsible to tracking ActiveStatements between
 207         // the EnterBreakStateOnPE event and the ExitBreakStateOnPE event.
 208         HRESULT GetCurrentActiveStatementPosition(
 209                 [in] UINT32 id,
 210                 [out] TextSpan* ptsNewPosition);
 211
 212         //
 213         // The MVID is used to determine if the project built matches the PE being debugged.
 214         //
 215         HRESULT GetPEidentity(
 216                 [out] GUID* pMVID,
 217                 [out] BSTR* pbstrPEName);
 218
 219         //
 220         // Provide the number of Exception spans surrounding Active Statements.
 221         //
 222         HRESULT GetExceptionSpanCount(
 223                 [out] UINT32* pcExceptionSpan);
 224
 225         //
 226         // Provide the exception spans surrounding Active Statements.
 227         //
 228         // Exception spans cover code that might run before a remap can be done, or
 229         // that might decide where a remap may occur.  When an Active Statement is
 230         // marked ASINFO_MIDSTATEMENT then any associated catch and finally clauses
 231         // must be marked as an Exception span.  If the Active statement is inside a finally
 232         // clause then the try block must also be included in the Exception span.  The reason
 233         // for this restriction is that a Leave instruction in the try block may define where
 234         // execution continues after the finally is completed.
 235         //
 236         // Code changes in ExceptionSpans are rude edits.
 237         //
 238         HRESULT GetExceptionSpans(
 239                 [in] UINT32 celt,
 240                 [out, size_is(celt), length_is(*pceltFetched)] ENC_EXCEPTION_SPAN* rgelt,
 241                 [in, out] ULONG* pceltFetched);
 242
 243         //
 244         // The Language service must track exception spans between the EnterBreakStateOnPE
 245         // event and the ExitBreakStateOnPE.
 246         //
 247         HRESULT GetCurrentExceptionSpanPosition(
 248                 [in] UINT32 id,
 249                 [out] TextSpan* ptsNewPosition);
 250
 251         //
 252         // Notification provided to the language service and compiler that the Apply Succeeded.
 253         // This provides an opportunity for the lang service to update state via func eval, and clean up
 254         // state.  The hrApplyResult is the HRESULT returned from IDebugENCModule::ApplyENCUpdate
 255         // see enc.idl.
 256         //
 257         HRESULT EncApplySucceeded(
 258                 [in] HRESULT hrApplyResult);
 259
 260         //
 261         // Provide the timestamp for the last non-enc build. The timestamp requied
 262         // here is the one placed in the PE header during build.  Do not use the filesystem timestamp.
 263         //
 264         // This is not used in the Whidbey implementation of ENC.
 265         HRESULT GetPEBuildTimeStamp(
 266                 [in,out] FILETIME* pTimeStamp);
 267 }
 268
 269 // {3909921B-BACD-11d2-BD66-00C04FA302E2}
 270 // DEFINE_GUID(IID_IEnumVsENCRebuildableProjectCfgs,
 271 // 0x3909921b, 0xbacd, 0x11d2, 0xbd, 0x66, 0x0, 0xc0, 0x4f, 0xa3, 0x2, 0xe2);
 272 [
 273         object,
 274         uuid(3909921B-BACD-11d2-BD66-00C04FA302E2),
 275         pointer_default(unique)
 276 ]
 277 interface IEnumVsENCRebuildableProjectCfgs : IUnknown
 278 {
 279         HRESULT Next
 280         (
 281                 [in] ULONG celt,
 282                 [out, size_is(celt), length_is(*pceltFetched)] IVsENCRebuildableProjectCfg** rgelt,
 283                 [in, out] ULONG* pceltFetched
 284         );
 285         HRESULT Skip
 286         (
 287                 [in] ULONG celt
 288         );
 289         HRESULT Reset
 290         (
 291                 void
 292         );
 293         HRESULT Clone
 294         (
 295                 [out] IEnumVsENCRebuildableProjectCfgs** ppEnum
 296         );
 297         HRESULT GetCount
 298         (
 299                 [out] ULONG* pcelt
 300         );
 301 }