// 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.

/* -------------------------------------------------------------------------- *
 * Common Language Runtime Process Publishing Interfaces
 * -------------------------------------------------------------------------- */

cpp_quote("#if 0")
#ifndef DO_NO_IMPORTS
import "unknwn.idl";
#endif
cpp_quote("#endif")

typedef enum
{
    COR_PUB_MANAGEDONLY                 = 0x00000001    // Must always be set,
                                                        // only enumerates 
                                                        // managed processes
} COR_PUB_ENUMPROCESS;


/* -------------------------------------------------------------------------- *
 * Forward declarations
 * -------------------------------------------------------------------------- */
#pragma warning(push)
#pragma warning(disable:28718)    //Unable to annotate as this is not a local interface

interface ICorPublish;
interface ICorPublishProcess;
interface ICorPublishAppDomain;
interface ICorPublishProcessEnum;
interface ICorPublishAppDomainEnum;

#pragma warning(pop)

/* ------------------------------------------------------------------------- *
 * Library defintion
 * ------------------------------------------------------------------------- */

[
  uuid(e97ca460-657d-11d3-8d5b-00104b35e7ef),
  version(1.0),
  helpstring("Common Language Runtime Process Publishing Library")
]
library CorpubProcessLib
{
    importlib("STDOLE2.TLB");

    // CorPublish is a shared component across all version of the runtime.
    [
        uuid(047a9a40-657e-11d3-8d5b-00104b35e7ef)
    ]
    coclass CorpubPublish
    {
        [default] interface ICorPublish;
        interface            ICorPublishProcess;
        interface            ICorPublishAppDomain;
        interface            ICorPublishProcessEnum;
        interface            ICorPublishAppDomainEnum;
    };
};


/* -------------------------------------------------------------------------- *
 * Interface definitions
 * -------------------------------------------------------------------------- */

/*
 * This interface is the top level interface for publishing of processes.
 */
[
    object,
    uuid(9613A0E7-5A68-11d3-8F84-00A0C9B4D50C),
    pointer_default(unique),
    local
]
interface ICorPublish : IUnknown
{
    /*
     * Retrieves a list of managed processes on this machine which
     * the current user has permission to debug.  In this version, 
     * Type must always be equal to COR_PUB_MANAGEDONLY.  
     * The list is based on a snapshot of the processes running when 
     * the enum method is called.  The enumerator will not reflect any
     * processes that start before or terminate after EnumProcesses is called.
     * If EnumProcesses is called more than once on this ICorPublish
     * instance, a new up-to-date enumeration will be returned without 
     * affecting any previous ones.
     */
    HRESULT EnumProcesses([in] COR_PUB_ENUMPROCESS Type,
                          [out] ICorPublishProcessEnum **ppIEnum);

    /*
     * Gets a new ICorPublishProcess object for the managed process 
     * with the given process ID.  Returns failure if the process doesn't
     * exist, or isn't a managed process that can be debugged by the current
     * user.  
     */
    HRESULT GetProcess([in] unsigned pid, 
                       [out] ICorPublishProcess **ppProcess);
}

/*
 * An abstract enumerator.
 */
[
    object,
    uuid(C0B22967-5A69-11d3-8F84-00A0C9B4D50C),
    pointer_default(unique),
    local
]
interface ICorPublishEnum : IUnknown
{
    /*
     * Moves the current position forward the given number of
     * elements.
     */
    HRESULT Skip([in] ULONG celt);

    /*
     * Sets the position of the enumerator to the beginning of the
     * enumeration.
     */
    HRESULT Reset();

    /*
     * Creates another enumerator with the same current position
     * as this one.
     */
    HRESULT Clone([out] ICorPublishEnum **ppEnum);

    /*
     * Gets the number of elements in the enumeration
     */
    HRESULT GetCount([out] ULONG *pcelt);
};

#pragma warning(push)
#pragma warning(disable:28718)
/*
 * Describes a process on a machine.
 */
