path: root/src/inc/clrinternal.idl

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

/**************************************************************************************
 **                                                                                  **
 ** clrinternal.idl - interface definitions for internal usage.                      **
 **                                                                                  **
 **************************************************************************************/

//
// Interface descriptions
//
import "unknwn.idl";

// import mscoree.idl for BucketParameters definition
import "mscoree.idl";

#ifndef FEATURE_CORECLR
import "hstring.idl";
#endif //!FEATURE_CORECLR

#ifndef FEATURE_CORECLR
interface IActivationFactory;
cpp_quote("interface IActivationFactory;")

interface IWinRTClassActivator;
cpp_quote("interface IWinRTClassActivator;")
#endif //!FEATURE_CORECLR

cpp_quote("#if 0")

typedef struct _OSVERSIONINFOA {
    DWORD dwOSVersionInfoSize;
    DWORD dwMajorVersion;
    DWORD dwMinorVersion;
    DWORD dwBuildNumber;
    DWORD dwPlatformId;
    CHAR   szCSDVersion[ 128 ];     // Maintenance string for PSS usage
} OSVERSIONINFOA, *POSVERSIONINFOA, *LPOSVERSIONINFOA;

typedef struct _OSVERSIONINFOW {
    DWORD dwOSVersionInfoSize;
    DWORD dwMajorVersion;
    DWORD dwMinorVersion;
    DWORD dwBuildNumber;
    DWORD dwPlatformId;
    WCHAR  szCSDVersion[ 128 ];     // Maintenance string for PSS usage
} OSVERSIONINFOW, *POSVERSIONINFOW, *LPOSVERSIONINFOW, RTL_OSVERSIONINFOW, *PRTL_OSVERSIONINFOW;
#ifdef UNICODE
typedef OSVERSIONINFOW OSVERSIONINFO;
typedef POSVERSIONINFOW POSVERSIONINFO;
typedef LPOSVERSIONINFOW LPOSVERSIONINFO;
#else
typedef OSVERSIONINFOA OSVERSIONINFO;
typedef POSVERSIONINFOA POSVERSIONINFO;
typedef LPOSVERSIONINFOA LPOSVERSIONINFO;
#endif // UNICODE

cpp_quote("#endif")

// IID IExecutionEngine :     uuid(7AF02DAC-2A33-494b-A09F-25E00A93C6F8)
cpp_quote("EXTERN_GUID(IID_IExecutionEngine, 0x7AF02DAC, 0x2A33, 0x494b, 0xA0, 0x9F, 0x25, 0xE0, 0x0A, 0x93, 0xC6, 0xF8);")

// IID IEEMemoryManager :     uuid{17713B61-B59F-4e13-BAAF-91623DC8ADC0}
cpp_quote("EXTERN_GUID(IID_IEEMemoryManager, 0x17713b61, 0xb59f, 0x4e13, 0xba, 0xaf, 0x91, 0x62, 0x3d, 0xc8, 0xad, 0xc0);")

// This ID is embedded in the CLRDEBUGINFO resource so that the shim can differentiate dlls which happen to be named
// clr.dll from official Microsoft clr.dll implementations. This is not intended to authenticate a CLR in a strong
// security sense but short of deliberate 3rd party spoofing it should provide a good identity.
//
// Using a different ID allows us to completely hide different CLR SKUs from each other. The recommendation is to keep
// the ID contant between different versions of the same SKU and use mscordbi's logic to determine whether a given
// version is compatible. This allows debuggers to give different errors for 'future version of the CLR I don't
// support' vs. 'No CLR is loaded at all.' 
// 
// This guid first appears in version 4.0 of CLR on x86 and amd64 - earlier versions had no resource
// GUID CLR_ID_V4_DESKTOP :   uuid{267F3989-D786-4b9a-9AF6-D19E42D557EC}
cpp_quote("EXTERN_GUID(CLR_ID_V4_DESKTOP, 0x267f3989, 0xd786, 0x4b9a, 0x9a, 0xf6, 0xd1, 0x9e, 0x42, 0xd5, 0x57, 0xec);")

