path: root/src/inc/mscorsvc.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.
/* -------------------------------------------------------------------------- *
 * Microsoft .Net Framework Service
 * -------------------------------------------------------------------------- */

#ifndef IN_MSCOREE
cpp_quote("#if 0")  // So that the outputted header file doesn't cause redefines

import "unknwn.idl";

cpp_quote("#endif")

// CLSID_CorSvcWorker
cpp_quote("EXTERN_GUID(CLSID_CorSvcWorker, 0x8ed1a844, 0x32a7, 0x4a67, 0xba, 0x62, 0xf8, 0xd5, 0xaf, 0xdf, 0xf4, 0x60);")

// CLSID_CorSvcBindToWorker
cpp_quote("EXTERN_GUID(CLSID_CorSvcBindToWorker, 0x9f74fb09, 0x4221, 0x40b4, 0xae, 0x21, 0xae, 0xb6, 0xdf, 0xf2, 0x99, 0x4e);")

#pragma midl_echo("STDAPI CorGetSvc(IUnknown **pIUnknown);")

[
    uuid(d69cca64-16f7-485c-8cf1-67063e44f0c3),
    version(2.0),
    helpstring("Common Language Runtime Execution Engine 2.0 Library")
]
library mscorsvc
{
    importlib("stdole32.tlb");

#endif // IN_MSCOREE


    //*****************************************************************************
    // ICorSvcDependencies is used to enumerate the dependencies of an
    // IL image.  It is used by the native image service.
    //*****************************************************************************[

    [
        object,
        oleautomation,
        uuid(ddb34005-9ba3-4025-9554-f00a2df5dbf5),
        pointer_default(unique),
    ]
    interface ICorSvcDependencies : IUnknown
    {
        HRESULT GetAssemblyDependencies(
            [in] BSTR pAssemblyName,
            [out] SAFEARRAY(BSTR) *pDependencies,
            [out] DWORD *assemblyNGenSetting,
            [out] BSTR *pNativeImageIdentity,
            [out] BSTR *pAssemblyDisplayName,
            [out] SAFEARRAY(DWORD) *pDependencyLoadSetting,
            [out] SAFEARRAY(DWORD) *pDependencyNGenSetting
        );
    }

    //*****************************************************************************
    // ICorSvcWorker contains methods for generating native images and enumerating
    // their dependencies.
    //*****************************************************************************[  
    
    typedef enum
    {
        ScenarioDefault              = 0x00000000,  // No special scenario flags
        ScenarioAll                  = 0x00000001,  // All scenarios (used to indicate all configurations)
        ScenarioDebug                = 0x00000002,  // Unoptimized debuggable code
        ScenarioProfile              = 0x00000008,  // Used for profiling (enter/leave notifications)
        ScenarioTuningDataCollection = 0x00000010,  // Used to gather IBC data
        ScenarioLegacy               = 0x00000020,  // Follow hard dependencies only

        ScenarioNgenLastRetry        = 0x00010000,  // Ngen failed last time and this a final retry 
        ScenarioAutoNGen             = 0x00100000,  // This is an Auto NGen request
        ScenarioRepositoryOnly       = 0x00200000,  // Install from repository only, no real NGen
    } OptimizationScenario;

    typedef enum
    {
        ScenarioEmitFixups           = 0x00010000,  // Emit fixups for Vulcan
        ScenarioProfileInfo          = 0x00020000   // Generate a PE section with profile ranges data
    } PrivateOptimizationScenario;

    typedef struct _SvcWorkerPriority
    {
        DWORD dwPriorityClass;
    } SvcWorkerPriority;

    [
        object,
        oleautomation,
        uuid(d1047bc2-67c0-400c-a94c-e64446a67fbe),
        pointer_default(unique),
    ]
    interface ICorSvcWorker : IUnknown
    {
        HRESULT SetPriority(
            [in] SvcWorkerPriority priority
            );

        HRESULT OptimizeAssembly(
            [in] BSTR pAssemblyName, 
            [in] BSTR pApplicationName, 
            [in] OptimizationScenario scenario,
            [in] SAFEARRAY(BSTR) loadAlwaysList,
            [in] SAFEARRAY(BSTR) loadSometimesList,
            [in] SAFEARRAY(BSTR) loadNeverList,
            [out] BSTR *pNativeImageIdentity
            );

        HRESULT DeleteNativeImage(
            [in] BSTR pAssemblyName,
            [in] BSTR pNativeImage
            );
    
        HRESULT DisplayNativeImages(
            [in] BSTR pAssemblyName
            );

        HRESULT GetCorSvcDependencies(
            [in] BSTR pApplicationName,
            [in] OptimizationScenario scenario,
            [out] ICorSvcDependencies **pCorSvcDependencies
            ); 

        HRESULT Stop(
            );
    }

    [
        object,
        oleautomation,
        uuid(f3358a7d-0061-4776-880e-a2f21b9ef93e),
        pointer_default(unique),
    ]
    interface ICorSvcWorker2 : ICorSvcWorker {
        // Create a PDB for the NGEN image that was generated for pAssemblyName
        // when compiled with the given appbase and scenario.
        HRESULT CreatePdb([in] BSTR pAssemblyName, 
                          [in] BSTR pAppBaseOrConfig,
                          [in] OptimizationScenario scenario,
                          [in] BSTR pNativeImagePath,
                          [in] BSTR pPdbPath);
    };
    
    [
        object,
        oleautomation,
        uuid(DC516615-47BE-477e-8B55-C5ABE0D76B8F),
        pointer_default(unique),
    ]
    interface ICorSvcWorker3 : ICorSvcWorker2 {
        // Create a PDB for the NGEN image that was generated for pAssemblyName
        // when compiled with the given appbase and scenario. Optionally include
        // source lines information in the geneated PDB
        HRESULT CreatePdb2([in] BSTR pAssemblyName, 
                           [in] BSTR pAppBaseOrConfig,
                           [in] OptimizationScenario scenario,
                           [in] BSTR pNativeImagePath,
                           [in] BSTR pPdbPath,
                           [in] BOOL pdbLines,
                           [in] BSTR managedPdbSearchPath);
    };

    //*****************************************************************************
    // ICorSvcSetPrivateAttributes sets private attributes that are used just for
    // the initial compilation
    //*****************************************************************************[
    
    typedef enum
    {
        DbgTypePdb               = 0x00000001,  // Generate a pdb for the NGen image
    } NGenPrivateAttributesFlags;

    typedef struct _NGenPrivateAttributes
    {
       DWORD Flags;
       DWORD ZapStats;
       BSTR  DbgDir;
    } NGenPrivateAttributes;

    [
        object,
        oleautomation,
        uuid(b18e0b40-c089-4350-8328-066c668bccc2),
        pointer_default(unique),
    ]
    interface ICorSvcSetPrivateAttributes : IUnknown
    {
       HRESULT SetNGenPrivateAttributes(
           [in] NGenPrivateAttributes ngenPrivateAttributes
           );

    }

    //*****************************************************************************
    // ICorSvcRepository controls native images repository
    //*****************************************************************************[

    typedef enum
    {
        RepositoryDefault       = 0x0, // default settings
        MoveFromRepository      = 0x1, // move the native images from repository
        CopyToRepository        = 0x2, // copy the generated native images to repository
        IgnoreRepository        = 0x4, // Do not use the repository
    } RepositoryFlags;

    [
        object,
        oleautomation,
        uuid(d5346658-b5fd-4353-9647-07ad4783d5a0),
        pointer_default(unique),
    ]
    interface ICorSvcRepository : IUnknown
    {
       HRESULT SetRepository(
           [in] BSTR pRepositoryDir, 
           [in] RepositoryFlags repositoryFlags
           );

    }

#ifdef FEATURE_APPX
    //*****************************************************************************
    // ICorSvcAppX contains AppX-related method
    //*****************************************************************************[

    [
        object,
        uuid(5c814791-559e-4f7f-83ce-184a4ccbae24),
        pointer_default(unique),
    ]
    interface ICorSvcAppX : IUnknown
    {
        HRESULT SetPackage([in] BSTR pPackageFullName);

        HRESULT SetLocalAppDataDirectory([in] BSTR pLocalAppDataDirectory);
    }
#endif

    //*****************************************************************************
    // ICorSvcLogger is used to log various messages to the service process
    //*****************************************************************************[
    
    typedef enum CorSvcLogLevel
    {
        LogLevel_Error,
        LogLevel_Warning,
        LogLevel_Success,
        LogLevel_Info
    } CorSvcLogLevel;
    
    [
        object,
        oleautomation,
        uuid(d189ff1a-e266-4f13-9637-4b9522279ffc),
        pointer_default(unique),
    ]
    interface ICorSvcLogger : IUnknown
    {
        HRESULT Log(
            [in] CorSvcLogLevel logLevel,
            [in] BSTR message
        );
    }

    //*****************************************************************************
    // ICorSvcPooledWorker is used to determine whether a worker process can be
    // reused
    //*****************************************************************************[

    [
        object,
        oleautomation,
        uuid(0631e7e2-6046-4fde-8b6d-a09b64fda6f3),
        pointer_default(unique),
    ]
    interface ICorSvcPooledWorker : IUnknown
    {
        HRESULT CanReuseProcess(
            [in]  OptimizationScenario scenario,
            [in]  ICorSvcLogger *pCorSvcLogger,
            [out] BOOL *pCanContinue
            );
    }

    
    //*****************************************************************************
    // ICorSvcBindToWorker is used to bind to a specific runtime version.
    //*****************************************************************************[

    
    [
        object,
        oleautomation,
        uuid(5c6fb596-4828-4ed5-b9dd-293dad736fb5),
        pointer_default(unique),
    ]
    interface ICorSvcBindToWorker : IUnknown
    {
        HRESULT BindToRuntimeWorker(
            [in] BSTR pRuntimeVersion,
            [in] DWORD  ParentProcessID,
            [in] BSTR   pInterruptEventName,
            [in] ICorSvcLogger *pCorSvcLogger,
            [out] ICorSvcWorker **pCorSvcWorker
        );
    }

#ifndef IN_MSCOREE
}

