// ==++==
//
//   Copyright (c) Microsoft Corporation.  All rights reserved.
//
// ==--==
/**************************************************************************************
 **                                                                                  **
 ** Corprof.idl - CLR Profiling interfaces.                                          **
 **                                                                                  **
 **************************************************************************************/

/* -------------------------------------------------------------------------- *
 * Imported types
 * -------------------------------------------------------------------------- */

#if !DEFINITIONS_FROM_NON_IMPORTABLE_PLACES

/* -------------------------------------------------------------------------- *
 * These are registry key & value names where profilers register themselves
 * Note that '\\\\' -- midl--> '\\' -- C++ compiler --> '\'
 * -------------------------------------------------------------------------- */
cpp_quote("#define PROFILER_REGKEY_ROOT            L\"software\\\\microsoft\\\\.NETFramework\\\\Profilers\"")
cpp_quote("#define PROFILER_REGVALUE_HELPSTRING    L\"HelpString\"")
cpp_quote("#define PROFILER_REGVALUE_PROFID        L\"ProfilerID\"")

cpp_quote("#define CorDB_CONTROL_Profiling         \"Cor_Enable_Profiling\"")
cpp_quote("#define CorDB_CONTROL_ProfilingL       L\"Cor_Enable_Profiling\"")

cpp_quote("#if 0")


import "unknwn.idl";

typedef LONG32  mdToken;
typedef mdToken mdModule;
typedef mdToken mdTypeDef;
typedef mdToken mdMethodDef;
typedef mdToken mdFieldDef;
typedef ULONG CorElementType;

// Forward declaration of enum in CorHdr.h
enum    CorElementType;

cpp_quote("#endif")

typedef const BYTE *LPCBYTE;
typedef BYTE *LPBYTE;

#endif

cpp_quote("#ifndef _COR_IL_MAP")
cpp_quote("#define _COR_IL_MAP")

#ifdef INTERNAL_DOCS
// Note that this structure is also defined in CorDebug.idl - PROPAGATE CHANGES
// BOTH WAYS, or this'll become a really insidious bug some day.
#endif
typedef struct _COR_IL_MAP
{
    ULONG32 oldOffset;        // Old IL offset relative to beginning of function
    ULONG32 newOffset;        // New IL offset relative to beginning of function
    BOOL    fAccurate; //put here for compatability with the Debugger structure.
} COR_IL_MAP;

cpp_quote("#endif //_COR_IL_MAP")

cpp_quote("#ifndef _COR_DEBUG_IL_TO_NATIVE_MAP_")
cpp_quote("#define _COR_DEBUG_IL_TO_NATIVE_MAP_")

/* ICorProfilerInfo:: GetILToNativeMapping returns an array of
 * COR_DEBUG_IL_TO_NATIVE_MAP structures.  In order to convey that certain
 * ranges of native instructions correspond to special regions of code (for
 * example, the prolog), an entry in the array may have it's ilOffset field set
 * to one of these values.
 */
typedef enum CorDebugIlToNativeMappingTypes
{
    NO_MAPPING = -1,
    PROLOG     = -2,
    EPILOG     = -3
} CorDebugIlToNativeMappingTypes;

typedef struct COR_DEBUG_IL_TO_NATIVE_MAP
{
    ULONG32 ilOffset;
    ULONG32 nativeStartOffset;
    ULONG32 nativeEndOffset;
} COR_DEBUG_IL_TO_NATIVE_MAP;

cpp_quote("#endif // _COR_DEBUG_IL_TO_NATIVE_MAP_")

cpp_quote("#ifndef _COR_FIELD_OFFSET_")
cpp_quote("#define _COR_FIELD_OFFSET_")

typedef struct _COR_FIELD_OFFSET
{
    mdFieldDef ridOfField;  // fieldDef token of the field
    ULONG      ulOffset;      // offset (from the ObjectID pointer) of the field
} COR_FIELD_OFFSET;

cpp_quote("#endif // _COR_FIELD_OFFSET_")


#ifndef DO_NO_IMPORTS
import "wtypes.idl";
import "unknwn.idl";
#endif

typedef UINT_PTR ProcessID;
typedef UINT_PTR AssemblyID;
typedef UINT_PTR AppDomainID;
typedef UINT_PTR ModuleID;
typedef UINT_PTR ClassID;
typedef UINT_PTR ThreadID;
typedef UINT_PTR ContextID;
typedef UINT_PTR FunctionID;
typedef UINT_PTR ObjectID;
typedef UINT_PTR GCHandleID;

/*
 * The FunctionIDMapper type definition is used by the
 * ICorProfilerInfo::SetFunctionIDMapper method to specify
 * a function that will be called to map FunctionIDs to alternative
 * values that will be passed to the function entry and function exit
 * callbacks supplied to the ICorProfilerInfo::SetEnterLeaveFunctionHooks
 * method. The mapper can be set only once and it is recommended to do so
 * in the Initialize callback.
 *
 * NOTE: There is a known bug in this API that must be worked around.
 * The return value of FunctionIDMapper cannot be NULL (unless the boolean
 * value in pbHookTheFunction is FALSE).  All other values are treated as
 * opaque data to be passed to the entry/exit callback functions.  The use
 * of a NULL return value will produce unpredictable results, including
 * possibly halting the process.
 *
 * NOTE: Profilers should be tolerant of cases where multiple threads of
 * a profiled app are calling the same method simultaneously.  In such
 * cases, the profiler may receive multiple FunctionIDMapper callbacks
 * for the same functionId.  The profiler should be certain to return
 * the same values from this callback when it is called multiple times
 * with the same functionId.
 * 
 */
typedef UINT_PTR __stdcall FunctionIDMapper(
                FunctionID funcId, 
                BOOL *pbHookFunction);

/*
 * Enum for specifying how much data to pass back with a stack snapshot
 */
typedef enum _COR_PRF_SNAPSHOT_INFO
{
    COR_PRF_SNAPSHOT_DEFAULT = 0x0,
    COR_PRF_SNAPSHOT_REGISTER_CONTEXT = 0x1      // Return a register context for each frame
} COR_PRF_SNAPSHOT_INFO;

/*
 * Opaque handle that represents information about a given stack frame. It is only
 * valid during the callback to which it is passed.
 */
typedef UINT_PTR COR_PRF_FRAME_INFO;

/*
 * Describes a range of function arguments stored contiguously in left-to-right
 * order in memory.
 */
typedef struct _COR_PRF_FUNCTION_ARGUMENT_RANGE
{
    UINT_PTR startAddress;          // start address of the range
    ULONG length;                         // contiguous length of the range
} COR_PRF_FUNCTION_ARGUMENT_RANGE;

/*
 * Describes the locations in memory of a function's arguments, in
 * left-to-right order. Note that arguments stored in registers are
 * spilled to memory to build these structures.
 */
typedef struct _COR_PRF_FUNCTION_ARGUMENT_INFO
{
    ULONG numRanges;                // number of chunks of arguments
    ULONG totalArgumentSize;    // total size of arguments
    COR_PRF_FUNCTION_ARGUMENT_RANGE ranges[1];  // chunks
} COR_PRF_FUNCTION_ARGUMENT_INFO;

/*
 * Represents one contiguous chunk of native code
 */
typedef struct _COR_PRF_CODE_INFO
{
    UINT_PTR startAddress;
    SIZE_T size;
} COR_PRF_CODE_INFO;

/*
 * Enum for describing the type of static a field is.  These may be bit-wise
 * or'ed with each other if the field is multiple types.
 */
typedef enum
{
    COR_PRF_FIELD_NOT_A_STATIC = 0x0,
    COR_PRF_FIELD_APP_DOMAIN_STATIC = 0x1,
    COR_PRF_FIELD_THREAD_STATIC = 0x2,
    COR_PRF_FIELD_CONTEXT_STATIC = 0x4,
    COR_PRF_FIELD_RVA_STATIC = 0x8
} COR_PRF_STATIC_TYPE;



/*
 *
 * NOTE: DEPRECATED IN V2
 *
 * These functions are considered deprecated in V2 and higher.  They will
 * continue to work, but incur a performance penalty for usage.  For equivalent
 * functionality, use the FunctionEnter2/Leave2/Tailcall2 callbacks with
 * bits cleared for COR_PRF_ENABLE_FRAME_INFO, COR_PRF_ENABLE_FUNCTION_RETVAL
 * and COR_PRF_ENABLE_FUNCTION_ARGS.
 *
 * NOTE!!!
 *
 * It is VERY IMPORTANT to note that these function implementations must be
 * __declspec(naked), since the EE is not saving any registers before calling
 * any of them.  YOU MUST SAVE ALL REGISTERS YOU USE, INCLUDING FPU REGISTERS
 * IF THE FPU STACK IS NOT EMPTY AND YOU INTEND TO USE IT.
 *
 * NOTE: The profiler should not block here, since the stack may not be in a
 *       GC-friendly state and so preemptive GC cannot be enabled.  If the
 *       profiler blocks here and a GC is attempted, the runtime will block
 *       until this callback returns.  Also, the profiler may NOT call into
 *       managed code or in any way cause a managed memory allocation.
 */
typedef void FunctionEnter(
                FunctionID funcID);
                
typedef void FunctionLeave(
                FunctionID funcID);
                
typedef void FunctionTailcall(
                FunctionID funcID);

/*
 * NOTE!!!
 *
 * It is VERY IMPORTANT to note that these function implementations must be
 * __declspec(naked), since the EE is not saving any registers before calling
 * any of them.  YOU MUST SAVE ALL REGISTERS YOU USE, INCLUDING FPU REGISTERS
 * IF THE FPU STACK IS NOT EMPTY AND YOU INTEND TO USE IT.
 *
 * NOTE: The profiler should not block here, since the stack may not be in a
 *       GC-friendly state and so preemptive GC cannot be enabled.  If the
 *       profiler blocks here and a GC is attempted, the runtime will block
 *       until this callback returns.  Also, the profiler may NOT call into
 *       managed code or in any way cause a managed memory allocation.
 *
 * funcId is the true FunctionID of the function
 *
 * clientData is the remapped value returned by FunctionIDMapper
 *
 * The COR_PRF_FRAME_INFOs passed to these callbacks are only good during the
 * callback.
 *
 * The argument or retval information passed to these callbacks is only good during the
 * callback itself; arguments or return values may move or be destroyed after the
 * callback. To get argument information, the profiler must specify
 * COR_PRF_ENABLE_FUNCTION_ARGS, and to get return value information it must
 * specify COR_PRF_ENABLE_FUNCTION_RETVAL.
 */
typedef void FunctionEnter2(
                FunctionID funcId, 
                UINT_PTR clientData, 
                COR_PRF_FRAME_INFO func, 
                COR_PRF_FUNCTION_ARGUMENT_INFO *argumentInfo);
                
typedef void FunctionLeave2(
                FunctionID funcId, 
                UINT_PTR clientData, 
                COR_PRF_FRAME_INFO func, 
                COR_PRF_FUNCTION_ARGUMENT_RANGE *retvalRange);
                
typedef void FunctionTailcall2(
                FunctionID funcId, 
                UINT_PTR clientData, 
                COR_PRF_FRAME_INFO func);

/*
 * Stack snapshot callback definition.
 *
 * This callback is called once per managed frame or run of unmanaged frames.
 *
 * funcID is the FunctionID of the managed function. If funcID == 0, the callback is
 * for a run of unmanaged frames. The profiler may either ignore the frame, or use
 * the register context to perform its own unmanaged stackwalk.
 *
 * ip is the native IP in the frame
 *
 * frameInfo is the COR_PRF_FRAME_INFO for this frame. It is only valid for
 * use during this callback.
 *
 * context is a Win32 CONTEXT struct for the current platform (size given in
 * contextSize). It will only be valid if the COR_PRF_SNAPSHOT_CONTEXT flag
 * was passed to DoStackSnapshot.
 *
 * clientData is a void* passed straight through from DoStackSnapshot
 *
 * NOTE: One must limit the complexity of work done in StackSnapshotCallback. 
 * For example, particularly when using DoStackSnapshot in an asynchronous manner, 
 * the target thread may be holding locks. Executing code within StackSnapshotCallback 
 * that requires the same locks could lead to deadlock.
 */
typedef HRESULT __stdcall StackSnapshotCallback(
                FunctionID funcId,
                UINT_PTR ip,
                COR_PRF_FRAME_INFO frameInfo,
                ULONG32 contextSize,
                BYTE context[],
                void *clientData);