// This guid has been set aside for CoreCLR usage - at present CoreCLR doesn't use it though
// GUID CLR_ID_CORECLR :   uuid{8CB8E075-0A91-408E-9228-D66E00A3BFF6}
cpp_quote("EXTERN_GUID(CLR_ID_CORECLR, 0x8CB8E075, 0x0A91, 0x408E, 0x92, 0x28, 0xD6, 0x6E, 0x00, 0xA3, 0xBF, 0xF6 );")

// This guid first appears in the CoreCLR port to Windows Phone 8 - note that it is seperate from the CoreCLR id because it will
// potentially have a different verioning lineage than CoreCLR
// GUID CLR_ID_PHONE_CLR :   uuid{E7237E9C-31C0-488C-AD48-324D3E7ED92A}
cpp_quote("EXTERN_GUID(CLR_ID_PHONE_CLR, 0xE7237E9C, 0x31C0, 0x488C, 0xAD, 0x48, 0x32, 0x4D, 0x3E, 0x7E, 0xD9, 0x2A);")

// This guid first appears 8/19/14 as CoreCLR evolves to OneCore, ProjectK, and versions of Phone after PhoneBlue
// The new guid intentionally creates a breaking change so we can simplify the file naming on mscordaccore.dll and mscordbi.dll
// in xplat hosting scenarios. Old versions of dbgshim.dll will not be able to support this.
// GUID CLR_ID_ONECORE_CLR :    uuid{B1EE760D-6C4A-4533-BA41-6F4F661FABAF}
cpp_quote("EXTERN_GUID(CLR_ID_ONECORE_CLR, 0xb1ee760d, 0x6c4a, 0x4533, 0xba, 0x41, 0x6f, 0x4f, 0x66, 0x1f, 0xab, 0xaf);")


// IID_IPrivateManagedExceptionReporting :     uuid{AD76A023-332D-4298-8001-07AA9350DCA4}
cpp_quote("EXTERN_GUID(IID_IPrivateManagedExceptionReporting, 0xad76a023, 0x332d, 0x4298, 0x80, 0x01, 0x07, 0xaa, 0x93, 0x50, 0xdc, 0xa4);")

#ifndef FEATURE_CORECLR
// CLSID CLRRuntimeHostInternal :    uuid(f7721072-bf57-476d-89f8-a7625d27683a)
cpp_quote("EXTERN_GUID(CLSID_CLRRuntimeHostInternal, 0xf7721072, 0xbf57, 0x476d, 0x89, 0xf8, 0xa7, 0x62, 0x5d, 0x27, 0x68, 0x3a);")
// IID ICLRRuntimeHostInternal :     uuid{07C4E752-3CBA-4A07-9943-B5F206382178}
cpp_quote("EXTERN_GUID(IID_ICLRRuntimeHostInternal, 0x07c4e752, 0x3cba, 0x4a07, 0x99, 0x43, 0xb5, 0xf2, 0x06, 0x38, 0x21, 0x78);")

// CLSID_CLRShimControlInternal : uuid(62D02A5B-F527-44d8-80BC-650BBD3CB082)
cpp_quote("EXTERN_GUID(CLSID_CLRShimControlInternal, 0x62d02a5b, 0xf527, 0x44d8, 0x80, 0xbc, 0x65, 0xb, 0xbd, 0x3c, 0xb0, 0x82);")

// IID ICLRShimControlInternal :     uuid{826AAAD7-717B-44f8-9BB0-7DAC368B85A5}
cpp_quote("EXTERN_GUID(IID_ICLRShimControlInternal, 0x826AAAD7, 0x717b, 0x44f8, 0x9b, 0xb0, 0x7d, 0xac, 0x36, 0x8b, 0x85, 0xa5);")

// CLSID_CLRActivationFactory :     uuid{5B132A7D-DA8E-461b-A0F2-109141C768CB}
cpp_quote("EXTERN_GUID(CLSID_CLRActivationFactory, 0x5b132a7d, 0xda8e, 0x461b, 0xa0, 0xf2, 0x10, 0x91, 0x41, 0xc7, 0x68, 0xcb );")

// IID_ICLRActivationFactory :     uuid{331F2F6C-385F-462c-9125-816712FB2BC6}
cpp_quote("EXTERN_GUID(IID_ICLRActivationFactory, 0x331f2f6c, 0x385f, 0x462c, 0x91, 0x25, 0x81, 0x67, 0x12, 0xfb, 0x2b, 0xc6);")

