/****************************************************************************
*  The VSSHELL Interfaces
*  Copyright (c) Microsoft Corporation, All Rights Reserved
****************************************************************************/

#ifndef INTEROPLIB

// Imports - all imports should go here (inside the ifndef)
import "oaidl.idl";
import "vsshell.idl";
import "vsshell150.idl";

#endif

/****************************************************************************

***** General notes for updating this file

***** Proxy Stub

If you modify anything in here, you may need to rebuild the proxy-stub,
msenvXXXp.dll, and update its registration file,
SetupAuthoring\env\Registry\msenvXXXp.ddr. To do that, once this file has been
built and published, build from env\msenv\proxies and observe the build output.

If you need to omit something from the proxy/stub file, then put it inside an
#ifndef PROXYSTUB_BUILD/#endif block

There is no need to define GUIDs in external header files such as
vsshelluuids.h. Instead, define the GUID directly within the [uuid(...)]
attribute and use __uuidof in native code.

***** Primary Interop Assemblies

If you modify anything in here, you may need to rebuild the primary interop
assemblies. To do that, once this file has been built and published, build
from vscommon\pias using: 'msbuild pias.nativeproj'

***** PreserveSig

Prefer "nopreservesig", which is the default for all new interfaces, because
it creates cleaner managed code. Managed implementations are free to throw
exceptions which will automatically be translated to HRESULTs in the CLR's
COM interop layer. Native implementations will return HRESULTs and they will
be converted to exceptions for managed callers.

Do not create methods returning S_FALSE. Instead use an additional
"[out] VARIANT_BOOL*" or "[out,retval] VARIANT_BOOL*" argument.

***** Interface inheritance

You may derive new interfaces from existing ones, but avoid mixing
"preservesig" (old) with "nopreservesig" (new). Derive from an older interface
if all of the methods in your interface match the preservesig attributes of the
older interface.

Remember, when implementing a derived interface in C++, you must implement
QueryInterface for the base interface(s) too.

***** Enumerators and bitwise flags passed as parameters:

When a parameter must be exactly one of a set of values (a true enumerator),
the values should be defined and used as follows:

typedef enum __VSSAMPLETYPE
{
ST_THISTYPE     = 0,   // first value should be zero or one, except
ST_THATTYPE     = 1,   // in special cases, and following values
ST_THEOTHERTYPE = 2,   // should use consecutive numbers
} VSSAMPLETYPE;

interface IVsSample : IUnknown
{
HRESULT SampleMethod([in] VSSAMPLETYPE stType);
}

When a parameter must be exactly one of a set of values (a true enumerator),
and is considered a PROPID, the values should be defined and used as follows:

enum __VSSAMPLEPROPID
{
VSSAMPPROPID_LAST     = -7000,  // first value should be a unique
VSSAMPPROPID_This     = -7000,  // number not used by any other
VSSAMPPROPID_That     = -7001,  // PROPID, and following values
VSSAMPPROPID_FIRST    = -7001,  // should use consecutive numbers
};
typedef LONG VSSAMPLEPROPID;

interface IVsSample : IUnknown
{
HRESULT GetProperty([in] VSSAMPLEPROPID propid, [out,retval] VARIANT *pvar);
HRESULT SetProperty([in] VSSAMPLEPROPID propid, [in] VARIANT var);
}

When a parameter can be none of or a combination of values (bitwise),
the values should be defined and used as follows:

enum __VSSAMPLEOPTS
{
SO_THISOPTION     = 0x00000001,   // first value should be one,
SO_THATOPTION     = 0x00000002,   // following values should use
SO_THEOTHEROPTION = 0x00000004,   // consecutive powers of two
};
typedef DWORD VSSAMPLEOPTS;

interface IVsSample : IUnknown
{
HRESULT SampleMethod([in] VSSAMPLEOPTS grfOptions);
}

***** Defining properties

Define properties as follows:

interface IVsSample : IUnknown
{
[propget] HRESULT Foo([out, retval] BSTR *pbstrFoo);
[propput] HRESULT Foo([in] LPCOLESTR strFoo);
}

Using [propget], [propput] and [out, retval] makes the interface easier
to implement and consume in managed code.

Note: The example above shows a case where the get/put methods accept slightly different
argument types (BSTR versus LPCOLESTR). As long as the equivalent interop types are the
same, this is fine (MarshalAs[..] attributes will be added as necessary). However, this
is typically seen only for string arguments.

***** Array typed args

Pass array type arguments (both in and out) using [] and size_is when the corresponding
size argument is present. You must have the array size as an argument for interop to
work correctly.

interface IVsSample : IUnknown
{
HRESULT MethodPassesInArray([in] int cItems, [in, size_is(cItems)] int prgiItems[]);
}

DO NOT use [in] int piItems[].

For simple element types, consider using SAFEARRAY: e.g. SAFEARRAY(VARIANT_BOOL),
SAFEARRAY(BSTR), SAFEARRAY(INT), etc. because they interop cleanly to managed code, but
note that there is additional memory allocation and it may not be appropriate for high-
performance methods. Also see the following note.

******* SAFEARRAY(IVsFoo*)

SAFEARRAY(IVsFoo*) will cause MIDL warning 2456:
SAFEARRAY(interface pointer) doesn't work using midl generated proxy

If you know for sure that implementions will never will never need to be called cross
apartment (cross thread/process), then you can add [local] to the method.

Alternatively, consider creating a custom IEnumXXX interface.

****** Strings

Use "[in] LPCOLESTR" instead of "[in] BSTR"

for faster marshaling and more convenience to native callers.
(But continue to use "[out] BSTR*" for out args.)

Generally, you don't need to specify [in,string] for NUL-terminated strings
because most of the "pointer to character" typedefs are already attributed with
[string]. (e.g. "typedef [string] const OLECHAR *LPCOLESTR")

******* Boolean

Use VARIANT_BOOL instead of BOOL because it interops as System.Boolean instead
of System.Int

However, exercise caution when assigning or comparing to/from C++ bool in native
code because VARIANT_BOOL is typedef'd as a short and VARIANT_TRUE is ((short)-1)

******* Optional (may be null) args

Use [in,unique] for optional input arguments which may be NULL.
Note that pointer_default(unique) does NOT do this automatically.

Do not use [out,unique] because unique cannot be applied to [out]-only top-level
pointer parameters. However, you can use [in,out,unique].

Do not use [optional]. It only works with VARIANT anyway and it's not
obvious for managed coders.

******* [out] NonNullableType*

Note that arguments of the type "[out] Foo* pFoo", where Foo is a "non-nullable
type" such as int, double, VARIANT_BOOL, BSTR, will be converted to
"out Foo[] pFoo" in managed code. This is a non-standard conversion applied by
an IL transformation step during the build for the interop assembly.

******* Service GUIDs

Define service GUIDs via an empty interface derived from IUnknown
and put it inside an #ifndef PROXYSTUB_BUILD/#endif block

******* HWNDs, HANDLE, and other non-marshalable types

Take care if you define an interface with HWND, HGDIOBJ or other Win32
handle types. These typically need to be marked [local] since they
cannot cross apartment (specifically, process) boundaries.

****************************************************************************/