typedef enum
{
    // These flags represent classes of callback events
    COR_PRF_MONITOR_NONE                = 0x00000000,

    // MONITOR_FUNCTION_UNLOADS controls the
    // FunctionUnloadStarted callback.
    COR_PRF_MONITOR_FUNCTION_UNLOADS    = 0x00000001,

    // MONITOR_CLASS_LOADS controls the ClassLoad*
    // and ClassUnload* callbacks.
    // See the comments on those callbacks for important
    // behavior changes in V2.
    COR_PRF_MONITOR_CLASS_LOADS         = 0x00000002,

    // MONITOR_MODULE_LOADS controls the 
    // ModuleLoad*, ModuleUnload*, and ModuleAttachedToAssembly
    // callbacks.
    COR_PRF_MONITOR_MODULE_LOADS        = 0x00000004,

    // MONITOR_ASSEMBLY_LOADS controls the
    // AssemblyLoad* and AssemblyUnload* callbacks
    COR_PRF_MONITOR_ASSEMBLY_LOADS      = 0x00000008,

    // MONITOR_APPDOMAIN_LOADS controls the
    // AppDomainCreation* and AppDomainShutdown* callbacks
    COR_PRF_MONITOR_APPDOMAIN_LOADS     = 0x00000010,

    // MONITOR_JIT_COMPILATION controls the
    // JITCompilation*, JITFunctionPitched, and JITInlining 
    // callbacks.
    COR_PRF_MONITOR_JIT_COMPILATION     = 0x00000020,


    // MONITOR_EXCEPTIONS controls the ExceptionThrown,
    // ExceptionSearch*, ExceptionOSHandler*, ExceptionUnwind*,
    // and ExceptionCatcher* callbacks.
    COR_PRF_MONITOR_EXCEPTIONS          = 0x00000040,

    // MONITOR_GC controls the GarbageCollectionStarted/Finished,
    // MovedReferences, SurvivingReferences,
    // ObjectReferences, ObjectsAllocatedByClass,
    // RootReferences*, HandleCreated/Destroyed, and FinalizeableObjectQueued
    // callbacks.
    COR_PRF_MONITOR_GC                  = 0x00000080,

    // MONITOR_OBJECT_ALLOCATED controls the
    // ObjectAllocated callback.
    COR_PRF_MONITOR_OBJECT_ALLOCATED    = 0x00000100,

    // MONITOR_THREADS controls the ThreadCreated,
    // ThreadDestroyed, ThreadAssignedToOSThread, 
    // and ThreadNameChanged callbacks.
    COR_PRF_MONITOR_THREADS             = 0x00000200,

    // MONITOR_REMOTING controls the Remoting*
    // callbacks.
    COR_PRF_MONITOR_REMOTING            = 0x00000400,

    // MONITOR_CODE_TRANSITIONS controls the
    // UnmanagedToManagedTransition and 
    // ManagedToUnmanagedTransition callbacks.
    COR_PRF_MONITOR_CODE_TRANSITIONS    = 0x00000800,

    // MONITOR_ENTERLEAVE controls the 
    // FunctionEnter*/Leave*/Tailcall* callbacks
    COR_PRF_MONITOR_ENTERLEAVE          = 0x00001000,

    // MONITOR_CCW controls the COMClassicVTable*
    // callbacks.
    COR_PRF_MONITOR_CCW                 = 0x00002000,

    // MONITOR_REMOTING_COOKIE controls whether
    // a cookie will be passed to the Remoting* callbacks
    COR_PRF_MONITOR_REMOTING_COOKIE     = 0x00004000 | COR_PRF_MONITOR_REMOTING,

    // MONITOR_REMOTING_ASYNC controls whether
    // the Remoting* callbacks will monitor async events
    COR_PRF_MONITOR_REMOTING_ASYNC      = 0x00008000 | COR_PRF_MONITOR_REMOTING,

    // MONITOR_SUSPENDS controls the RuntimeSuspend*,
    // RuntimeResume*, RuntimeThreadSuspended, and 
    // RuntimeThreadResumed callbacks.
    COR_PRF_MONITOR_SUSPENDS            = 0x00010000,

    // MONITOR_CACHE_SEARCHES controls the
    // JITCachedFunctionSearch* callbacks.
    // See the comments on those callbacks for important
    // behavior changes in V2.
    COR_PRF_MONITOR_CACHE_SEARCHES      = 0x00020000,

    // MONITOR_CLR_EXCEPTIONS controls the ExceptionCLRCatcher*
    // callbacks.
    COR_PRF_MONITOR_CLR_EXCEPTIONS      = 0x01000000,

    // All callback events are enabled with this flag
    COR_PRF_MONITOR_ALL                 = 0x0107FFFF,

    // V2 MIGRATION WARNING: DEPRECATED
    // ReJIT is not supported. ENABLE_REJIT has no effect.
    COR_PRF_ENABLE_REJIT                 = 0x00040000,

    // V2 MIGRATION WARNING: DEPRECATED
    // Inproc debugging is no longer supported. ENABLE_INPROC_DEBUGGING
    // has no effect.
    COR_PRF_ENABLE_INPROC_DEBUGGING     = 0x00080000,

    // V2 MIGRATION NOTE: DEPRECATED
    // The runtime now always tracks IL-native maps; this flag is thus always
    // considered to be set.
    COR_PRF_ENABLE_JIT_MAPS             = 0x00100000,

    // DISABLE_INLINING tells the runtime to disable all inlining
    COR_PRF_DISABLE_INLINING            = 0x00200000,

    // DISABLE_OPTIMIZATIONS tells the runtime to disable all code optimizations
    COR_PRF_DISABLE_OPTIMIZATIONS       = 0x00400000,

    // ENABLE_OBJECT_ALLOCATED tells the runtime that the profiler may want
    // object allocation notifications.  This must be set during initialization if the profiler
    // ever wants object notifications (using COR_PRF_MONITOR_OBJECT_ALLOCATED)
    COR_PRF_ENABLE_OBJECT_ALLOCATED     = 0x00800000,

    // ENABLE_FUNCTION_ARGS enables argument tracing through FunctionEnter2.
    COR_PRF_ENABLE_FUNCTION_ARGS        = 0X02000000,

    // ENABLE_FUNCTION_RETVAL enables retval tracing through FunctionLeave2.
    COR_PRF_ENABLE_FUNCTION_RETVAL      = 0X04000000,

    // ENABLE_FRAME_INFO enables retrieval of exact ClassIDs for generic functions using
    // GetFunctionInfo2 with a COR_PRF_FRAME_INFO obtained from FunctionEnter2.
    COR_PRF_ENABLE_FRAME_INFO           = 0X08000000,

    // ENABLE_STACK_SNAPSHOT enables the used of DoStackSnapshot calls.
    COR_PRF_ENABLE_STACK_SNAPSHOT       = 0X10000000,

    // USE_PROFILE_IMAGES causes the native image search to look for profiler-enhanced
    // images.  If no profiler-enhanced image is found for a given assembly the
    // runtime will fallback to JIT for that assembly.
    COR_PRF_USE_PROFILE_IMAGES          = 0x20000000,

    // The mask for valid mask bits
    COR_PRF_ALL                         = 0x3FFFFFFF,

    // MONITOR_IMMUTABLE represents all flags that may only be set during initialization.
    // Trying to change any of these flags elsewhere will result in a
    // failed HRESULT.
    COR_PRF_MONITOR_IMMUTABLE           = COR_PRF_MONITOR_CODE_TRANSITIONS |
                                          COR_PRF_MONITOR_REMOTING |
                                          COR_PRF_MONITOR_REMOTING_COOKIE |
                                          COR_PRF_MONITOR_REMOTING_ASYNC |
                                          COR_PRF_MONITOR_GC |
                                          COR_PRF_ENABLE_REJIT |
                                          COR_PRF_ENABLE_INPROC_DEBUGGING |
                                          COR_PRF_ENABLE_JIT_MAPS |
                                          COR_PRF_DISABLE_OPTIMIZATIONS |
                                          COR_PRF_DISABLE_INLINING |
                                          COR_PRF_ENABLE_OBJECT_ALLOCATED |
                                          COR_PRF_ENABLE_FUNCTION_ARGS |
                                          COR_PRF_ENABLE_FUNCTION_RETVAL |
                                          COR_PRF_ENABLE_FRAME_INFO |
                                          COR_PRF_ENABLE_STACK_SNAPSHOT |
                                          COR_PRF_USE_PROFILE_IMAGES
} COR_PRF_MONITOR;

/*
 * COR_PRF_MISC contains miscellaneous constant ID's used for special
 * purposes.
 */
typedef enum
{
    // PROFILER_PARENT_UNKNOWN is the AssemblyID used by GetModuleInfo
    // when a module has not yet been attached to an assembly.
    PROFILER_PARENT_UNKNOWN             = 0xFFFFFFFD,

    // PROFILER_GLOBAL_CLASS is a ClassID used for globals that belong to no class
    PROFILER_GLOBAL_CLASS               = 0xFFFFFFFE,

    // PROFILER_GLOBAL_MODULE is a ModuleID used for globals that belong
    // to no module in particular
    PROFILER_GLOBAL_MODULE              = 0xFFFFFFFF
} COR_PRF_MISC;

/*
 * COR_PRF_JIT_CACHE contains values used to express the result of a
 * cached function search. Note that FOUND is 0, and thus this is not truly
 * a boolean.
 */
typedef enum
{
    COR_PRF_CACHED_FUNCTION_FOUND,
    COR_PRF_CACHED_FUNCTION_NOT_FOUND
} COR_PRF_JIT_CACHE;

/*
 * COR_PRF_TRANSITION_REASON contains values used to describe
 * the reason for a ManagedToUnmanaged or UnmanagedToManagedTransition
 * callback.
 */
typedef enum
{
    COR_PRF_TRANSITION_CALL,
    COR_PRF_TRANSITION_RETURN
} COR_PRF_TRANSITION_REASON;

/*
 * COR_PRF_SUSPEND_REASON contains values used to describe the
 * reason for suspending the runtime. See the RuntimeSuspension*
 * callbacks for detailed descriptions of each.
 */
typedef enum
{
    COR_PRF_SUSPEND_OTHER                   = 0,
    COR_PRF_SUSPEND_FOR_GC                  = 1,
    COR_PRF_SUSPEND_FOR_APPDOMAIN_SHUTDOWN  = 2,
    COR_PRF_SUSPEND_FOR_CODE_PITCHING       = 3,
    COR_PRF_SUSPEND_FOR_SHUTDOWN            = 4,
    COR_PRF_SUSPEND_FOR_INPROC_DEBUGGER     = 6,
    COR_PRF_SUSPEND_FOR_GC_PREP             = 7
} COR_PRF_SUSPEND_REASON;

/* -------------------------------------------------------------------------- *
 * Forward declarations
 * -------------------------------------------------------------------------- */

interface ICorProfilerCallback;
interface ICorProfilerCallback2;
interface ICorProfilerInfo;
interface ICorProfilerInfo2;
interface ICorProfilerObjectEnum;
interface IMethodMalloc;

/* -------------------------------------------------------------------------- *
 * User Callback interface
 * -------------------------------------------------------------------------- */

/*
 * The ICorProfilerCallback interface is used by the CLR to notify a
 * code profiler when events have occurred that the code profiler has registered
 * an in interest in receiving. This is the primary callback interface through
 * which the CLR communicates with the code profiler. A code profiler
 * must register this callback interface in the Win32 registry. This object has
 * several methods that receive notification from the runtime when an event is
 * about to occur in an executing runtime process.
 *
 * The methods implemented on this interface return S_OK on success, or E_FAIL
 * on failure.
 */

[
    object,
    uuid(176FBED1-A55C-4796-98CA-A9DA0EF883E7),
    pointer_default(unique),
    local
]
interface ICorProfilerCallback : IUnknown
{

    /*
     *
     * STARTUP/SHUTDOWN EVENTS
     *
     */

    /*
     * The CLR calls Initialize to setup the code profiler
     * whenever a new CLR application is started. The call provides
     * an IUnknown interface pointer that should be QI'd for an ICorProfilerInfo
     * interface pointer.
     *
     * NOTE: this is the only opportunity to enable callbacks that are a part
     * of COR_PRF_MONITOR_IMMUTABLE, since they can no longer be changed after
     * returning from this function.  This is done through SetEventMask on the
     * ICorProfilerInfo object.
     */
    HRESULT Initialize(
                [in] IUnknown     *pICorProfilerInfoUnk);

    /*
     * The CLR calls Shutdown to notify the code profiler that
     * the application is exiting.  This is the profiler's last opportunity to
     * safely call functions on the ICorProfilerInfo interface.  After returning
     * from this function the runtime will proceed to unravel its internal data
     * structures and any calls to ICorProfilerInfo are undefined in their
     * behaviour.
     *
     * NOTE: Certain IMMUTABLE events may still occur after Shutdown.
     *
     * NOTE: Shutdown will only fire where the managed application that is being
     * profiled was started running managed code (i.e., the initial frame on the
     * process’ stack is managed).  If the application being profiled started
     * life as unmanaged code, which later ‘jumped into’ managed code (thereby
     * creating an instance of the CLR), then Shutdown will not fire.  In these
     * cases, the profiler should include a DllMain routine in their library that
     * uses Win32’s DLL_PROCESS_DETACH call to free any resources and perform tidy-up
     * processing of its data (flush traces to disk, etc)
     *
     * NOTE: The profiler must in general cope with unexpected shutdowns, such as
     * when the process is "killed" by Win32's TerminateProcess.
     *
     * NOTE: Sometimes the CLR will violently kill certain managed threads
     * (background threads) without delivering orderly destruction messages for them.
     */
    HRESULT Shutdown();


    /*
     *
     * APPLICATION DOMAIN EVENTS
     *
     */

    /*
     * Called when an application domain creation has begun and ended.
     * The ID is not valid for any information request until the Finished
     * event is called.
     *
     * Some parts of app domain loading may take place lazily at some time
     * after the Finished callback. Therefore, while a failure HRESULT in
     * hrStatus definitely indicates a failure, a success HRESULT only indicates
     * that the first part of app domain creation succeeded.
     */
    HRESULT AppDomainCreationStarted(
                [in] AppDomainID appDomainId);

    HRESULT AppDomainCreationFinished(
                [in] AppDomainID appDomainId,
                [in] HRESULT     hrStatus);

    /*
     * Called before and after an app domain is unloaded from a process.
     * The ID is no longer valid after the Started event returns.
     *
     * Some parts of app domain unloading may take place lazily at some time
     * after the Finished callback. Therefore, while a failure HRESULT in
     * hrStatus definitely indicates a failure, a success HRESULT only indicates
     * that the first part of app domain unloading succeeded.
     */
    HRESULT AppDomainShutdownStarted(
                [in] AppDomainID appDomainId);