typedef enum
{
    Service_NoAction             = -1 ,
    Service_Start                = 0x0, // start service
    Service_Stop                 = 0x1, // Stop service
    Service_Pause                = 0x2, // pause service
    Service_Continue             = 0x3, // continue a paused service
    Service_Interrogate          = 0x4, // continue a paused service
    Service_StartPaused          = 0x5, // pause service. start and pause if it's stopped
} ControlServiceAction;

// Haven't seen a better way of doing this. Everybody seems to be duplicating
// into IDLs (for example wtypes.idl)
typedef struct _COR_SERVICE_STATUS 
{  
    WCHAR sServiceName[64];
    DWORD dwServiceType;  
    DWORD dwCurrentState;   
    DWORD dwControlsAccepted;  
    DWORD dwWin32ExitCode;  
    DWORD dwServiceSpecificExitCode;  
    DWORD dwCheckPoint;  
    DWORD dwWaitHint;   
} COR_SERVICE_STATUS, *LPCOR_SERVICE_STATUS;

/* -------------------------------------------------------------------------- *
 * ICorSvc is implemented by the service dispatcher and contains APIs
 * for installing/uninstalling/starting/stopping the native image service,
 * as well as marshaling logic that provides the ICorOptSvcManager interface.
 * -------------------------------------------------------------------------- */