// IID_ICLRActivationFactory2 :    uuid{035049E5-2658-40C0-9269-21C48D8F0748}
cpp_quote("EXTERN_GUID(IID_ICLRActivationFactory2, 0x035049E5, 0x2658, 0x40C0, 0x92, 0x69, 0x21, 0xC4, 0x8D, 0x8F, 0x07, 0x48);")

// IID IID_ICLRExecutionManager: uuid(1000A3E7-B420-4620-AE30-FB19B587AD1D)
cpp_quote("EXTERN_GUID(IID_ICLRExecutionManager, 0x1000A3E7, 0xB420, 0x4620, 0xAE, 0x30, 0xFB, 0x19, 0xB5, 0x87, 0xAD, 0x1D);")
#endif // !FEATURE_CORECLR

//*****************************************************************************
// Interface for exposing services from the EE to other DLLs of the CLR.
//*****************************************************************************
typedef void * CRITSEC_COOKIE;
typedef void * EVENT_COOKIE;
typedef void * SEMAPHORE_COOKIE;
typedef void * MUTEX_COOKIE;

typedef enum {
    CRST_DEFAULT          = 0x0,
    CRST_REENTRANCY       = 0x1,  // allow same thread to take lock multiple times.
    CRST_UNSAFE_SAMELEVEL = 0x2,  // AVOID THIS! Can take other locks @ same level in
                                  //             any order.
    CRST_UNSAFE_COOPGC    = 0x4,  // AVOID THIS! Lock must be taken in cooperative mode.
    CRST_UNSAFE_ANYMODE   = 0x8,  // AVOID THIS! Lock can be taken in either GC mode.
    CRST_DEBUGGER_THREAD  = 0x10, // This lock can be taken on the debugger's helper thread.
    CRST_HOST_BREAKABLE   = 0x20, // This lock is held while running managed code.  It can be terminated by a host.
    // CRST_UNUSED        = 0x40,
    CRST_TAKEN_DURING_SHUTDOWN = 0x80, // This lock is taken during the shutdown sequence in EEShutdown(helper)
    CRST_GC_NOTRIGGER_WHEN_TAKEN = 0x100, 
        // User of this lock cannot trigger GC, while it is locked.
        // Note that Enter on this lock can trigger GC if called from COOPERATIVE mode.
        // It is useful for locks which can be taken on GC or debugger threads.
    CRST_DEBUG_ONLY_CHECK_FORBID_SUSPEND_THREAD = 0x200,
        // Some rare locks should be taken only in ForbidSuspend region (i.e. profiler cannot walk the stack), 
        // this option will assert it in debug mode.
} CrstFlags;

// Callback function for cleaning up TLS
typedef VOID (__stdcall *PTLS_CALLBACK_FUNCTION)(PVOID);


[
    uuid(7AF02DAC-2A33-494b-A09F-25E00A93C6F8),
    helpstring("CLR Coordination Interface"),
    pointer_default(unique),
    local
]
interface IExecutionEngine : IUnknown
{
    // Thread Local Storage is based on logical threads.  The underlying
    // implementation could be threads, fibers, or something more exotic.
    // Slot numbers are predefined.  This is not a general extensibility
    // mechanism.

    // Associate a callback function for releasing TLS on thread/fiber death.
    // This can be NULL.
    void TLS_AssociateCallback([in] DWORD slot, [in] PTLS_CALLBACK_FUNCTION callback);

    // Get the TLS block for fast Get/Set operations
    PVOID* TLS_GetDataBlock();

    // Get the value at a slot
    PVOID TLS_GetValue([in] DWORD slot);

    // Get the value at a slot, return FALSE if TLS info block doesn't exist
    BOOL TLS_CheckValue([in] DWORD slot, [out] PVOID * pValue);

    // Set the value at a slot
    void TLS_SetValue([in] DWORD slot, [in] PVOID pData);

    // Free TLS memory block and make callback
    void TLS_ThreadDetaching();