    HRESULT AppDomainShutdownFinished(
                [in] AppDomainID appDomainId,
                [in] HRESULT     hrStatus);

    /*
     *
     * ASSEMBLY EVENTS
     *
     */

    /*
     * Called when an Assembly load has begun and ended. The ID is not valid
     * for any information request until the Finished event is called.
     *
     * Some parts of assembly loading may take place lazily at some time
     * after the Finished callback. Therefore, while a failure HRESULT in
     * hrStatus definitely indicates a failure, a success HRESULT only indicates
     * that the first part of assembly loading succeeded.
     */
    HRESULT AssemblyLoadStarted(
                [in] AssemblyID assemblyId);

    HRESULT AssemblyLoadFinished(
                [in] AssemblyID assemblyId,
                [in] HRESULT    hrStatus);

    /*
     * Called before and after an assembly is unloaded.
     * The ID is no longer valid after the Started event returns.
     *
     * Some parts of assembly unloading may take place lazily at some time
     * after the Finished callback. Therefore, while a failure HRESULT in
     * hrStatus definitely indicates a failure, a success HRESULT only indicates
     * that the first part of assembly unloading succeeded.
     */
    HRESULT AssemblyUnloadStarted(
                [in] AssemblyID assemblyId);

    HRESULT AssemblyUnloadFinished(
                [in] AssemblyID assemblyId,
                [in] HRESULT    hrStatus);


    /*
     *
     * MODULE EVENTS
     *
     */

    /*
     * Called when a module load has begun and ended. The ID is not valid
     * for any information request until the Finished event is called.
     *
     * Some parts of module loading may take place lazily at some time
     * after the Finished callback. Therefore, while a failure HRESULT in
     * hrStatus definitely indicates a failure, a success HRESULT only indicates
     * that the first part of module loading succeeded.
     *
     * Note that when a module load is reported as finished this indicates
     * that the load has completed but it has not yet returned to the caller.
     * This is the opportunity for the profiler to note that other notifications regarding
     * this module may start coming afterwards however internal safeguards
     * protecting the runtime from recursive loading are still present and so it is
     * a bad time to begin inquiries on this module.  The notification is informational
     * only.  
     *
     * Note: ModuleLoadFinished is a reasonable time to interrogate MetaData via API's 
     * like GetModuleMetadata, however APIs that create (e.g. ClassID's and FunctionID's)
     * are not safe to use here.  Profiler writers are advised to stay in the universe of
     * tokens.
     *
     */
    HRESULT ModuleLoadStarted(
                [in] ModuleID moduleId);

    HRESULT ModuleLoadFinished(
                [in] ModuleID moduleId,
                [in] HRESULT  hrStatus);

    /*
     * Called before and after a module is unloaded.
     * The ID is no longer valid after the Started event returns.
     *
     * Some parts of module unloading may take place lazily at some time
     * after the Finished callback. Therefore, while a failure HRESULT in
     * hrStatus definitely indicates a failure, a success HRESULT only indicates
     * that the first part of module unloading succeeded.
     */
    HRESULT ModuleUnloadStarted(
                [in] ModuleID moduleId);

    HRESULT ModuleUnloadFinished(
                [in] ModuleID moduleId,
                [in] HRESULT  hrStatus);

    /*
     * A module can get loaded through legacy means (ie: IAT or LoadLibrary) or
     * through a metadata reference.  The CLR loader therefore has many code
     * paths for determining what assembly a module lives in.  It is therefore
     * possible that after a ModuleLoadFinished event, the module does not
     * know what assembly it is in and getting the parent AssemblyID is not possible.
     * This event is fired when the module is officially attached to its parent
     * assembly.  Calling GetModuleInfo after this function is called will return the
     * proper parent assembly.
     */
    HRESULT ModuleAttachedToAssembly(
                [in] ModuleID   moduleId,
                [in] AssemblyID AssemblyId);


    /*
     *
     *  CLASS EVENTS
     *
     */

    /*
     * Called when a class load has begun and ended. The ID is not valid
     * for any information request until the Finished event is called.
     *
     * Some parts of class loading may take place lazily at some time
     * after the Finished callback. Therefore, while a failure HRESULT in
     * hrStatus definitely indicates a failure, a success HRESULT only indicates
     * that the first part of class loading succeeded.
     *
     * Note that when a class load is reported as finished this indicates
     * that the load has completed but it has not yet returned to the caller.
     * This is the opportunity for the profiler to note that other notifications regarding
     * this class may start coming afterwards however internal safeguards
     * protecting the runtime from recursive loading are still present and so it is
     * a bad time to begin inquiries on this class.  The notification is informational
     * only.  
     *
     */
    HRESULT ClassLoadStarted(
                [in] ClassID classId);

    HRESULT ClassLoadFinished(
                [in] ClassID classId,
                [in] HRESULT hrStatus);

    /*
     * Called before and after a class is unloaded.
     * The ID is no longer valid after the Started event returns.
     *
     * Some parts of class unloading may take place lazily at some time
     * after the Finished callback. Therefore, while a failure HRESULT in
     * hrStatus definitely indicates a failure, a success HRESULT only indicates
     * that the first part of class unloading succeeded.
     */
    HRESULT ClassUnloadStarted(
                [in] ClassID classId);

    HRESULT ClassUnloadFinished(
                [in] ClassID classId,
                [in] HRESULT hrStatus);

    /*
     *
     * JIT EVENTS
     *
     */

    /*
     * The CLR calls FunctionUnloadStarted to notify the code
     * profiler that a function is being unloaded.  After returning from this
     * call, the FunctionID is no longer valid.
     */
    HRESULT FunctionUnloadStarted(
                [in] FunctionID functionId);


    /*
     * The CLR calls JITCompilationStarted to notify the code
     * profiler that the JIT compiler is starting to compile a function.
     *
     * The fIsSafeToBlock argument tells the profiler whether or not blocking
     * will affect the operation of the runtime.  If true, blocking may cause
     * the runtime to wait for the calling thread to return from this callback.
     * Although this will not harm the runtime, it will skew the profiling
     * results.
     *
     * NOTE: It is possible to receive more than one JITCompilationStarted/
     * JITCompilationFinished pair for each method.  This is because of how
     * the runtime handles class constructors: method A starts to be JIT'd,
     * then realizes that the class ctor for class B needs to be run, so
     * JIT's it and runs it, and while it's running makes a call to original
     * method A, which causes it to be JIT'd again, and causes the original
     * (incomplete) JIT'ing of A to be aborted.  However, both attempts to
     * JIT A are reported with JIT compilation events.  If the profiler is
     * going to replace IL code for this method with SetILFunctionBody, then
     * it must do so for both JITCompilationStarted events, but may use the
     * same IL block for both.
     *
     * NOTE: A profiler should be tolerant of the sequence of JIT callbacks
     * received in cases where two threads are simultaneously calling a
     * method.  For example, thread A receives JITCompilationStarted.
     * But before thread A receives JITCompilationFinished, thread B
     * receives FunctionEnter with the functionId from thread A's
     * JITCompilationStarted callback.  It may appear that functionId should
     * not yet be valid because JITCompilationFinished had not yet been
     * received.  But it is indeed valid in such a case.
     */
    HRESULT JITCompilationStarted(
                [in] FunctionID functionId,
                [in] BOOL       fIsSafeToBlock);

    /*
     * The CLR calls JITCompilationFinished to notify the code
     * profiler that the JIT compiler has finished compiling a function.
     *
     * The fIsSafeToBlock argument tells the profiler whether or not blocking
     * will affect the operation of the runtime.  If true, blocking may cause
     * the runtime to wait for the calling thread to return from this callback.
     * Although this will not harm the runtime, it will skew the profiling
     * results.
     *
     * The FunctionID is now valid in ICorProfilerInfo APIs.
     *
     * The hrStatus provides the success or failure of the operation
     */
    HRESULT JITCompilationFinished(
                [in] FunctionID functionId,
                [in] HRESULT    hrStatus,
                [in] BOOL       fIsSafeToBlock);

    /*
     * V2 MIGRATION WARNING: DOES NOT ALWAYS OCCUR
     * The JITCachedFunctionSearchStarted/Finished callbacks
     * will now occur only for some functions in regular NGEN images;
     * only profiler-optimized NGEN images will generate callbacks for
     * all functions in the image. Profilers which do not use these callbacks 
     * to force a function to be JIT-compiled should move to using a lazy
     * strategy for gathering function information.
     *
     * This notifies the profiler when a search for a prejitted function is
     * starting.
     *
     *    functionId: the function for which the search is being performed.
     *    bUseCachedFunction: if true, the EE uses the cached function (if applicable)
     *                        if false, the EE jits the function instead of
     *                        using a pre-jitted version.
     *
     * NOTE: Profilers should be tolerant of cases where multiple threads of
     * a profiled app are calling the same method simultaneously.  For example,
     * thread A may receive JITCachedFunctionSearchStarted (and the
     * profiler sets *pbUseCachedFunction=FALSE to force a JIT), thread A
     * then receives JITCompilationStarted/JITCompilationFinished, then
     * thread B receives another JITCachedFunctionSearchStarted for the same
     * method.  It might appear odd to receive this final callback, since the
     * profiler already stated its intention to JIT the method.  But this is
     * occurring because the CLR in thread B decided to send this callback
     * before thread A responded to JITCachedFunctionSearchStarted
     * with *pbUseCachedFunction=FALSE, and the thread B callback
     * hadn't actually been sent until now due how the threads
     * happened to be scheduled.  In such cases where the profiler
     * receives duplicate JITCachedFunctionSearchStarted callbacks for
     * the same functionId, the profiler should be certain to set
     * *pbUseCachedFunction to the same value from this callback
     * when it is called multiple times with the same functionId.
     */
    HRESULT JITCachedFunctionSearchStarted(
                [in] FunctionID functionId,
                [out] BOOL      *pbUseCachedFunction);

    /*
     * V2 MIGRATION WARNING: DOES NOT ALWAYS OCCUR
     * The JITCachedFunctionSearchStarted/Finished callbacks
     * will now occur only for some functions in regular NGEN images;
     * only profiler-optimized NGEN images will generate callbacks for
     * all functions in the image. Profilers which do not use these callbacks 
     * to force a function to be JIT-compiled should move to using a lazy
     * strategy for gathering function information.
     *
     * This notifies the profiler when a search for a cached function has been
     * performed.
     *
     *    functionId: the function for which the search has been performed.
     *    result: the result of the search.  There are two possible results:
     *        COR_PRF_CACHED_FUNCTION_FOUND
     *        COR_PRF_CACHED_FUNCTION_NOT_FOUND
     *
     */
    HRESULT JITCachedFunctionSearchFinished(
                [in] FunctionID        functionId,
                [in] COR_PRF_JIT_CACHE result);

    /*
     * The CLR calls JITFunctionPitched to notify the profiler
     * that a jitted function was removed from memory.  If the pitched
     * function is called in the future, the profiler will receive new
     * JIT compilation events as it is re-jitted.
     *
     * Currently the CLR JIT does not pitch functions, so this callback
     * will not be received.
     *
     * NOTE: the FunctionID is not valid until it is re-jitted.  When it is
     * re-jitted, it will use the same FunctionID value.
     */
    HRESULT JITFunctionPitched(
                [in] FunctionID functionId);

    /*
     * The CLR calls JITInlining to notify the profiler that the jitter
     * is about to inline calleeId into callerId.  Set pfShouldInline to FALSE
     * to prevent the callee from being inlined into the caller, and set to
     * TRUE to allow the inline to occur.
     *
     * NOTE: Inlined functions do not provide Enter/Leave events, so if you desire
     *       an accurate callgraph, you should set FALSE.  Be aware that
     *       setting FALSE will affect performance, since inlining typically
     *       increases speed and reduces separate jitting events for the inlined
     *       method.
     *
     * NOTE: It is also possible to globally disable inlining by setting the
     *       COR_PRF_DISABLE_INLINING flag.
     */
    HRESULT JITInlining(
                [in] FunctionID callerId,
                [in] FunctionID calleeId,
                [out] BOOL      *pfShouldInline);

    /*
     *
     * THREAD EVENTS
     *
     */

    /*
     * The CLR calls ThreadCreated to notify the code profiler
     * that a thread has been created.  The ThreadID is valid immediately.
     */
    HRESULT ThreadCreated(
                [in] ThreadID threadId);

    /*
     * The CLR calls ThreadDestroyed to notify the code profiler
     * that a thread has been destroyed.  The ThreadID is no longer valid
     * at the time of this call.
     */
    HRESULT ThreadDestroyed(
                [in] ThreadID threadId);

    /*
     * The CLR calls ThreadAssignedToOSThread to tell the profiler
     * that a managed thread is being implemented via a particualr OS thread.
     * This callback exists so that the profiler can maintain an accurate
     * OS to Managed thread mapping across fibres.
     */
    HRESULT ThreadAssignedToOSThread(
                [in] ThreadID managedThreadId,
                [in] DWORD    osThreadId);

    /*
     *
     * REMOTING EVENTS
     *
     */

    //
    // Client-side events
    //