typedef struct _ServiceOptions
{
    BOOL RunAsWindowsService;
    BOOL RunAsPrivateRuntime;
    BOOL StartPaused;
} ServiceOptions;


[
    object,
    uuid(3eef5ff0-3680-4f20-8a8f-9051aca66b22),
    pointer_default(unique),
]
interface ICorSvc : IUnknown
{
   HRESULT GetServiceManagerInterface(
      [in] IUnknown **pIUnknown
      );

   HRESULT InstallService(
      );

   HRESULT UninstallService(
      );

   HRESULT ControlService(
      [in]  ControlServiceAction Action,
      [out] LPCOR_SERVICE_STATUS lpServiceStatus
      );
            
   HRESULT RunService(
            [in] ServiceOptions options
      );
}

[
    object,
    uuid(01c10030-6c81-4671-bd51-14b184c673b2),
    pointer_default(unique),
]
interface ICompileProgressNotification : IUnknown
{
    // Notify the installer that compilation has started, and give it an
    // estimation of how long it will take.
    HRESULT CompileStarted(
       [in] DWORD cAssembliesToCompile, 
       [in] DWORD cTimeEstimate
       );

    // Notify the installer that one more assembly has been compiled.  The
    // installer can return E_ABORT from ProgressNotification if it wants to
    // abort the compilation.
    HRESULT ProgressNotification(
       [in] DWORD cAssembly,
       [in] BSTR pAssemblyName,
       [in] BOOL isStartNotification, // if TRUE: we're starting to compile, if FALSE, we finished
       [in] HRESULT hrResult,       
       [in] BSTR errorExplanation,
       [in] DWORD cTimeRemainingEstimate
       );

           
}