#include "vsshelluuids.h" // for uuid_VsPreserveSigAttribute

// forward declarations


[uuid(2D124B9B-8989-4F82-8E9D-AE0B002E0615)]
interface IVsBulkFileOperation : IUnknown
{
    // Update this instance of Visual Studio
    HRESULT StartOperation();
    HRESULT EndOperation();
}

[uuid(a4afcb52-b595-43f9-87dd-6eb348181e14)]
interface IVsFileChangeEx3 : IVsFileChangeEx2
{
    // Pauses all change notifications from the service, for all files and directories.
    // Pause() can be called multiple times, and must be balanced by an equal number of
    // calls to Resume() before notificiations are resumed.  The returned task will be
    // completed once notifications have been paused.
    HRESULT Pause([out, retval] IVsTask** task);

    // Resumes change notifications from the service, for all files and directories.
    // The change notifications that accumulated while the service is paused will be
    // dispatched asynchronously.  The returned task will be completed once the accumulated
    // notifications have been dispatched.
    HRESULT Resume([out, retval] IVsTask** task);
}

//----------------------------------------------------------------------------
// IVsFreeThreadedFileChangeEvents2
//
// If you implement this interface on your event sink, you are declaring 
// that your sink is free-threaded.  IVsFileChangeEvents.FilesChanged will be 
// called on a background thread, not on the main thread.  Likewise, 
// IVsFreeThreadedFileChangeEvents2.DirectoryChangedEx2 will be called on a
// background thread, not on the main thread.  IVsFileChangeEvents.DirectoryChanged
// and IVsFreeThreadedFileChangeEvents.DirectoryChangedEx will not be called on your sink.
//----------------------------------------------------------------------------
[
    uuid(2019c53d-105b-4116-8a1a-4703796e5052),
    custom(uuid_VsPreserveSigAttribute, "preservesig")              // base interface is preservesig, so this one must be as well
]
interface IVsFreeThreadedFileChangeEvents2 : IVsFreeThreadedFileChangeEvents
{
    HRESULT DirectoryChangedEx2(
        [in] LPCOLESTR pszDirectory,                                // the directory that changed
        [in] DWORD cChanges,                                        // the number of files that changed
        [in, size_is(cChanges)] LPCOLESTR rgpszFile[],              // the files that changed
        [in, size_is(cChanges)] VSFILECHANGEFLAGS rggrfChange[]);   // the changes to the files
}