    /*
     * NOTE: each of the following pairs of callbacks will occur on the same
     *       thread
     *   RemotingClientInvocationStarted  & RemotingClientSendingMessage
     *   RemotingClientReceivingReply     & RemotingClientInvocationFinished
     *   RemotingServerInvocationReturned & RemotingServerSendingReply
     *
     * There are a few issues with the remoting callbacks that should be outlined.
     * First, remoting function execution is not reflected by the profiler API, so
     * the notifications for functions that are called from the client and executed
     * to the server are not properly received. The actual invocation happens via a
     * proxy object. That creates the illusion to the profiler that certain
     * functions get jit-compiled but they never get used. Second, the profiler does
     * not receive accurate notifications for asynchronous remoting events.
     */

    /*
     * The CLR calls RemotingClientInvocationStarted to notify the profiler that
     * a remoting call has begun.  This event is the same for synchronous and
     * asynchronous calls.
     */
    HRESULT RemotingClientInvocationStarted();

    /*
     * The CLR calls RemotingClientSendingMessage to notify the profiler that
     * a remoting call is requiring the the caller to send an invocation request through
     * a remoting channel.
     *
     * pCookie  - if remoting GUID cookies are active, this value will correspond with the
     *            the value provided in RemotingServerReceivingMessage, if the channel
     *            succeeds in transmitting the message, and if GUID cookies are active on
     *            the server-side process.  This allows easy pairing of remoting calls,
     *            and the creation of a logical call stack.
     * fIsAsync - is true if the call is asynchronous.
     */
    HRESULT RemotingClientSendingMessage(
                [in] GUID *pCookie,
                [in] BOOL fIsAsync);

    /*
     * The CLR calls RemotingClientReceivingReply to notify the profiler that
     * the server-side portion of a remoting call has completed and that the client is
     * now receiving and about to process the reply.
     *
     * pCookie  - if remoting GUID cookies are active, this value will correspond with the
     *            the value provided in RemotingServerSendingReply, if the channel
     *            succeeds in transmitting the message, and if GUID cookies are active on
     *            the server-side process.  This allows easy pairing of remoting calls.
     * fIsAsync - is true if the call is asynchronous.
     */
    HRESULT RemotingClientReceivingReply(
                [in] GUID *pCookie,
                [in] BOOL fIsAsync);

    /*
     * The CLR calls RemotingClientInvocationFinished to notify the profiler that
     * a remoting invocation has run to completion on the client side.  If the call was
     * synchronous, this means that it has also run to completion on the server side.  If
     * the call was asynchronous, a reply may still be expected when the call is handled.
     * If the call is asynchronous, and a reply is expected, then the reply will occur in
     * the form of a call to RemotingClientReceivingReply and an additional call to
     * RemotingClientInvocationFinished to indicate the required secondary processing of
     * an asynchronous call.
     */
    HRESULT RemotingClientInvocationFinished();

    //
    // Server-side events
    //

    /*
     * The CLR calls RemotingServerReceivingMessage to notify the profiler that
     * the process has received a remote method invocation (or activation) request.  If
     * the message request is asynchronous, then the request may be serviced by any
     * arbitrary thread.
     *
     * pCookie  - if remoting GUID cookies are active, this value will correspond with the
     *            the value provided in RemotingClientSendingMessage, if the channel
     *            succeeds in transmitting the message, and if GUID cookies are active on
     *            the client-side process.  This allows easy pairing of remoting calls.
     * fIsAsync - is true if the call is asynchronous.
     */
    HRESULT RemotingServerReceivingMessage(
                [in] GUID *pCookie,
                [in] BOOL fIsAsync);

    /*
     * The CLR calls RemotingServerInvocationStarted to notify the profiler that
     * the process is invoking a method due to a remote method invocation request.
     */
    HRESULT RemotingServerInvocationStarted();

    /*
     * The CLR calls RemotingServerInvocationReturned to notify the profiler that
     * the process has finished invoking a method due to a remote method invocation request.
     */
    HRESULT RemotingServerInvocationReturned();

    /*
     * The CLR calls RemotingServerSendingReply to notify the profiler that
     * the process has finished processing a remote method invocation request and is
     * about to transmit the reply through a channel.
     *
     * pCookie  - if remoting GUID cookies are active, this value will correspond with the
     *            the value provided in RemotingClientReceivingReply, if the channel
     *            succeeds in transmitting the message, and if GUID cookies are active on
     *            the client-side process.  This allows easy pairing of remoting calls.
     * fIsAsync - is true if the call is asynchronous.
     */
    HRESULT RemotingServerSendingReply(
                [in] GUID *pCookie,
                [in] BOOL fIsAsync);

    /*
     *
     * TRANSITION EVENTS
     *
     */

    /*
     * The CLR calls UnmanagedToManagedTransition to notify the
     * code profiler that a transition from unmanaged code to managed code has
     * occurred. functionId is always the ID of the callee, and reason
     * indicates whether the transition was due to a call into managed code from
     * unmanaged, or a return from an unmanaged function called by a managed one.
     *
     * Note that if the reason is COR_PRF_TRANSITION_RETURN and the functionId is
     * non-NULL, then the functionId is that of the unmanaged function, and will
     * never have been jitted. Unmanaged functions still have some basic
     * information associated with them, such as a name, and some metadata.
     *
     * Note that if the reason is COR_PRF_TRANSITION_RETURN and the callee was
     * a PInvoke call indirect, then the runtime does not know the destination
     * of the call and functionId will be NULL.
     *
     * Note that if the reason is COR_PRF_TRANSITION_CALL then it may be possible
     * that the callee has not yet been JIT-compiled.
     */
    HRESULT UnmanagedToManagedTransition(
                [in] FunctionID                functionId,
                [in] COR_PRF_TRANSITION_REASON reason);


    /*
     * The CLR calls ManagedToUnmanagedTransition to notify the
     * code profiler that a transition from managed code to unmanaged code has
     * occurred. functionId is always the ID of the callee, and reason
     * indicates whether the transition was due to a call into unmanaged code from
     * managed, or a return from an managed function called by an unmanaged one.
     *
     * Note that if the reason is COR_PRF_TRANSITION_CALL, then the functionId
     * is that of the unmanaged function, and will never have been jitted.
     * Unmanaged functions still have some basic information associated with
     * them, such as a name, and some metadata.
     *
     * Note that if the reason is COR_PRF_TRANSITION_CALL and the callee is
     * a PInvoke call indirect, then the runtime does not know the destination
     * of the call and functionId will be NULL.
     */
    HRESULT ManagedToUnmanagedTransition(
                [in] FunctionID                functionId,
                [in] COR_PRF_TRANSITION_REASON reason);


    /*
     *
     * RUNTIME SUSPENSION EVENTS
     *
     */

    /*
     * The CLR calls RuntimeSuspendStarted to notify the code profiler
     * that the runtime is about to suspend all of the runtime threads.
     * All runtime threads that are in unmanaged code are permitted to continue
     * running until they try to re-enter the runtime, at which point they will
     * also suspend until the runtime resumes.  This also applies to new threads
     * that enter the runtime.  All threads within the runtime are either
     * suspended immediately if they are in interruptible code, or asked to
     * suspend when they do reach interruptible code.
     *
     * suspendReason make be any of the following values:
     *  COR_PRF_SUSPEND_FOR_GC
     *      the runtime is suspending to service a GC request.  The GC-related
     *      callbacks will occur between the RuntimeSuspendFinished and
     *      RuntimeResumeStarted events.
     *  COR_PRF_SUSPEND_FOR_CODE_PITCHING
     *      the runtime is suspending so that code pitching may occur.  This
     *      only occurs when the EJit is active with code pitching enabled.
     *      Code pitching callbacks will occur between the
     *      RuntimeSuspendFinished and RuntimeResumeStarted events.
     *  COR_PRF_SUSPEND_FOR_APPDOMAIN_SHUTDOWN
     *      the runtime is suspending so that an AppDomain can be shut down.
     *      While the runtime is suspended, the runtime will determine which
     *      threads are in the AppDomain that is being shut down, set them to
     *      abort when they resume, and then resumes the runtime.  There are
     *      no AppDomain-specific callbacks during this suspension.
     *  COR_PRF_SUSPEND_FOR_SHUTDOWN
     *      the runtime is shutting down, and it must suspend all threads to
     *      complete the operation.
     *  COR_PRF_SUSPEND_FOR_GC_PREP
     *      the runtime is preparing for a GC.
     *  COR_PRF_SUSPEND_FOR_INPROC_DEBUGGER
     *      the runtime is suspending for in-process debugging.
     *  COR_PRF_SUSPEND_OTHER
     *      the runtime is suspending for a reason other than those above.
     */
    HRESULT RuntimeSuspendStarted(
            [in] COR_PRF_SUSPEND_REASON suspendReason);

    /*
     * The CLR calls RuntimeSuspendFinished to notify the code profiler
     * that the runtime has suspended all threads needed for a runtime
     * suspension.  Note that not all runtime threads are required to be
     * suspended, as described in the comment for RuntimeSuspendStarted.
     *
     * NOTE: It is guaranteed that this event will occur on the same ThreadID
     * as RuntimeSuspendStarted occurred on.
     */
    HRESULT RuntimeSuspendFinished();

    /*
     * The CLR calls RuntimeSuspendAborted to notify the code profiler
     * that the runtime is aborting the runtime suspension that was occurring.
     * This may occur if two threads simultaneously attempt to suspend the
     * runtime.
     *
     * NOTE: It is guaranteed that this event will occur on the same ThreadID
     * as the RuntimeSuspendStarted occurred on, and that only one of
     * RuntimeSuspendFinished and RuntimeSuspendAborted may occur on a single
     * thread following a RuntimeSuspendStarted event.
     */
    HRESULT RuntimeSuspendAborted();

    /*
     * The CLR calls RuntimeResumeStarted to notify the code profiler
     * that the runtime is about to resume all of the runtime threads.
     */
    HRESULT RuntimeResumeStarted();

    /*
     * The CLR calls RuntimeResumeFinished to notify the code profiler
     * that the runtime has finished resuming all of it's threads and is now
     * back in normal operation.
     *
     * NOTE: It is *NOT* guaranteed that this event will occur on the same
     * ThreadID as the RuntimeSuspendStarted occurred on, but is guaranteed
     * to occur on the same ThreadID as the RuntimeResumeStarted occurred on.
     */
    HRESULT RuntimeResumeFinished();

    /*
     * The CLR calls RuntimeThreadSuspended to notify the code profiler
     * that a particular thread has been suspended. 
     *
     * This notification may occur any time between the RuntimeSuspendStarted
     * and the associated RuntimeResumeStarted. Notifications that occur
     * between RuntimeSuspendFinished and RuntimeResumeStarted are for
     * threads that had been running in unmanaged code and were suspended
     * upon entry to the runtime.
     */
    HRESULT RuntimeThreadSuspended(
                    [in] ThreadID threadId);

    /*
     * The CLR calls RuntimeThreadResumed to notify the code profiler
     * that a particular thread has been resumed after being suspended due to
     * a runtime suspension.
     */
    HRESULT RuntimeThreadResumed(
                    [in] ThreadID threadId);

    /*
     *
     * GC EVENTS
     *
     * NOTE: All of these callbacks (except ObjectAllocated) are made while the
     *       runtime is suspended, so none of the ObjectID values can change until
     *       the runtime resumes and another GC occurs.
     *
     * NOTE: The profiler will receive GC-related events (except ObjectAllocated)
     *       when the profiler has been suspended for COR_PRF_SUSPEND_FOR_GC *except*
     *       for one special case.  When the runtime is shutting down, there is a
     *       stage where it is suspended for COR_PRF_SUSPEND_FOR_SHUTDOWN reason and
     *       is never resumed.  But after this suspension a garbage collection may
     *       occur without a COR_PRF_SUSPEND_FOR_GC suspension notification, and
     *       the profiler will thus receive GC-related callbacks.
     *
     * NOTE: All of these callbacks (except ObjectAllocated) may be called more than
     *       once during the same GC. These calls should be considered multiple parts of
     *       one long report; the profiler should simply aggregate the information provided
     *       in all of them.
     */

    /*
     * The CLR calls MovedReferences with information about
     * object references that moved as a result of garbage collection.
     *
     * cMovedObjectIDRanges is a count of the number of ObjectID ranges that
     *      were moved.
     * oldObjectIDRangeStart is an array of elements, each of which is the start
     *      value of a range of ObjectID values before being moved.
     * newObjectIDRangeStart is an array of elements, each of which is the start
     *      value of a range of ObjectID values after being moved.
     * cObjectIDRangeLength is an array of elements, each of which states the
     *      size of the moved ObjectID value range.
     *
     * The last three arguments of this function are parallel arrays.
     *
     * In other words, if an ObjectID value lies within the range
     *      oldObjectIDRangeStart[i] <= ObjectID < oldObjectIDRangeStart[i] + cObjectIDRangeLength[i]
     * for 0 <= i < cMovedObjectIDRanges, then the ObjectID value has changed to
     *      ObjectID - oldObjectIDRangeStart[i] + newObjectIDRangeStart[i]
     *
     * NOTE: None of the objectIDs returned by MovedReferences are valid during the callback
     * itself, as the GC may be in the middle of moving objects from old to new. Thus profilers
     * should not attempt to inspect objects during a MovedReferences call. At 
     * GarbageCollectionFinished, all objects have been moved to their new locations, and
     * inspection may be done.
     */
    HRESULT MovedReferences(
                [in]                                ULONG    cMovedObjectIDRanges,
                [in, size_is(cMovedObjectIDRanges)] ObjectID oldObjectIDRangeStart[] ,
                [in, size_is(cMovedObjectIDRanges)] ObjectID newObjectIDRangeStart[] ,
                [in, size_is(cMovedObjectIDRanges)] ULONG    cObjectIDRangeLength[] );