/*
 * Ndp v4 interface that provides a threadID in notification messages
 */
[
    object,
    uuid(98E5BDE2-E9A0-4ADE-9CB2-6CD06FDB1A85),
    pointer_default(unique),
]
interface ICompileProgressNotification2 : IUnknown
{
    // Notify the installer that compilation has started, and give it an
    // estimation of how long it will take.
    HRESULT CompileStarted(
       [in] DWORD cAssembliesToCompile, 
       [in] DWORD cTimeEstimate,
       [in] DWORD threadID
       );

    // Notify the installer that one more assembly has been compiled.  The
    // installer can return E_ABORT from ProgressNotification if it wants to
    // abort the compilation.
    HRESULT ProgressNotification(
       [in] DWORD cAssembly,
       [in] BSTR pAssemblyName,
       [in] BOOL isStartNotification, // if TRUE: we're starting to compile, if FALSE, we finished
       [in] HRESULT hrResult,       
       [in] BSTR errorExplanation,
       [in] DWORD cTimeRemainingEstimate,
       [in] DWORD threadID
       );

           
}

typedef enum
{
    DefaultOptimizeFlags                = 0x0, // default settings
    TolerateCompilationFailures         = 0x1, // continue after encoutering compilation failures
    OptimizeNGenQueueOnly               = 0x2  // only take work items from the NGen Queue
} OptimizeFlags;


[
    object,
    uuid(0523feee-eb0e-4857-b2aa-db787521d077),
    pointer_default(unique),
] 
interface ICorSvcInstaller : IUnknown
{
   HRESULT Install(
      [in] BSTR path
      );

   HRESULT Uninstall(
      [in] BSTR path 
      );
    
   HRESULT Optimize(
      [in] ICompileProgressNotification *pCompileProgressNotification,
      [in] OptimizeFlags optimizeFlags
      );

   HRESULT SetLogger(
      [in] ICorSvcLogger *pCorSvcLogger
      );         
}

typedef enum
{
    DefaultFlags                        = 0x0, // default settings
    AllowPartialNames                   = 0x1, // input path allows partial names
    KeepPriority                        = 0x2, // keep priority after ngen completes
    NoRoot                              = 0x4, // Do not persist NGen root (automatically initiated NGen)
} GeneralFlags;

typedef enum
{
    Priority_None                 = -1,
    Priority_0                    = 0x0, // NGen offline queue. Do not use for anything else
    Priority_1                    = 0x1,
    Priority_2                    = 0x2,
    Priority_3                    = 0x3, // If you add or remove priorities, update Priority_Lowest

    Priority_Default              = Priority_3,
    Priority_Lowest               = Priority_3,
    Priority_LowestAggressive     = Priority_2, // The lowest priority for which assemblies are compiled aggressively
    Priority_Highest              = Priority_0,
    Priority_Highest_Root         = Priority_1,
    Priority_Lowest_Root          = Priority_3
} PriorityLevel;


/* -------------------------------------------------------------------------- *
 * ICorSvcAdvancedInstaller is implemented by the service manager and
 * used by installers with custom install requirements
 * such as special scenarios or hosting requirements).
 * -------------------------------------------------------------------------- */

[
    object,
    uuid(0871fb80-3ea0-47cc-9b51-d92e2aee75db),
    pointer_default(unique),
]
interface ICorSvcAdvancedInstaller : IUnknown
{
   HRESULT Install(
      [in] BSTR path,
      [in] OptimizationScenario optScenario,
      [in] BSTR config,
      [in] GeneralFlags generalFlags,
      [in] PriorityLevel priorityLevel
      );

   HRESULT Uninstall(
      [in] BSTR path,
      [in] OptimizationScenario optScenario,
      [in] BSTR config,
      [in] GeneralFlags generalFlags
      );
}


/* -------------------------------------------------------------------------- *
 * ICorSvcOptimizer is implemented by the service manager and is called
 * by installers and other tools to repair the native image caches.
 * -------------------------------------------------------------------------- */

typedef enum
{
    UpdateDefault                   = 0x0, // no hints about the scope of the update
    Force                           = 0x1, // force generation of new native images
    PostReboot                      = 0x2  // Update must happen after reboot
} UpdateFlags;