[uuid(bfdff000-3761-49b2-ba9b-4c1db1d82789)]
interface IVsDebugger9 : IUnknown
{
    // Called by project systems that display an option to enable JavaScript debugging when the user changes this option.
    HRESULT SetEnableJavaScriptDebuggerOnBrowserLaunch([in] BOOL fEnable);

    // Called by project systems that respond to the debugger's "Enable JavaScript debugging" option. Currently this is
    // just the ASP.NET project system, though other project systems can use it.
    //
    // This will check if there are any breakpoints set in javascript files, and put up a dialog giving users the option
    // to re-enable javascript debugging if breakpoints are found and script debugging is currently disabled.
    //
    // The out param will return the current value of the option at the end of the method.
    HRESULT NotifyBeforeLaunchWithoutJavaScriptDebugger([out] BOOL* pfEnabled);
}



// Batch project load support

enum __VSPREFETCHFACTORYCAPABILITIES
{
    // (pre-fetched)
    PFC_NONE          = 0x00000000,
    PFC_SYNC          = 0x00000001,     // Projects prefetch will be complete before factory PrepareProject() call complete
    PFC_SELECTOR      = 0x00000002,    // Prefetch factory integrates the project selector as well.
    PFC_SAFE_CHECK    = 0x00000004     // Prefetch factory will do the mark of the web check before loading proejct
};
typedef DWORD VSPREFETCHFACTORYCAPABILITIES;


enum __VSPROJECTLOADFLAGS
{
    PLF_NONE           = 0x00000000,
    PFL_CONFIRMED_SAFE = 0x00000001   // project is confirmed to be safe by user.
};
typedef DWORD VSPROJECTLOADFLAGS;

enum __VSBATCHLOADRESULT
{
    // (pre-fetched)
    BLR_SUCCESS        = 0x00000000,    // project pre-fetched successfully

    // (not pre-fetched)
    BLR_PREFETCH_ERROR = 0x00000001,    // project prefetch error. (will try to load it with no prefetch)
    BLR_LOAD_ERROR     = 0x00000002,    // project load error. (no need to retry with no prefetch)
    BLR_NEED_UPGRADE   = 0x00000003,    // project needs upgrade.
    BLR_UNSAFE_PROJECT = 0x00000004,    // project is unsafe and need user confirmation.
    BLR_NEW_FACTORY    = 0x00000005     // project selector identified different factory.
};
typedef DWORD VSBATCHLOADRESULT;


typedef struct _VsPrefetchedProjectInfo
{
    GUID  guidProjectId;
    VSBATCHLOADRESULT resultFlags;              // prefetch result
    IUnknown *pProject;                         // prefetched project object
    HRESULT hr;                                 // overall result
    GUID  guidNewFactory;                       // in case of preferred factory via project selector or new factory identified by upgrade check
    VSPUVF_REPAIRFLAGS repairFlags;             // in case of upgrade required
    VSPUVF_FLAGS       upgradeCapabilityFlags;  // in case of upgrade required
} VsPrefetchedProjectInfo;

[uuid(C917ECD8-ED08-49BE-97F2-6C994BF32072)]
interface IVsPrefetchLoadProgress2 : IUnknown
{
    // Called back by prefetch factory when prefetch process is done to provide detailed pre-fetch result
    HRESULT PrefetchResult([in] int count, [in, size_is(count)] VsPrefetchedProjectInfo rgProjects[]);
}