    /*
     * The CLR calls ObjectAllocated to notify the code profiler
     * an object was allocated on the heap. This notification does not fire
     * for allocations from the stack, nor from unmanaged memory.
     *
     * It is possible to receive a classId that corresponds to a regular class
     * that has not been loaded yet. The profiler will receive a class load
     * callback for that class immediately after the object creation callback.
     */
    HRESULT ObjectAllocated(
                [in] ObjectID objectId,
                [in] ClassID classId);

    /*
     * The CLR calls ObjectsAllocatedByClass to notify the code
     * profiler about the number of objects of a particular class that were
     * allocated since the previous garbage collection. The classes and the
     * counts are passed in parallel arrays. (Classes for which no instances
     * have been allocated since the previous GC are omitted entirely.)
     *
     * NOTE: This callback will not report objects allocated in the large
     *       object heap.
     *
     * NOTE: The numbers here are only estimates. Use ObjectAllocated for
     *       exact counts.
     */
    HRESULT ObjectsAllocatedByClass(
                [in]                       ULONG   cClassCount,
                [in, size_is(cClassCount)] ClassID classIds[] ,
                [in, size_is(cClassCount)] ULONG   cObjects[] );

    /*
     * The CLR calls ObjectReferences to provide information
     * about objects in memory referenced by a given object.  This function
     * is called for each object remaining in the GC heap after a collection
     * has completed.  If the profiler returns an error from this callback,
     * the profiling services will discontinue invoking this callback until the
     * next GC.  This callback can be used in conjunction with the
     * RootReferences callback to create a complete object reference graph for
     * the runtime.
     *
     * NOTE: The CLR will ensure that each object reference is reported only
     * once by this function.
     *
     * NOTE: None of the objectIDs returned by ObjectReferences are valid during the callback
     * itself, as the GC may be in the middle of moving objects from old to new. Thus profilers
     * should not attempt to inspect objects during an ObjectReferences call. At 
     * GarbageCollectionFinished, all objects have been moved to their new locations, and
     * inspection may be done.
     */
    HRESULT ObjectReferences(
                [in]                       ObjectID objectId,
                [in]                       ClassID  classId,
                [in]                       ULONG    cObjectRefs,
                [in, size_is(cObjectRefs)] ObjectID objectRefIds[] );

    /*
     * The CLR calls RootReferences with information about root
     * references after a garbage collection has occurred. Static object
     * references and references to objects on a stack are co-mingled in the
     * arrays.
     *
     * NOTE: It is possible to get NULL ObjectIDs in the RootReferences callback.
     * For example, all object references declared on the stack are treated as
     * roots by the GC, and will always be reported.
     *
     * NOTE: None of the objectIDs returned by RootReferences are valid during the callback
     * itself, as the GC may be in the middle of moving objects from old to new. Thus profilers
     * should not attempt to inspect objects during a RootReferences call. At 
     * GarbageCollectionFinished, all objects have been moved to their new locations, and
     * inspection may be done.
     */
    HRESULT RootReferences(
                [in]                     ULONG    cRootRefs,
                [in, size_is(cRootRefs)] ObjectID rootRefIds[] );


    /*
     *
     * EXCEPTION EVENTS
     *
     */

    //
    // Exception creation
    //

    /*
     * The CLR calls ExceptionThrown to notify the code
     * profiler that an exception has been thrown.
     *
     * NOTE: This function is only called if the exception reaches
     *       managed code.
     *
     * NOTE: The profiler should not block here, since the stack may not be in a
     *       GC-friendly state and so preemptive GC cannot be enabled.  If the
     *       profiler blocks here and a GC is attempted, the runtime will block
     *       until this callback returns.  Also, the profiler may NOT call into
     *       managed code or in any way cause a managed memory allocation.
     */
    HRESULT ExceptionThrown(
                [in] ObjectID thrownObjectId);

    //
    // Search phase
    //

    /*
     * The CLR calls ExceptionSearchFunctionEnter to notify the profiler
     * that the search phase of exception handling has entered a function.
     */
    HRESULT ExceptionSearchFunctionEnter(
                [in] FunctionID functionId);

    /*
     * The CLR calls ExceptionSearchFunctionLeave to notify the profiler
     * that the search phase of exception handling has left a function.
     */
    HRESULT ExceptionSearchFunctionLeave();

    /*
     * The CLR will call ExceptionSearchFilterEnter just before excecuting
     * a user filter.  The functionID is that of the function containing the filter.
     */
    HRESULT ExceptionSearchFilterEnter(
                [in] FunctionID functionId);

    /*
     * The CLR will call ExceptionSearchFilterLeave immediately after
     * executing a user filter.
     */
    HRESULT ExceptionSearchFilterLeave();

    /*
     * The CLR will call ExceptionSearchCatcherFound when the search
     * phase of exception handling has located a handler for the exception that
     * was thrown.
     */
    HRESULT ExceptionSearchCatcherFound(
                [in] FunctionID functionId);

    /*
     * DEPRECATED. It is the job of the unmanaged profiler to detect OS
     * handling of exceptions.
     */
    HRESULT ExceptionOSHandlerEnter(
                [in] UINT_PTR __unused);

    /*
     * DEPRECATED. It is the job of the unmanaged profiler to detect OS
     * handling of exceptions.
     */
    HRESULT ExceptionOSHandlerLeave(
                [in] UINT_PTR __unused);

    //
    // Unwind phase
    //

    /*
     * The CLR calls ExceptionUnwindFunctionEnter to notify the profiler
     * that the unwind phase of exception handling has entered a function.
     *
     * NOTE: The profiler should not block here, since the stack may not be in a
     *       GC-friendly state and so preemptive GC cannot be enabled.  If the
     *       profiler blocks here and a GC is attempted, the runtime will block
     *       until this callback returns.  Also, the profiler may NOT call into
     *       managed code or in any way cause a managed memory allocation.
     */
    HRESULT ExceptionUnwindFunctionEnter(
                [in] FunctionID functionId);

    /*
     * The CLR calls ExceptionUnwindFunctionLeave to notify the profiler
     * that the unwind phase of exception handling has left a function.  The
     * function instance and it's stack data has now been removed from the stack.
     *
     * NOTE: The profiler should not block here, since the stack may not be in a
     *       GC-friendly state and so preemptive GC cannot be enabled.  If the
     *       profiler blocks here and a GC is attempted, the runtime will block
     *       until this callback returns.  Also, the profiler may NOT call into
     *       managed code or in any way cause a managed memory allocation.
     */
    HRESULT ExceptionUnwindFunctionLeave();

    /*
     * The CLR calls ExceptionUnwindFinallyEnter to notify the profiler
     * that the unwind phase of exception is entering a finally clause contained
     * in the specified function.
     *
     * NOTE: The profiler should not block here, since the stack may not be in a
     *       GC-friendly state and so preemptive GC cannot be enabled.  If the
     *       profiler blocks here and a GC is attempted, the runtime will block
     *       until this callback returns.  Also, the profiler may NOT call into
     *       managed code or in any way cause a managed memory allocation.
     */
    HRESULT ExceptionUnwindFinallyEnter(
                [in] FunctionID functionId);

    /*
     * The CLR calls ExceptionUnwindFinallyLeave to notify the profiler
     * that the unwind phase of exception is leaving a finally clause.
     *
     * NOTE: The profiler should not block here, since the stack may not be in a
     *       GC-friendly state and so preemptive GC cannot be enabled.  If the
     *       profiler blocks here and a GC is attempted, the runtime will block
     *       until this callback returns.  Also, the profiler may NOT call into
     *       managed code or in any way cause a managed memory allocation.
     */
    HRESULT ExceptionUnwindFinallyLeave();

    /*
     * The CLR calls this function just before passing control to
     * the appropriate catch block.  Note that this is called only if the
     * catch point is in JIT'ed code.  An exception that is caught in
     * unmanaged code, or in the internal code of the CLR will
     * not generate this notification.  The ObjectID is passed again since
     * a GC could have moved the object since the ExceptionThrown
     * notification.
     *
     * NOTE: The profiler should not block here, since the stack may not be in a
     *       GC-friendly state and so preemptive GC cannot be enabled.  If the
     *       profiler blocks here and a GC is attempted, the runtime will block
     *       until this callback returns.  Also, the profiler may NOT call into
     *       managed code or in any way cause a managed memory allocation.
     */
    HRESULT ExceptionCatcherEnter(
                [in] FunctionID functionId,
                [in] ObjectID   objectId);

    /*
     * The CLR calls ExceptionCatcherLeave when the runtime leaves
     * the catcher's code.
     *
     * NOTE: The profiler should not block here, since the stack may not be in a
     *       GC-friendly state and so preemptive GC cannot be enabled.  If the
     *       profiler blocks here and a GC is attempted, the runtime will block
     *       until this callback returns.  Also, the profiler may NOT call into
     *       managed code or in any way cause a managed memory allocation.
     */
    HRESULT ExceptionCatcherLeave();

    /*
     *  CLR<->COM interop vtable creation/destruction.
     */

    /*
     * The CLR calls this function when an CLR<->COM interop vtable
     * for a particular IID and for a particular class has been created.
     * This provides the ClassID of the class for which this vtable has been
     * created, the IID it implements, the start of the vtable and how many
     * slots are in it.
     *
     * NOTE: The profiler should not block here, since the stack may not be in a
     *       GC-friendly state and so preemptive GC cannot be enabled.  If the
     *       profiler blocks here and a GC is attempted, the runtime will block
     *       until this callback returns.  Also, the profiler may NOT call into
     *       managed code or in any way cause a managed memory allocation.
     *
     * NOTE: It is possible to receive a NULL GUID if the interface is
     *       internal only.
     */
    HRESULT COMClassicVTableCreated(
               [in] ClassID wrappedClassId,
               [in] REFGUID implementedIID,
               [in] void    *pVTable,
               [in] ULONG   cSlots);

    /*
     * The CLR calls this function when a CLR<->COM interop vtable is
     * being destroyed.  Provided are the ClassID, IID and vtable pointer for
     * the destroyed vtable.
     *
     * NOTE: The profiler should not block here, since the stack may not be in a
     *       GC-friendly state and so preemptive GC cannot be enabled.  If the
     *       profiler blocks here and a GC is attempted, the runtime will block
     *       until this callback returns.  Also, the profiler may NOT call into
     *       managed code or in any way cause a managed memory allocation.
     *
     * NOTE: It is possible to receive a NULL GUID if the interface is
     *       internal only.
     *
     * NOTE: This callback is likely never to occur, since the destruction of
     *       vtables occurs very close to Shutdown.
     */
    HRESULT COMClassicVTableDestroyed(
               [in] ClassID wrappedClassId,
               [in] REFGUID implementedIID,
               [in] void    *pVTable);

    /*
     * DEPRECATED. These callbacks are no longer delivered.
     */
    HRESULT ExceptionCLRCatcherFound();

    HRESULT ExceptionCLRCatcherExecute();
}

/*
 * COR_PRF_GC_ROOT_KIND describes the kind of GC root exposed by
 * the RootReferences2 callback.
 */

typedef enum
{
    COR_PRF_GC_ROOT_STACK = 1,        // Variables on the stack
    COR_PRF_GC_ROOT_FINALIZER = 2,    // Entry in the finalizer queue
    COR_PRF_GC_ROOT_HANDLE = 3,        // GC Handle
    COR_PRF_GC_ROOT_OTHER = 0        //Misc. roots
}   COR_PRF_GC_ROOT_KIND;


/*
 * COR_PRF_GC_ROOT_FLAGS describes properties of a GC root
 * exposed by the RootReferences callback.
 */

typedef enum
{  
    COR_PRF_GC_ROOT_PINNING = 0x1,    // Prevents GC from moving the object
    COR_PRF_GC_ROOT_WEAKREF = 0x2,    // Does not prevent collection
    COR_PRF_GC_ROOT_INTERIOR = 0x4,   // Refers to a field of the object rather than the object itself
    COR_PRF_GC_ROOT_REFCOUNTED = 0x8, // Whether it prevents collection depends on a refcount - if not,
                                      // COR_PRF_GC_ROOT_WEAKREF will be set also
}   COR_PRF_GC_ROOT_FLAGS;

 
/*
 * COR_PRF_FINALIZER_FLAGS is used by FinalizableObjectQueued to describe
 * the finalizer for the object.
 */

typedef enum
{
    COR_PRF_FINALIZER_CRITICAL = 0x1    // Critical finalizer
}   COR_PRF_FINALIZER_FLAGS;

 
/*
 * COR_PRF_GC_GENERATION contains the numbers used to represent each GC generation
 * in the GetGenerationBounds and GetObjectGeneration functions.
 */

typedef enum
{
    COR_PRF_GC_GEN_0 = 0,
    COR_PRF_GC_GEN_1 = 1,
    COR_PRF_GC_GEN_2 = 2,
    COR_PRF_GC_LARGE_OBJECT_HEAP = 3
}   COR_PRF_GC_GENERATION;


/*
 * COR_PRF_GC_GENERATION_RANGE describes a range of memory in the GetGenerationBounds and GetObjectGeneration functions.
 * Note that the rangeLength member is only guaranteed to be accurate if GetGenerationBounds or GetObjectGeneration are
 * called from a GarbageCollectionStarted or GarbageCollectionFinished notification
 */