[
    object,
    uuid(18D87AF1-5A6A-11d3-8F84-00A0C9B4D50C),
    pointer_default(unique),
    local
]
interface ICorPublishProcess : IUnknown
{
    /*
     * Returns true if the process is known to have managed code
     * running in it.  Since this version of ICorPublish only provides access 
     * to managed processes, this method always returns true.
     */
    HRESULT IsManaged([out] BOOL *pbManaged);
    
    /*
     * Enumerates the list of known application domains in this process.
     * This list is based on a snapshot of the existing AppDomains when
     * this method is called.  This method may be called more than
     * once to create a new up-to-date list.  Existing enumerations will not
     * be affected by calls to this method.  If the process has been 
     * terminated, this will fail with CORDBG_E_PROCESS_TERMINATED.
     */
    HRESULT EnumAppDomains([out] ICorPublishAppDomainEnum **ppEnum);
    
    /*
     * Returns the OS ID for this process.
     */
    HRESULT GetProcessID([out] unsigned *pid);
    
    /*
     * Get the full path of the executable for this process.
     * If szName is non-null, this copies up to cchName characters (including 
     * the null terminator) into szName, and ensures it is null-terminated.
     * If pcchName is non-null, the actual number of characters in the name
     * (including the null terminator) is stored there.  This method returns
     * S_OK regardless of how many characters were copied.
     */
    HRESULT GetDisplayName([in] ULONG32 cchName, 
                           [out] ULONG32 *pcchName,
                           [out, size_is(cchName), 
                           length_is(*pcchName)] WCHAR *szName);
}
#pragma warning(pop)

#pragma warning(push)
#pragma warning(disable:28718)
/*
 * Provide information on an Application Domain object.
 */
[
    object,
    uuid(D6315C8F-5A6A-11d3-8F84-00A0C9B4D50C),
    pointer_default(unique),
    local
]
interface ICorPublishAppDomain : IUnknown
{
    /*
     * Gets the identification number of this application domain.  
     * Note that this number is unique to this AppDomain, but only 
     * within the containing process.
     */
    HRESULT GetID([out] ULONG32 *puId);
    
    /*
     * Get the name for an application domain.
     * If szName is non-null, this copies up to cchName characters (including 
     * the null terminator) into szName, and ensures it is null-terminated.
     * If pcchName is non-null, the actual number of characters in the name
     * (including the null terminator) is stored there.  This method returns
     * S_OK regardless of how many characters were copied.
     */
    HRESULT GetName([in] ULONG32 cchName, 
                    [out] ULONG32 *pcchName,
                    [out, size_is(cchName), 
                    length_is(*pcchName)] WCHAR *szName);
}
#pragma warning(pop)


/*
 * Enumerate a list of processes based on the filter criteria given
 * when the enumerator object was created.
 */
[
    object,
    uuid(A37FBD41-5A69-11d3-8F84-00A0C9B4D50C),
    pointer_default(unique),
    local
]
interface ICorPublishProcessEnum : ICorPublishEnum
{
    /*
     * Gets the next "celt" processes in the enumeration.
     */
    HRESULT Next([in] ULONG celt,
                 [out, size_is(celt), 
                  length_is(*pceltFetched)] ICorPublishProcess **objects,
                 [out] ULONG *pceltFetched);
}

/*
 * Enumerate a list of app domains based in a process.
 */
[
    object,
    uuid(9F0C98F5-5A6A-11d3-8F84-00A0C9B4D50C),
    pointer_default(unique),
    local
]
interface ICorPublishAppDomainEnum : ICorPublishEnum
{
    /*
     * Gets the next "celt" application domains in the enumeration.
     */
    HRESULT Next([in] ULONG celt,
                 [out, size_is(celt), 
                  length_is(*pceltFetched)] ICorPublishAppDomain **objects,
                 [out] ULONG *pceltFetched);
}