[
    object,
    uuid(94af0ec4-c10d-45d4-a625-d68d1b02a396),
    pointer_default(unique),
]
interface ICorSvcOptimizer : IUnknown
{
    // Optimize the native image for a given application or assembly (will regenerate
    // native images that are out of date)
    HRESULT Update(
       [in] BSTR path,
       [in] UpdateFlags updateFlags,
       [in] GeneralFlags generalFlags
       );

    HRESULT Display(
        [in] BSTR path,
        [in] GeneralFlags generalFlags
        );

    HRESULT ScheduleWork(
        [in] PriorityLevel priorityLevel
        );
}

[
    object,
    uuid(ee3b09c2-0110-4b6e-a73f-a3d6562f98ab),
    pointer_default(unique)
]
interface ICorSvcOptimizer2 : ICorSvcOptimizer {
    // generate a PDB for the given native image
    HRESULT CreatePdb([in] BSTR nativeImagePath, [in] BSTR pdbPath);
}

[
    object,
    uuid(6EED164F-61EE-4a07-ABE8-670F92B4B7A9),
    pointer_default(unique)
]
interface ICorSvcOptimizer3 : ICorSvcOptimizer2 {
    // generate a PDB for the given native image, optionally including source lines info
    HRESULT CreatePdb2([in] BSTR nativeImagePath, [in] BSTR pdbPath, [in] BOOL pdbLines, [in] BSTR managedPdbSearchPath);
}

typedef enum
{
    NewWorkAvailable                    = 0x0, // Notify the service that there is new work to do.
    ClientWorkStart                     = 0x1, // Notify the service that there is client starting to do work.
    ClientWorkDone                      = 0x2, // Notify the service that the client is done doing work.
    UpdatePostReboot                    = 0x3, // Notify the service that it should do an 'ngen update' after reboot
    NewWorkAvailableWithDelay           = 0x4, // Like NewWorkAvailable, but service should wait a while before working
} ServiceNotification;


/* -------------------------------------------------------------------------- *
 * ICorSvcManager is implemented by the service manager and used by
 * the service controller in balancing the need to generate native images
 * with the desire to not interfere with the usage of the computer.
 * -------------------------------------------------------------------------- */
[
    object,
    uuid(8f416a48-d663-4a7e-9732-fbca3fc46ea8),
    pointer_default(unique),
]
interface ICorSvcManager : IUnknown
{    
   // Schedule work only for selected priority level
   HRESULT ScheduleWorkForSinglePriorityLevel(
        [in]  PriorityLevel priorityLevel,
        [in]  BSTR          pInterruptEventName,
        [out] BOOL*         pWorkScheduled
        );

   // Do scheduled work
   HRESULT Optimize(
      [in] DWORD dwWorkerPriorityClass,
      [in] ICompileProgressNotification *pCompileProgressNotification,
      [in] BSTR pInterruptEventName
      ); 
   
   // Notify the service of new work
   HRESULT NotifyService(ServiceNotification notification); 

   HRESULT IsWorkAvailable  ([in] PriorityLevel priorityLevel,
                             [out] BOOL*        pWorkAvailable);      

   HRESULT Update(
       [in] UpdateFlags updateFlags,
       [in] BSTR pInterruptEventName
       );                                

   HRESULT SetSvcLogger(
      [in] ICorSvcLogger *pCorSvcLogger
      );         
}

[
    object,
    uuid(29626056-8031-441b-affa-7a82480058b3),
    pointer_default(unique),
]
interface ICorSvcManager2 : IUnknown
{
    HRESULT SetRuntimeVersion(BSTR version);

    HRESULT SetPackageMoniker(BSTR moniker);

    HRESULT SetLocalAppData(BSTR directory);
}

[
    object,
    uuid(35e5d609-ec3d-4fc2-9ba2-5f99e42ff42f),
    pointer_default(unique),
]
interface ICorSvcSetLegacyServiceBehavior : IUnknown
{
    HRESULT SetLegacyServiceBehavior();
}

[
    object,
    uuid(115466A4-7005-4CA3-971F-01F0A2C8EF09),
    pointer_default(unique),
]
interface ICorSvcSetTaskBootTriggerState : IUnknown
{
    HRESULT SetTaskBootTriggerState(BOOL bEnabled);
}

[
    object,
    uuid(261DD1E3-F07E-4B8D-B54E-F26889413626),
    pointer_default(unique),
]
interface ICorSvcSetTaskDelayStartTriggerState : IUnknown
{
    HRESULT SetTaskDelayStartTriggerState(BOOL bEnabled);
}

#endif // IN_MSCOREE