typedef struct COR_PRF_GC_GENERATION_RANGE
{
    COR_PRF_GC_GENERATION   generation;             // what generation the range of memory belongs to
    ObjectID                rangeStart;             // the start of the range
    UINT_PTR                rangeLength;            // the used length of the range
    UINT_PTR                rangeLengthReserved;    // the amount of memory reserved for the range (including rangeLength)

}   COR_PRF_GC_GENERATION_RANGE;



/*
 * COR_PRF_CLAUSE_TYPE defines the various clause codes for the EX clauses
 */
typedef enum
{
    COR_PRF_CLAUSE_NONE = 0,  // not a real clause (only used in error cases)
    COR_PRF_CLAUSE_FILTER = 1,  
    COR_PRF_CLAUSE_CATCH = 2,  
    COR_PRF_CLAUSE_FINALLY = 3, 
}   COR_PRF_CLAUSE_TYPE;

/*
 * COR_PRF_EX_CLAUSE_INFO identifies a specific exception clause instance and its associated frame. 
 * When an exception notification is received, GetNotifiedExceptionClauseInfo() may be used to get the 
 * native address and frame information for the exception clause (catch/finally/filter) that is 
 * about to be run (ExceptionCatchEnter, ExceptionUnwindFinallyEnter, ExceptionFilterEnter) or has just 
 * been run (ExceptionCatchLeave, ExceptionUnwindFinallyLeave, ExceptionFilterLeave).  
 */
typedef struct COR_PRF_EX_CLAUSE_INFO 
{
    COR_PRF_CLAUSE_TYPE  clauseType; // the type of clause we just entered or left
    UINT_PTR  programCounter;   // the native entry point of the clause handler (e.g. EIP)
    UINT_PTR framePointer;    // the logical frame pointer (e.g. EBP) for that clause handler
    UINT_PTR shadowStackPointer;  // the shadow stack pointer (IA64 only, BSP)
}   COR_PRF_EX_CLAUSE_INFO;

/*
 * COR_PRF_GC_REASON describes the reason for a given GC.
 */
typedef enum
{
    COR_PRF_GC_INDUCED = 1,     // Induced by GC.Collect
    COR_PRF_GC_OTHER = 0        // Anything else
}   COR_PRF_GC_REASON;


/*
 * The ICorProfilerCallback2 interface is used by the CLR to notify a
 * code profiler when events have occurred that the code profiler has registered
 * an in interest in receiving.  These are new callbacks implemented in V2.0
 * of the runtime.
 *
 * The methods implemented on this interface return S_OK on success, or E_FAIL
 * on failure.
 */

[
    object,
    uuid(8A8CC829-CCF2-49fe-BBAE-0F022228071A),
    pointer_default(unique),
    local
]
interface ICorProfilerCallback2 : ICorProfilerCallback
{

    /*
     *
     * THREAD EVENTS
     *
     */

    /*
     * The CLR calls ThreadNameChanged to notify the code profiler
     * that a thread's name has changed.
     *
     * name is not NULL terminated.
     *
     */
    HRESULT ThreadNameChanged(
                [in] ThreadID threadId,
                [in] ULONG cchName,
                [in] WCHAR name[]);


    /*
     *
     * GARBAGE COLLECTION EVENTS
     *
     */

    /*
     * The CLR calls GarbageCollectionStarted before beginning a 
     * garbage collection. All GC callbacks pertaining to this
     * collection will occur between the GarbageCollectionStarted
     * callback and the corresponding GarbageCollectionFinished
     * callback. Corresponding GarbageCollectionStarted and 
     * GarbageCollectionFinished callbacks need not occur on the same thread.
     *
     *          cGenerations indicates the total number of entries in
     *                the generationCollected array
     *          generationCollected is an array of booleans, indexed
     *                by COR_PRF_GC_GENERATIONS, indicating which
     *                generations are being collected in this collection
     *          reason indicates whether this GC was induced
     *                by the application calling GC.Collect().
     *
     * NOTE: It is safe to inspect objects in their original locations
     * during this callback. The GC will begin moving objects after
     * the profiler returns from this callback. Therefore, after 
     * returning, the profiler should consider all ObjectIDs to be invalid
     * until it receives a GarbageCollectionFinished callback.
     */
    HRESULT GarbageCollectionStarted(
                [in] int cGenerations,
                [in, size_is(cGenerations), length_is(cGenerations)] BOOL generationCollected[],
                [in] COR_PRF_GC_REASON reason);

    /*
     * The CLR calls SurvivingReferences with information about
     * object references that survived a garbage collection.
     *
     * Generally, the CLR calls SurvivingReferences for non-compacting garbage collections.
     * For compacting garbage collections, MovedReferences is called instead.
     *
     * The exception to this rule is that the CLR always calls SurvivingReferences for objects
     * in the large object heap, which is not compacted.
     *
     * Multiple calls to SurvivingReferences may be received during a particular
     * garbage collection, due to limited internal buffering, multiple threads reporting
     * in the case of server gc, and other reasons.
     * In the case of multiple calls, the information is cumulative - all of the references
     * reported in any SurvivingReferences call survive this collection.
     *
     * cSurvivingObjectIDRanges is a count of the number of ObjectID ranges that
     *      survived.
     * objectIDRangeStart is an array of elements, each of which is the start
     *      value of a range of ObjectID values that survived the collection.
     * cObjectIDRangeLength is an array of elements, each of which states the
     *      size of the surviving ObjectID value range.
     *
     * The last two arguments of this function are parallel arrays.
     *
     * In other words, if an ObjectID value lies within the range
     *      objectIDRangeStart[i] <= ObjectID < objectIDRangeStart[i] + cObjectIDRangeLength[i]
     * for 0 <= i < cMovedObjectIDRanges, then the ObjectID has survived the collection
     */
    HRESULT SurvivingReferences(
                [in]                                    ULONG    cSurvivingObjectIDRanges,
                [in, size_is(cSurvivingObjectIDRanges)] ObjectID objectIDRangeStart[] ,
                [in, size_is(cSurvivingObjectIDRanges)] ULONG    cObjectIDRangeLength[] );
    /*
     * The CLR calls GarbageCollectionFinished after a garbage
     * collection has completed and all GC callbacks have been
     * issued for it.
     *
     * NOTE: It is now safe to inspect objects in their
     * final locations.
     */
    HRESULT GarbageCollectionFinished();

    /*
     * The CLR calls FinalizeableObjectQueued to notify the code profiler
     * that an object with a finalizer (destructor in C# parlance) has
     * just been queued to the finalizer thread for execution of its
     * Finalize method.
     *
     * finalizerFlags describes aspects of the finalizer, and takes its
     *     value from COR_PRF_FINALIZER_FLAGS.
     *
     */

    HRESULT FinalizeableObjectQueued(
                [in] DWORD finalizerFlags,
                [in] ObjectID objectID);

    /*
     * The CLR calls RootReferences2 with information about root
     * references after a garbage collection has occurred.
     * For each root reference in rootRefIds, there is information in
     * rootClassifications to classify it. Depending on the classification,
     * rootsIds may contain additional information. The information in
     * rootKinds and rootFlags contains information about the location and
     * properties of the reference.
     *
     * If the profiler implements ICorProfilerCallback2, both
     * ICorProfilerCallback::RootReferences and ICorProfilerCallback2::RootReferences2
     * are called. As the information passed to RootReferences2 is a superset
     * of the one passed to RootReferences, profilers will normally implement
     * one or the other, but not both.
     *
     * If the root kind is STACK, the ID is the FunctionID of the
     * function containing the variable. If the FunctionID is 0, the function
     * is an unnamed function internal to the CLR.
     *
     * If the root kind is HANDLE, the ID is the GCHandleID.
     *
     * For the other root kinds, the ID is an opaque value and should
     * be ignored.
     *
     * It's possible for entries in rootRefIds to be 0 - this just
     * implies the corresponding root reference was null and thus did not
     * refer to an object on the managed heap.
     *
     * NOTE: None of the objectIDs returned by RootReferences2 are valid during the callback
     * itself, as the GC may be in the middle of moving objects from old to new. Thus profilers
     * should not attempt to inspect objects during a RootReferences2 call. At 
     * GarbageCollectionFinished, all objects have been moved to their new locations, and
     * inspection may be done.
     */

    HRESULT RootReferences2(
                [in]                     ULONG    cRootRefs,
                [in, size_is(cRootRefs)] ObjectID rootRefIds[],
                [in, size_is(cRootRefs)] COR_PRF_GC_ROOT_KIND rootKinds[],
                [in, size_is(cRootRefs)] COR_PRF_GC_ROOT_FLAGS rootFlags[],
                [in, size_is(cRootRefs)] UINT_PTR rootIds[]);

    /*
     * The CLR calls HandleCreated when a gc handle has been created.
     *
     */

    HRESULT HandleCreated(
                [in] GCHandleID handleId,
                [in] ObjectID initialObjectId);

    /*
     * The CLR calls HandleDestroyed when a gc handle has been destroyed.
     *
     */

    HRESULT HandleDestroyed(
                [in] GCHandleID handleId);
}


/*
 * The CLR implements the ICorProfilerInfo interface. This interface is
 * used by a code profiler to communicate with the CLR to control event
 * monitoring and request information. The CLR passes an
 * ICorProfilerInfo interface to each code profiler during initialization.
 *
 * A code profiler can call methods on the ICorProfilerInfo interface to get
 * information about managed code being executed under the control of the CLR
 *
 * The ICorProfilerInfo interface implemented by the CLR uses the free
 * threaded model.
 *
 * The methods implemented on this interface return S_OK on success, or E_FAIL
 * on failure.
 *
 */

[
    object,
    uuid(28B5557D-3F3F-48b4-90B2-5F9EEA2F6C48),
    pointer_default(unique),
    local
]
interface ICorProfilerInfo : IUnknown
{
    /*
     * The code profiler calls GetClassFromObject to obtain the ClassID of an
     * object given its ObjectID.
     */
    HRESULT GetClassFromObject(
                [in]  ObjectID objectId,
                [out] ClassID *pClassId);

    /*
     * V2 MIGRATION WARNING - DOES NOT WORK FOR GENERIC TYPES
     *
     * This function will be removed in a future release, so
     * use GetClassFromTokenAndTypeArgs for all types.
     */
    HRESULT GetClassFromToken(
                [in]  ModuleID  moduleId,
                [in]  mdTypeDef typeDef,
                [out] ClassID   *pClassId);

    /*
     * V2 MIGRATION WARNING - WILL NOT WORK WITH .NET FRAMEWORK
     * FUNCTIONS
     *
     * This function will be removed in a future release; use GetCodeInfo2
     * in all cases.
     */
    HRESULT GetCodeInfo(
                [in]  FunctionID functionId,
                [out] LPCBYTE    *pStart,
                [out] ULONG      *pcSize);

    /*
     * The code profiler calls GetEventMask to obtain the current event
     * categories for which it is to receive event notifications from the COM+
     * Runtime.
     */
    HRESULT GetEventMask(
                [out] DWORD *pdwEvents);

    /*
     * The code profiler calls GetFunctionFromIP to map an instruction pointer
     * in managed code to a FunctionID.
     */
    HRESULT GetFunctionFromIP(
                [in]  LPCBYTE    ip,
                [out] FunctionID *pFunctionId);

    /*
     * V2 MIGRATION WARNING - WILL NOT WORK FOR GENERIC FUNCTIONS OR
     * FUNCTIONS ON GENERIC TYPES
     *
     * This function will be removed in a future release, so use
     * GetFunctionFromTokenAndTypeArgs for all functions.
     */
    HRESULT GetFunctionFromToken(
                [in]  ModuleID   moduleId,
                [in]  mdToken    token,
                [out] FunctionID *pFunctionId);

    /*
     * The code profiler calls GetHandleFromThread to map a ThreadID to a Win32
     * thread handle. The profiler must call DuplicateHandle on the handle
     * before using it.
     */
    HRESULT GetHandleFromThread(
                [in]  ThreadID threadId,
                [out] HANDLE  *phThread);

    /*
     * The code profiler calls GetObjectSize to obtain the size of an object.
     * Note that types like arrays and strings may have a different size for each object.
     */
    HRESULT GetObjectSize(
                [in]  ObjectID objectId,
                [out] ULONG  *pcSize);

    /*
     * This will return S_OK if the ClassID provided is an array class, and will
     * fill out the information for any non-null out params.  S_FALSE will be
     * returned if the ClassID is not an array.
     *
     * classId       : the ClassID to return information about
     * pBaseElemType : the array's base element type
     * pBaseClassId  : the base ClassID if the element type == ELEMENT_TYPE_CLASS
     * pcRank        : the number of dimensions of the array
     */
    HRESULT IsArrayClass(
                [in]  ClassID        classId,
                [out] CorElementType *pBaseElemType,
                [out] ClassID        *pBaseClassId,
                [out] ULONG          *pcRank);

    /*
     * The code profiler calls GetThreadInfo to obtain the current Win32 thread ID for
     * the specified thread.
     */
    HRESULT GetThreadInfo(
                [in]  ThreadID threadId,
                [out] DWORD    *pdwWin32ThreadId);

    /*
     * The code profiler calls GetCurrentThreadID to get the managed thread ID
     * for the current thread.
     *
     * NOTE: GetCurrentThreadID may return CORPROF_E_NOT_MANAGED_THREAD if the
     * current thread is an internal runtime thread, and the returned value of
     * pThreadId will be NULL.
     */
    HRESULT GetCurrentThreadID(
                [out] ThreadID *pThreadId);