    // Critical Sections are sometimes exposed to the host and therefore need to be
    // reflected from all CLR DLLs to the EE.
    //
    // In addition, we always monitor interactions between the lock & the GC, based
    // on the GC mode in which the lock is acquired and we restrict what operations
    // are permitted while holding the lock based on this.
    //
    // Finally, we we rank all our locks to prevent deadlock across all the DLLs of
    // the CLR.  This is the level argument to CreateLock.
    //
    // All usage of these locks must be exception-safe.  To achieve this, we suggest
    // using Holders (see holder.h & crst.h).  In fact, within the EE code cannot
    // hold locks except by using exception-safe holders.

    CRITSEC_COOKIE CreateLock([in] LPCSTR szTag, [in] LPCSTR level, [in] CrstFlags flags);

    void DestroyLock([in] CRITSEC_COOKIE lock);

    void AcquireLock([in] CRITSEC_COOKIE lock);

    void ReleaseLock([in] CRITSEC_COOKIE lock);

    EVENT_COOKIE CreateAutoEvent([in] BOOL bInitialState);
    EVENT_COOKIE CreateManualEvent([in] BOOL bInitialState);
    void CloseEvent([in] EVENT_COOKIE event);
    BOOL ClrSetEvent([in] EVENT_COOKIE event);
    BOOL ClrResetEvent([in] EVENT_COOKIE event);
    DWORD WaitForEvent([in] EVENT_COOKIE event, [in] DWORD dwMilliseconds, [in] BOOL bAlertable);
    DWORD WaitForSingleObject([in] HANDLE handle, [in] DWORD dwMilliseconds);

    // OS header file defines CreateSemaphore.
    SEMAPHORE_COOKIE ClrCreateSemaphore([in] DWORD dwInitial, [in] DWORD dwMax);
    void ClrCloseSemaphore([in] SEMAPHORE_COOKIE semaphore);
    DWORD ClrWaitForSemaphore([in] SEMAPHORE_COOKIE semaphore, [in] DWORD dwMilliseconds, [in] BOOL bAlertable);
    BOOL ClrReleaseSemaphore([in] SEMAPHORE_COOKIE semaphore, [in] LONG lReleaseCount, [in] LONG *lpPreviousCount);

    MUTEX_COOKIE ClrCreateMutex([in]LPSECURITY_ATTRIBUTES lpMutexAttributes, [in]BOOL bInitialOwner, [in]LPCTSTR lpName);
    DWORD ClrWaitForMutex([in] MUTEX_COOKIE mutex, [in] DWORD dwMilliseconds, [in] BOOL bAlertable);
    BOOL ClrReleaseMutex([in] MUTEX_COOKIE mutex);
    void ClrCloseMutex([in] MUTEX_COOKIE mutex);

    DWORD ClrSleepEx([in] DWORD dwMilliseconds, [in] BOOL bAlertable);

    BOOL ClrAllocationDisallowed();

    void GetLastThrownObjectExceptionFromThread([out] void **ppvException);

};  // interface IExecutionEngine


//*****************************************************************************
// Interface for exposing memory services from the EE to other DLLs of the CLR.
//*****************************************************************************

cpp_quote("#if !defined(_WINNT_) && !defined(_NTMMAPI_)")
typedef void* PMEMORY_BASIC_INFORMATION;
cpp_quote("#endif")


[
    uuid(17713B61-B59F-4e13-BAAF-91623DC8ADC0),
    helpstring("CLR Memory Manager Interface"),
    pointer_default(unique),
    local
]
interface IEEMemoryManager : IUnknown
{
    LPVOID ClrVirtualAlloc(
        [in] LPVOID lpAddress,        // region to reserve or commit
        [in] SIZE_T dwSize,           // size of region
        [in] DWORD flAllocationType,  // type of allocation
        [in] DWORD flProtect          // type of access protection
    );

    BOOL ClrVirtualFree(
        [in] LPVOID lpAddress,   // address of region
        [in] SIZE_T dwSize,      // size of region
        [in] DWORD dwFreeType    // operation type
    );

    SIZE_T ClrVirtualQuery(
        [in] const void* lpAddress,                    // address of region
        [in] PMEMORY_BASIC_INFORMATION lpBuffer,  // information buffer
        [in] SIZE_T dwLength                      // size of buffer
    );

    BOOL ClrVirtualProtect(
        [in] LPVOID lpAddress,       // region of committed pages
        [in] SIZE_T dwSize,          // size of the region
        [in] DWORD flNewProtect,     // desired access protection
        [in] DWORD* lpflOldProtect   // old protection
    );

