/**************************************************************************** * 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 "vsshell2.idl"; import "vsshell80.idl"; import "vsshell90.idl"; import "vsshell100.idl"; import "vsshell110.idl"; import "vsshell120.idl"; import "vsshell140.idl"; import "vsshell150.idl"; import "vsshell153.idl"; import "objext.idl"; import "olecm.idl"; import "VsPlatformUI.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 //---------------------------------------------------------------------- // IVsUserSettings3 // clients that want to export settings asynchronously should use this instead of IVsUserSettings2 //---------------------------------------------------------------------- [ uuid(2AD1813A-8691-468A-A777-BD0FDA5CF48E), version(1.0), pointer_default(unique) ] interface IVsUserSettings3 : IVsUserSettings2 { // asynchronous version of export settings, returns a task that the caller can wait on HRESULT ExportSettingsAsync([in] REFGUID category, [in] IVsSettingsWriter* settingsWriter, [in] IVsSettingsStorageContainer* storageContainer, [out,retval] IVsTask** ppTask); }; // enum __VSDBGLAUNCHFLAGS154 ADDED IN DEV15 Update 5 // NOTE: USE OF THIS ENUM REQUIRES DEV15 UPDATE 5 OR ABOVE TO BE INSTALLED enum __VSDBGLAUNCHFLAGS155 { /********************************************** defined in vsshell.idl DBGLAUNCH_Silent = 0x00000001, DBGLAUNCH_LocalDeploy = 0x00000002, // passed to IVsDebuggableProjectCfg::Launch to allow optimizations DBGLAUNCH_NoDebug = 0x00000004, // launch without attaching a debugger DBGLAUNCH_DetachOnStop = 0x00000008, // detach instead of terminate when debugging stopped. DBGLAUNCH_Selected = 0x00000010, // launch selected project instead of startup project DBGLAUNCH_StopDebuggingOnEnd = 0x00000020, // when this process ends, debugging is stopped. DBGLAUNCH_WaitForAttachComplete = 0x00000040, // when DLO_LaunchByWebServer, wait for the attach to finish before continuing to launch other targets ********************************************** defined in vsshell80.idl*/ /* DBGLAUNCH_MergeEnv = 0x00000080, // provided environment should be merged with system environment DBGLAUNCH_DesignTimeExprEval = 0x00000100, // launched for design-time expression evaluation DBGLAUNCH_StopAtEntryPoint = 0x00000200, // Stop at the entrypoint (step-into) DBGLAUNCH_CannotDebugAlone = 0x00000400, // this process cannot be debugged alone -- stop debugging when only processes with this flag remain **********************************************/ /********************************************** defined in vsshell90.idl DBGLAUNCH_WaitForEvent = 0x00000800 // Debugger should wait for a named event to become signaled after launching the first debug target and before launching more targets **********************************************/ /********************************************** defined in vsshell90.idl (SP1) DBGLAUNCH_UseDefaultBrowser = 0x00001000 // Debugger should use the Default Web Browser; this flag used in conjunction with DLO_LaunchBrowser. // The default browser is obtained via IVsUIShellOpenDocument:: GetFirstDefaultPreviewer(). // The bstrEXE in VsDebugTargetInfo2 points to the URL to be launched. Web Site projects will use // this for Silverlight projects. This allows, for example, Firefox to be used which is single // instance and so has to be handled differently on launch. Other project systems (e.g. C++) that // currently use DLO_LaunchBrowser will continue to use that and IE will get launched as before. **********************************************/ /********************************************* defined in vsshell100.idl (dev10) DBGLAUNCH_PrepForDebug = 0x00002000, // We will eventually debug this process, so allow the debugger to perform additional setup DBGLAUNCH_TerminateOnStop = 0x00004000, // Terminate the debuggee when debugging is stopped. It is an error to specify both this and DBGLAUNCH_DetachOnStop DBGLAUNCH_BreakOneProcess = 0x00008000 // Disable 'Break all processes when one process breaks' debugger option for the debugging session; this option is ignoring if debugging has already started. DBGLAUNCH_BlockCredentialsDialog= 0x00010000, // Blocks the creditials dialog from being shown on authentication errors DBGLAUNCH_BlockWWSDialog = 0x00020000, // Blocks the WWS install dialog from being shown DBGLAUNCH_StartInSimulator = 0x00040000 // For DLO_AppPackageDebug, debugger should launch the application (or expect the application to start) in the simulator ********************************************** defined in vsshell110.idl (dev11) **********************************************/ /********************************************* defined in vsshell100.idl (dev12) DBGLAUNCH_ALLOW_EVENTS_AFTER_STOPPED = 0x00080000, // Allows stopping events in break-mode DBGLAUNCH_FORCE_32BIT_DEBUG = 0x00100000, // Force use of the 32-bit debugger (currently used only for DLO_CreateProcess) DBGLAUNCH_FORCE_64BIT_DEBUG = 0x00200000 // Force use of the 64-bit debugger (currently used only for DLO_CreateProcess) ********************************************** defined in vsshell110.idl (dev13) **********************************************/ /********************************************** defined in vsshell140.idl (dev14) DBGLAUNCH_ContainsStartupTask = 0x00400000, // Use Startup Task activator (currently used only for DLO_AppPackageDebug) DBGLAUNCH_Profiling = 0x00800000 // Launch process for profiling **********************************************/ /********************************************** defined in vsshell142.idl (dev14) DBGLAUNCH_NoTerminateOnImmediateLaunch = 0x01000000 // For DLO_AppPackageDebug, allow app to be running immediately after App Activation. **********************************************/ DBGLAUNCH_ParallelLaunch = 0x02000000 }; typedef DWORD VSDBGLAUNCHFLAGS155;