    /*
     * V2 MIGRATION NOTE - More information is available for generic types
     * from GetClassIDInfo2.
     *
     * Returns the parent module a class is defined in, along with the
     * metadata token for the class.  One can call GetModuleMetaData
     * to obtain the metadata interface for a given module.  The token
     * can then be used to access the metadata for this class.
     */
    HRESULT GetClassIDInfo(
                [in]  ClassID   classId,
                [out] ModuleID  *pModuleId,
                [out] mdTypeDef *pTypeDefToken);

    /*
     * Return the parent class for a given function.  Also return the metadata
     * token which can be used to read the metadata.
     *
     * V2 MIGRATION WARNING - LESS INFORMATION FOR GENERIC CLASSES
     * The ClassID of a function on a generic class may not be obtainable without
     * more context about the use of the function. In this case, *pClassId will be 0;
     * try using GetFunctionInfo2 with a COR_PRF_FRAME_INFO to give more context.
     */
    HRESULT GetFunctionInfo(
                [in]  FunctionID functionId,
                [out] ClassID    *pClassId,
                [out] ModuleID   *pModuleId,
                [out] mdToken    *pToken);

    /*
     * The code profiler calls SetEventMask to sets the event categories for
     * which it is set to receive notification from the CLR.
     */
    HRESULT SetEventMask(
                [in] DWORD dwEvents);

    /*
     * The code profiler calls SetFunctionHooks to specify handlers
     * for FunctionEnter, FunctionLeave, and FunctionTailcall.
     *
     * Note that only one set of callbacks may be active at a time. Thus,
     * if a profiler calls both SetEnterLeaveFunctionHooks and
     * SetEnterLeaveFunctionHooks2, then SetEnterLeaveFunctionHooks2
     * wins.
     *
     * Each function pointer may be null to disable that callback.
     *
     * SetEnterLeaveFunctionHooks may only be called from the
     * profiler's Initialize() callback.
     */
    HRESULT SetEnterLeaveFunctionHooks(
                [in] FunctionEnter    *pFuncEnter,
                [in] FunctionLeave    *pFuncLeave,
                [in] FunctionTailcall *pFuncTailcall);

    /*
     * This is used for mapping FunctionIDs to alternative values that will be
     * passed to the callbacks
     */
    HRESULT SetFunctionIDMapper(
                [in] FunctionIDMapper *pFunc);

    /*
     * For a given function, retrieve the token value and an instance of the
     * meta data interface which can be used against this token.
     */
    HRESULT GetTokenAndMetaDataFromFunction(
                [in]  FunctionID functionId,
                [in]  REFIID     riid,
                [out] IUnknown   **ppImport,
                [out] mdToken    *pToken);

    /*
     * Retrieve information about a given module.
     *
     * The name returned will be the filename. For dynamic modules, the name
     * will be an empty string, and the base address will be 0.
     *
     * NOTE: While this function may be called as soon as the moduleId is alive,
     * the AssemblyID of the containing assembly will not be available until the
     * ModuleAttachedToAssembly callback.
     */
    HRESULT GetModuleInfo(
                [in]  ModuleID   moduleId,
                [out] LPCBYTE    *ppBaseLoadAddress,
                [in]  ULONG      cchName,
                [out] ULONG      *pcchName,
                [out, size_is(cchName), length_is(*pcchName)]
                      WCHAR      szName[] ,
                [out] AssemblyID *pAssemblyId);

    /*
     * Get a metadata interface instance which maps to the given module.
     * One may ask for the metadata to be opened in read+write mode, but
     * this will result in slower metadata execution of the program, because
     * changes made to the metadata cannot be optimized as they were from
     * the compiler.
     *
     * NOTE: Some modules (such as resource modules) have no metadata. In
     * those cases, GetModuleMetaData will return S_FALSE, and a NULL
     * IUnknown.
     *
     * NOTE: the only values valid for dwOpenFlags are ofRead and ofWrite.
     */
    HRESULT GetModuleMetaData(
                [in]  ModuleID moduleId,
                [in]  DWORD    dwOpenFlags,
                [in]  REFIID   riid,
                [out] IUnknown **ppOut);

    /*
     * Retrieve a pointer to the body of a method starting at it's header.
     * A method is scoped by the module it lives in.  Because this function
     * is designed to give a tool access to IL before it has been loaded
     * by the Runtime, it uses the metadata token of the method to find
     * the instance desired.
     *
     * GetILFunctionBody can return CORPROF_E_FUNCTION_NOT_IL if the methodId
     * points to a method without any IL (such as an abstract method, or a
     * P/Invoke method).
     */
    HRESULT GetILFunctionBody(
                [in]  ModuleID    moduleId,
                [in]  mdMethodDef methodId,
                [out] LPCBYTE     *ppMethodHeader,
                [out] ULONG       *pcbMethodSize);

    /*
     * IL method bodies must be located as RVA's to the loaded module, which
     * means they come after the module within 4 gb.  In order to make it
     * easier for a tool to swap out the body of a method, this allocator
     * will ensure memory is allocated within that range.
     */
    HRESULT GetILFunctionBodyAllocator(
                [in]  ModuleID      moduleId,
                [out] IMethodMalloc **ppMalloc);

    /*
     * Replaces the method body for a function in a module.  This will replace
     * the RVA of the method in the metadata to point to this new method body,
     * and adjust any internal data structures as required.  This function can
     * only be called on those methods which have never been compiled by a JITTER.
     * Please use the GetILFunctionAllocator to allocate space for the new method to
     * ensure the buffer is compatible.
     */
    HRESULT SetILFunctionBody(
                [in] ModuleID    moduleId,
                [in] mdMethodDef methodid,
                [in] LPCBYTE     pbNewILMethodHeader);

    /*
     * Retrieve app domain information given its id.
     */
    HRESULT GetAppDomainInfo(
                [in]  AppDomainID appDomainId,
                [in]  ULONG       cchName,
                [out] ULONG       *pcchName,
                [out, size_is(cchName), length_is(*pcchName)]
                      WCHAR       szName[] ,
                [out] ProcessID   *pProcessId);

    /*
     * Retrieve information about an assembly given its ID.
     */
    HRESULT GetAssemblyInfo(
                [in]  AssemblyID  assemblyId,
                [in]  ULONG       cchName,
                [out] ULONG       *pcchName,
                [out, size_is(cchName), length_is(*pcchName)]
                      WCHAR       szName[] ,
                [out] AppDomainID *pAppDomainId,
                [out] ModuleID    *pModuleId);


    /*
     * V2 MIGRATION WARNING: DEPRECATED.  Returns E_NOTIMPL always.
     *
     * Marks a function as requiring a re-JIT.  The function will be re-JITted
     * at its next invocation.  The normal profiller events will give the profiller
     * an opportunity to replace the IL prior to the JIT.  By this means, a tool
     * can effectively replace a function at runtime.  Note that active instances
     * of the function are not affected by the replacement.
     *
     * NOTE: memory used by the current jitted code for this method will not be
     *       released, as it may currently be in use by one or more threads and
     *       may have associated data on the stack.
     */
    HRESULT SetFunctionReJIT(
                [in] FunctionID functionId);

    /*
     * ForceGC forces a GC to occur within the runtime.
     *
     * NOTE: This method needs to be called from a thread that does not have any
     * profiler callbacks on its stack. The most convenient way to implement this is
     * to create a separate thread within the profiler and have it call ForceGC when
     * signalled.
     */
    HRESULT ForceGC();

    /*
     *
     * V2 MIGRATION NOTE - Calling SetILInstrumentedCodeMap on any one
     * of the multiple FunctionIDs that represent a generic function in a given
     * AppDomain will affect all instantiations of that function in the AppDomain.
     *
     * fStartJit should be set to true the first time this function is called for
     * a given FunctionID, and false thereafter.
     *
     * The format of the map is as follows:
     *      The debugger will assume that each oldOffset refers to an IL offset
     *  within the original, unmodified IL code.  newOffset refers to the corresponding
     *  IL offset within the new, instrumented code.
     *
     * The map should be sorted in increasing order. For stepping to work properly:
     * - Instrumented IL should not be reordered (so both old & new are sorted)
     * - original IL should not be removed
     * - the map should include entries to map all of the sequence points from the pdb.
     *
     * The map does not interpolate missing entries. So given the following map:
     * (0 old, 0  new)
     * (5 old, 10 new)
     * (9 old, 20 new)
     * - An old offset of 0,1,2,3,4 will be mapped to a new offset of 0
     * - An old offset of 5,6,7, or 8 will be mapped to new offset 10.
     * - An old offset of 9 or higher will be mapped to new offset 20.
     * - A new offset of 0, 1,...8,9 will be mapped to old offset 0
     * - A new offset of 10,11,...18,19 will be mapped to old offset 5.
     * - A new offset of 20 or higher will be mapped to old offset 9.
     *
     */
    HRESULT SetILInstrumentedCodeMap(
                [in]                         FunctionID functionId,
                [in]                         BOOL       fStartJit,
                [in]                         ULONG      cILMapEntries,
                [in, size_is(cILMapEntries)] COR_IL_MAP rgILMapEntries[] );

    /*
     * DEPRECATED.
     */
    HRESULT GetInprocInspectionInterface(
                [out] IUnknown **ppicd);

    /*
     * DEPRECATED.
     */
    HRESULT GetInprocInspectionIThisThread(
                [out] IUnknown **ppicd);

    /*
     * This will return the ContextID currently associated with the calling
     * runtime thread.  This will set pContextId to NULL if the calling thread
     * is not a runtime thread.
     */
    HRESULT GetThreadContext(
                [in]  ThreadID  threadId,
                [out] ContextID *pContextId);

    /*
     * DEPRECATED.
     */
    HRESULT BeginInprocDebugging(
                [in]  BOOL   fThisThreadOnly,
                [out] DWORD *pdwProfilerContext);

    /*
     * DEPRECATED.
     */
    HRESULT EndInprocDebugging(
                [in]  DWORD dwProfilerContext);

    /*
     * GetILToNativeMapping returns a map from IL offsets to native
     * offsets for this code. An array of COR_PROF_IL_TO_NATIVE_MAP
     * structs will be returned, and some of the ilOffsets in this array
     * may be the values specified in CorDebugIlToNativeMappingTypes.
     */
    HRESULT GetILToNativeMapping(
                [in] FunctionID functionId,
                [in] ULONG32 cMap,
                [out] ULONG32 *pcMap,
                [out, size_is(cMap), length_is(*pcMap)]
                    COR_DEBUG_IL_TO_NATIVE_MAP map[]);
}

/*
 * The CLR implements the ICorProfilerInfo2 interface. This interface is
 * used by a code profiler to communicate with the CLR to control event
 * monitoring and request information. The CLR passes an
 * ICorProfilerInfo2 interface to each code profiler during initialization.
 *
 * A code profiler can call methods on the ICorProfilerInfo2 interface to get
  * information about managed code being executed under the control of the CLR
 *
 * The ICorProfilerInfo2 interface implemented by the CLR uses the free
 * threaded model.
 *
 * The methods implemented on this interface return S_OK on success, or E_FAIL
 * on failure.
 *
 */

[
    object,
    uuid(CC0935CD-A518-487d-B0BB-A93214E65478),
    pointer_default(unique),
    local
]
interface ICorProfilerInfo2 : ICorProfilerInfo
{

    /*
     * The code profiler calls DoStackSnapshot to do sparse one-off stack snapshots.
     *
     * Passing NULL for thread yields a snapshot of the current thread. If a ThreadID
     * of a different thread is passed, the runtime will suspend that thread, perform
     * the snapshot, and resume.
     *
     * infoFlags come from the COR_PRF_SNAPSHOT_INFO enum.
     *
     * context is a platform-dependent CONTEXT structure, representing the complete
     * register context that the profiling API will use to seed the stack walk.  If this
     * is non-NULL, it must point to JITd or NGENd code, or else DoStackSnapshot
     * will return CORPROF_E_STACKSNAPSHOT_UNMANAGED_CTX.  Contexts are
     * only provided by profilers that hijack threads to force them to walk their
     * own stacks; profilers should not attempt to provide a context when walking
     * another thread's stack. If context is NULL, the stack walk will begin at the 
     * last available managed frame for the target thread.
     *
     * See the definition of StackSnapshotCallback for more information.
     */
    HRESULT DoStackSnapshot(
                [in] ThreadID thread,
                [in] StackSnapshotCallback *callback,
                [in] ULONG32 infoFlags,
                [in] void *clientData,
                [in, size_is(contextSize), length_is(contextSize)] BYTE context[],
                [in] ULONG32 contextSize);

    /*
     * The code profiler calls SetFunctionHooks2 to specify handlers
     * for FunctionEnter2, FunctionLeave2, and FunctionTailcall2
     * callbacks.
     *
     * Note that only one set of callbacks may be active at a time. Thus,
     * if a profiler calls both SetEnterLeaveFunctionHooks and
     * SetEnterLeaveFunctionHooks2, then SetEnterLeaveFunctionHooks2
     * wins.
     *
     * Each pointer may be null to disable that particular callback.
     *
     * SetEnterLeaveFunctionHooks2 may only be called from the
     * profiler's Initialize() callback.
     */
    HRESULT SetEnterLeaveFunctionHooks2(
                [in] FunctionEnter2    *pFuncEnter,
                [in] FunctionLeave2    *pFuncLeave,
                [in] FunctionTailcall2 *pFuncTailcall);