    HANDLE ClrGetProcessHeap();

    HANDLE ClrHeapCreate(
        [in] DWORD flOptions,       // heap allocation attributes
        [in] SIZE_T dwInitialSize,  // initial heap size
        [in] SIZE_T dwMaximumSize   // maximum heap size
    );

    BOOL ClrHeapDestroy(
        [in] HANDLE hHeap   // handle to heap
    );

    LPVOID ClrHeapAlloc(
        [in] HANDLE hHeap,   // handle to private heap block
        [in] DWORD dwFlags,  // heap allocation control
        [in] SIZE_T dwBytes  // number of bytes to allocate
    );

    BOOL ClrHeapFree(
        [in] HANDLE hHeap,  // handle to heap
        [in] DWORD dwFlags, // heap free options
        [in] LPVOID lpMem   // pointer to memory
    );

    BOOL ClrHeapValidate(
        [in] HANDLE hHeap,  // handle to heap
        [in] DWORD dwFlags, // heap access options
        [in] const void* lpMem   // optional pointer to memory block
    );

    HANDLE ClrGetProcessExecutableHeap();

};  // interface IEEMemoryManager

//********************************************************************************************
// Interface for exposing GetBucketParametersForCurrentException to Watson testing harness.
//********************************************************************************************
[
    uuid(AD76A023-332D-4298-8001-07AA9350DCA4),
    helpstring("Private Managed Exception Reporting Interface"),
    pointer_default(unique),
    local
]
interface IPrivateManagedExceptionReporting : IUnknown
{
    HRESULT GetBucketParametersForCurrentException([out]BucketParameters *pParams);
}

#ifndef FEATURE_CORECLR
/**************************************************************************************
 ** ICLRRuntimeHostInternal                                                          **
 ** This is the functionality used only by CLR internal tools that moved from being  **
 ** flat APIs (loading the latest runtime) to something that is runtime-specific and **
 ** requires the runtime to be loaded.                                               **
 **************************************************************************************/
[
    uuid(07C4E752-3CBA-4A07-9943-B5F206382178),
    version(1.0),
    helpstring("CLR internal hosting interface for V4.0"),
    local
]
interface ICLRRuntimeHostInternal : IUnknown
{
    HRESULT MetaDataGetDispenser(
        [in]                        REFCLSID   rclsid, 
        [in]                        REFIID     riid, 
        [out, iid_is(riid), retval] IUnknown **ppInterface);
    
    HRESULT GetAssemblyMDImport(
        [in]                        LPCWSTR    wszFileName, // The scope (file name) to open.
        [in]                        REFIID     riid,        // Desired interface.
        [out, iid_is(riid), retval] IUnknown **ppIUnk);     // Returned interface on success.
    
    HRESULT GetMetaDataInternalInterface(
        [in, size_is(cbData)]       BYTE   *pbData,         // MetaData data.
        [in]                        ULONG   cbData,         // MetaData data size.
        [in]                        DWORD   flags,          // Flags.
        [in]                        REFIID  riid,           // Desired interface.
        [out, iid_is(riid), retval] LPVOID *ppInterface);   // Returned interface.
    
    HRESULT GetMetaDataInternalInterfaceFromPublic(
        [in]                        IUnknown *pInterface,   // Given interface.
        [in]                        REFIID    riid,         // Desired interface.
        [out, iid_is(riid), retval] LPVOID   *ppInterface); // Returned interface.
    
    HRESULT GetMetaDataPublicInterfaceFromInternal(
        [in]                        IUnknown *pInterface,   // Given interface.
        [in]                        REFIID    riid,         // Desired interface.
        [out, iid_is(riid), retval] LPVOID   *ppInterface); // Returned interface.
    
    /**********************************************************************************
     ** Returns the version string that MD emitter should by default write to images.**
     ** Supersedes: GetCORRequiredVersion                                            **
     **********************************************************************************/
    HRESULT GetImageVersionString(
        [out, size_is(*pcchBuffer), annotation("__out_ecount_opt(*pcchBuffer)")] LPWSTR pwzBuffer,       // Returned version string.
        [in, out]                   DWORD *pcchBuffer);     // Buffer size/version length.