    /*
     * GetFunctionInfo2 returns the parent class of a function, plus the
     * function's metadata token and the ClassIDs of its type arguments
     * (if any). 
     *
     * When a COR_PRF_FRAME_INFO obtained from a FunctionEnter2
     * callback is passed, the ClassID and all type arguments will be exact.
     *
     * When a COR_PRF_FRAME_INFO from any other source is passed, or 
     * when 0 is passed as the frameInfo argument, exact ClassID and type 
     * arguments cannot always be determined.  The value returned in pClassId 
     * may be NULL and some type args will come back as System.Object.
     *
     */
    HRESULT GetFunctionInfo2(
                [in] FunctionID funcId,
                [in] COR_PRF_FRAME_INFO frameInfo,
                [out] ClassID *pClassId,
                [out] ModuleID *pModuleId,
                [out] mdToken *pToken,
                [in] ULONG32 cTypeArgs,
                [out] ULONG32 *pcTypeArgs,
                [out] ClassID typeArgs[]);

    /*
     * GetStringLayout returns detailed information about how string objects are stored.
     *
     * *pBufferLengthOffset is the offset (from the ObjectID pointer) to a DWORD that
     * stores the length of the string's buffer
     *
     * *pStringLengthOffset is the offset (from the ObjectID pointer) to a DWORD that
     * stores the length of the string itself
     *
     * *pBufferOffset is the offset (from the ObjectID pointer) to the actual buffer
     * of wide characters
     *
     * Strings may or may not be null-terminated.
     */
    HRESULT GetStringLayout(
                [out] ULONG *pBufferLengthOffset,
                [out] ULONG *pStringLengthOffset,
                [out] ULONG *pBufferOffset);

    /*
     * GetClassLayout returns detailed information how a specific class is stored.
     * It only returns the fields defined by the class itself; if the parent class
     * defined fields as well, the profiler must call GetClassLayout on the parent class
     * to obtain those fields.
     *
     * Though it will not fail, the data returned for array and string classes will
     * not be correct.
     */
    HRESULT GetClassLayout(
                [in]  ClassID classID,
                [in, out] COR_FIELD_OFFSET rFieldOffset[],
                [in] ULONG cFieldOffset,
                [out] ULONG *pcFieldOffset,
                [out] ULONG *pulClassSize);

    /*
     * Returns the parent module a class is defined in, along with the
     * metadata token for the class, the ClassID of its parent class, and the
     * ClassIDs of its type arguments (if any).
     *
     * One can call GetModuleMetaData to obtain the metadata interface for
     * a given module.  The token can then be used to access the metadata for this
     * class.
     */
    HRESULT GetClassIDInfo2(
                [in] ClassID classId,
                [out] ModuleID *pModuleId,
                [out] mdTypeDef *pTypeDefToken,
                [out] ClassID *pParentClassId,
                [in] ULONG32 cNumTypeArgs,
                [out] ULONG32 *pcNumTypeArgs,
                [out] ClassID typeArgs[]);

    /*
     * GetCodeInfo2 returns the extents of native code associated with the
     * given FunctionID. These extents are returned sorted in order of increasing
     * IL offset.
     */
    HRESULT GetCodeInfo2(
                [in] FunctionID functionID,
                [in] ULONG32 cCodeInfos,
                [out] ULONG32 *pcCodeInfos,
                [out, size_is(cCodeInfos), length_is(*pcCodeInfos)]
                COR_PRF_CODE_INFO codeInfos[]);

    /*
     * GetClassFromTokenAndTypeArgs returns the ClassID of a type given its metadata
     * token (typedef) and the ClassIDs of its type arguments (if any).
     *
     *      cTypeArgs must be equal to the number of type parameters for the given type
     *          (0 for non-generic types)
     *      typeArgs may be NULL if cTypeArgs == 0
     *
     * Calling this function with a TypeRef token can have unpredictable results; callers
     * should resolve the TypeRef to a TypeDef and use that.
     *
     * If the type is not already loaded, calling this function will cause it to be. 
     * Loading is a dangerous operation in many contexts. For example, calling
     * this function during loading of modules or other types could lead to an infinite
     * loop as the runtime attempts to circularly load things.
     *
     * In general, use of this function is discouraged. If profilers are interested in
     * events for a particular type, they should store the ModuleID and TypeDef of that type,
     * and use GetClassIDInfo2 to check whether a given ClassID is the desired type.
     */
    HRESULT GetClassFromTokenAndTypeArgs(
                    [in] ModuleID moduleID,
                    [in] mdTypeDef typeDef,
                    [in] ULONG32 cTypeArgs,
                    [in, size_is(cTypeArgs)] ClassID typeArgs[],
                    [out] ClassID* pClassID);

    /*
     * GetFunctionFromTokenAndTypeArgs returns the FunctionID of a function given
     * its metadata token (methoddef), containing class, and type args (if any).
     *
     *      classID may be 0 if the containing class is not generic
     *      typeArgs may be NULL if cTypeArgs == 0
     *
     * Calling this function with a MethodRef token can have unpredictable results; callers
     * should resolve the MethodRef to a MethodDef and use that.
     *
     * If the function is not already loaded, calling this function will cause it to be. 
     * Loading is a dangerous operation in many contexts. For example, calling
     * this function during loading of modules or types could lead to an infinite
     * loop as the runtime attempts to circularly load things.
     *
     * In general, use of this function is discouraged. If profilers are interested in
     * events for a particular function, they should store the ModuleID and MethodDef of that function,
     * and use GetFunctionInfo2 to check whether a given FunctionID is the desired function.
     */
    HRESULT GetFunctionFromTokenAndTypeArgs(
                    [in] ModuleID moduleID,
                    [in] mdMethodDef funcDef,
                    [in] ClassID classId,
                    [in] ULONG32 cTypeArgs,
                    [in, size_is(cTypeArgs)] ClassID typeArgs[],
                    [out] FunctionID* pFunctionID);

    /*
     * Returns an enumerator over all frozen objects in the given module.
     */
    HRESULT EnumModuleFrozenObjects(
                [in] ModuleID moduleID,
                [out] ICorProfilerObjectEnum** ppEnum);



    /*
     * GetArrayObjectInfo returns detailed information about an array object.
     * objectId is a valid array object.
     * cDimensions is the rank (# of dimensions).
     * On success:
     *   pDimensionSizes, pDimensionLowerBounds are parallel arrays describing the size and lower bound for each dimension.
     *   (*ppData) is a pointer to the raw buffer for the array, which is laid out according to the C++
     *   convention
     */
    HRESULT GetArrayObjectInfo(
                    [in] ObjectID objectId,
                    [in] ULONG32 cDimensions,
                    [out, size_is(cDimensions), length_is(cDimensions)] ULONG32 pDimensionSizes[],
                    [out, size_is(cDimensions), length_is(cDimensions)] int pDimensionLowerBounds[],
                    [out] BYTE **ppData);

    /*
     * GetBoxClassLayout returns information about how a particular value type is laid out
     * when boxed.
     *
     *  *pBufferOffset is the offset (from the ObjectID pointer) to where the value type
     *  is stored within the box. The value type's class layout may then be used to
     *  interpret it.
     */
    HRESULT GetBoxClassLayout(
                    [in] ClassID classId,
                    [out] ULONG32 *pBufferOffset);


    /*
     * GetThreadAppDomain returns the AppDomainID currently associated with\
     * the given ThreadID
     */
    HRESULT GetThreadAppDomain(
                    [in] ThreadID threadId,
                    [out] AppDomainID *pAppDomainId);


    /*
     * GetRVAStaticAddress gets the address of the home for the given
     * RVA static. 
     */
    HRESULT GetRVAStaticAddress(
                    [in] ClassID classId,
                    [in] mdFieldDef fieldToken,
                    [out] void **ppAddress);

    /*
     * GetAppDomainStaticAddress gets the address of the home for the given
     * AppDomain static in the given AppDomain.
     *
     * This function may return CORPROF_E_DATAINCOMPLETE if the given static
     * has not been assigned a home in the given AppDomain.
     */
    HRESULT GetAppDomainStaticAddress(
                    [in] ClassID classId,
                    [in] mdFieldDef fieldToken,
                    [in] AppDomainID appDomainId,
                    [out] void **ppAddress);

    /*
     * GetThreadStaticAddress gets the address of the home for the given
     * Thread static in the given Thread.
     *
     * This function may return CORPROF_E_DATAINCOMPLETE if the given static
     * has not been assigned a home in the given Thread.
     */
    HRESULT GetThreadStaticAddress(
                    [in] ClassID classId,
                    [in] mdFieldDef fieldToken,
                    [in] ThreadID threadId,
                    [out] void **ppAddress);

    /*
     * GetContextStaticAddress gets the address of the home for the given
     * Context static in the given context.
     *
     * This function may return CORPROF_E_DATAINCOMPLETE if the given static
     * has not been assigned a home in the given Context.
     */
    HRESULT GetContextStaticAddress(
                    [in] ClassID classId,
                    [in] mdFieldDef fieldToken,
                    [in] ContextID contextId,
                    [out] void **ppAddress);

    /*
     * GetStaticFieldInfo gets COR_PRF_STATIC_TYPE for a specific
     * field in a class. This information can be used to decide which
     * function to call to get the address of the static.
     *
     * NOTE: One should still check the metadata for a static to ensure
     * it is actually going to have an address. Statics that are literals
     * (aka constants) exist only in the metadata and do not have an address.
     *
     */
    HRESULT GetStaticFieldInfo(
                    [in] ClassID classId,
                    [in] mdFieldDef fieldToken,
                    [out] COR_PRF_STATIC_TYPE *pFieldInfo);

    /*
     * GetGenerationBounds returns the memory regions that make up a given
     * GC generation in memory. It may be called from any profiler callback as long
     * as a GC is not in progress. (To be exact, it may be called from any callback
     * except for those that occur between GarbageCollectionStarted and GarbageCollectionFinished.)
     *
     * Most shifting of generations takes place during garbage collections; between
     * collections generations may grow, but generally do not move around. Therefore
     * the most interesting places to call this function are in GarbageCollectionStarted
     * and Finished.
     *
     * During program startup, some objects are allocated by the CLR itself, generally
     * in generations 3 and 0. So by the time managed code starts executing, these
     * generations will already contain objects. Generations 1 and 2 will be normally
     * empty, except for dummy objects generated by the garbage collector (of size 12
     * bytes in 32-bit implementations of the CLR, larger in 64-bit implementaions).
     * You may also see generation 2 ranges that are inside modules generated by ngen.
     * These are "frozen objects" generated at ngen time rather than allocated by the
     * garbage collector.
     *
     * cObjectRanges is a count of the number of elements allocated by the caller for
     *      the ranges array
     * pcObjectRanges is an out param for the number of ranges in the given generation
     * ranges is an array of elements of type COR_PRF_GC_GENERATION_RANGE, each of which
     *      describes a range of memory used by the garbage collector
     */

    HRESULT GetGenerationBounds(
                    [in] ULONG cObjectRanges,
                    [out] ULONG *pcObjectRanges,
                    [out, size_is(cObjectRanges), length_is(*pcObjectRanges)] COR_PRF_GC_GENERATION_RANGE ranges[]);
 
    /*
     * GetObjectGeneration returns which generation the given object is currently in, along
     * with the start and length of the segment containing the object. It may be called
     * at any time as long as a GC is not in progress.
     */

    HRESULT GetObjectGeneration(
                    [in] ObjectID objectId,
                    [out] COR_PRF_GC_GENERATION_RANGE *range);


   /*
     * When an exception notification is received, GetNotifiedExceptionClauseInfo() may be used 
     * to get the native address and frame information for the exception clause (catch/finally/filter)
     * that is about to be run (ExceptionCatchEnter, ExceptionUnwindFinallyEnter, ExceptionFilterEnter)
     * or has just been run (ExceptionCatchLeave, ExceptionUnwindFinallyLeave, ExceptionFilterLeave).  
     *
     * This call may be made at any time after one of the Enter calls above until either the matching
     * Leave call is received or until a nested exception throws out of the current clause in which case
     * there will be no Leave notification for that clause.  Note it is not possible for a throw to escape 
     * a Filter so there is always a Leave in that case.
     *
     * Return values:
     *   S_OK indicates success
     *   S_FALSE indicates that no exception clause is active   
     *   CORPROF_E_NOT_MANAGED_THREAD indicates an unmanaged thread.    
     */

    HRESULT GetNotifiedExceptionClauseInfo(
                    [out] COR_PRF_EX_CLAUSE_INFO *pinfo);                 
}

/*
 * This interface lets you iterate over the frozen objects from ngen images.
 */

[
    object,
    uuid(2C6269BD-2D13-4321-AE12-6686365FD6AF),
    pointer_default(unique),
    local
]
interface ICorProfilerObjectEnum : IUnknown
{
    HRESULT Skip(
                [in] ULONG celt);
        
    HRESULT Reset();
    
    HRESULT Clone(
                    [out] ICorProfilerObjectEnum **ppEnum);
                    
    HRESULT GetCount(
                    [out] ULONG *pcelt);

    HRESULT Next(
                    [in] ULONG celt,
                    [out, size_is(celt), length_is(*pceltFetched)]  ObjectID objects[],
                    [out] ULONG *pceltFetched);
}

/*
 * This is simple allocator that only allows you to allocate memory.
 * You may not free it.  This should be used in conjunction with
 * SetILFunctionBody.
 */
[
    object,
    uuid(A0EFB28B-6EE2-4d7b-B983-A75EF7BEEDB8),
    pointer_default(unique),
    local
]
interface IMethodMalloc : IUnknown
{
    /*
     * Tries to allocate memory above the start address of the module from
     * which it was created.  It is important to note that this method may
     * fail to allocate the memory specified above the start address, and
     * may as a result return NULL.
     */
    PVOID Alloc(
                    [in] ULONG cb);
}