    /**********************************************************************************
     ** Locks the given module for this runtime. The HRESULT is S_OK if it is the    **
     ** runtime represented by this instance, S_FALSE if somebody beat us to it.     **
     **********************************************************************************/
    HRESULT LockModuleForRuntime(
        [in]                        BYTE   *pModuleBase,    // Address where the module is mapped.
        [in]                        REFIID  riid,           // Desired interface.
        [out, iid_is(riid)]         LPVOID *ppRuntime);     // The owning runtime.

    /**********************************************************************************
     ** Asks the Shim to attempt a graceful shutdown of all other runtimes loaded    **
     ** in this process, then to exit the process via ::ExitProcess(). V4+ runtimes  **
     ** call this instead of ::ExitProcess().                                        **
     **********************************************************************************/
    HRESULT ShutdownAllRuntimesThenExit(
        [in]                        UINT    exitCode);      // Process exit code.

    /**********************************************************************************
     ** GetTrueOSVersion - Bypasses the OS compatibility shim                        **
     **********************************************************************************/
    HRESULT GetTrueOSVersion(
        [out, in]                    LPOSVERSIONINFO   osvi);     // OS Version.

    /**********************************************************************************
     ** Returns the runtime that a COM component with the given CLSID would be       **
     ** activated in. Returns runtime represented by this instance for Fx types.     **
     **********************************************************************************/
    HRESULT GetRuntimeForManagedCOMObject(
        [in]                        REFCLSID rclsid,            // CLSID of the component.
        [in]                        REFIID   riid,              // Desired runtime interface.
        [out, iid_is(riid), retval] LPVOID  *ppRuntime);        // Returned runtime.
};  // interface ICLRRuntimeHostInternal

/**************************************************************************************
 ** ICLRShimControlInternal                                                          **
 ** This is the functionality used only by CLR internal tools that moved from being  **
 ** flat APIs (loading the latest runtime) to controlshim behavior                   **
 **************************************************************************************/
[
    uuid(826AAAD7-717B-44f8-9BB0-7DAC368B85A5),
    version(1.0),
    helpstring("CLR internal hosting interface for V4.0"),
    local
]
interface ICLRShimControlInternal : IUnknown
{
    HRESULT SetShouldSkipSkuCheck(
        [in]                        BOOL       bValue
        );
};  // interface ICLRRuntimeHostInternal



/**************************************************************************************
 ** ICLRActivationFactory                                                            **
 ** This is the functionality used only by CLR to provide in-proc                    **
 ** hosting                                                                          **
 **************************************************************************************/
[
    uuid(331F2F6C-385F-462c-9125-816712FB2BC6),
    version(1.0),
    helpstring("CLR internal activation factory for V4.5"),
    local
]
interface ICLRActivationFactory : IUnknown
{
    HRESULT CreateFactory([in] LPCWSTR activatableClassId, 
                           [out, retval] IActivationFactory** factory);

};  // interface ICLRActivationFactory

/**************************************************************************************
 ** ICLRActivationFactory2                                                           **
 ** This is functionality exposed by the CLR to enable hosting WinRT components in a **
 ** non-AppX process                                                                 **
 **************************************************************************************/
[
    uuid(035049E5-2658-40C0-9269-21C48D8F0748),
    version(1.0),
    helpstring("CLR internal activation factory for desktop WinRT activation"),
    local
]
interface ICLRActivationFactory2 : ICLRActivationFactory
{
    HRESULT GetClassActivatorForApplication(HSTRING appPath, [out] IWinRTClassActivator** ppActivator);
};

typedef enum 
{
    PAUSE_APP_DOMAINS = 0x1

} PauseFlags;

[
    uuid(1000A3E7-B420-4620-AE30-FB19B587AD1D),
    version(1.0),
    helpstring("Pause and Resume Interface"),
    pointer_default(unique),
    local
]
interface ICLRExecutionManager : IUnknown
{
    // Pause all managed threads
    // Parameters are ignored and reserved for future use.
    HRESULT Pause([in] DWORD dwAppDomainId, [in] DWORD dwFlags);

    // Resume managed threads
    // Parameters are ignored and reserved for future use.
    HRESULT Resume([in] DWORD dwAppDomainId);
}
#endif // !FEATURE_CORECLR