using System;
using System.Runtime.CompilerServices;
using System.Runtime.InteropServices;
namespace Vanara.PInvoke
{
public static partial class Shell32
{
/// These flags are used with IExplorerBrowser::FillFromObject.
[Flags]
[PInvokeData("Shobjidl.h", MSDNShortId = "5be62600-147d-4625-8e6c-aa6687da2168")]
public enum EXPLORER_BROWSER_FILL_FLAGS
{
/// No flags.
EBF_NONE = 0x0000000,
///
/// Causes IExplorerBrowser::FillFromObject to first populate the results folder with the contents of the parent folders of the
/// items in the data object, and then select only the items that are in the data object.
///
EBF_SELECTFROMDATAOBJECT = 0x0000100,
///
/// Do not allow dropping on the folder. In other words, do not register a drop target for the view. Applications can then
/// register their own drop targets.
///
EBF_NODROPTARGET = 0x0000200,
}
/// These flags are used with IExplorerBrowser::GetOptions and IExplorerBrowser::SetOptions.
[Flags]
[PInvokeData("Shobjidl.h", MSDNShortId = "4e2983bc-cad2-4bcc-8169-57b5274b2142")]
public enum EXPLORER_BROWSER_OPTIONS
{
/// No options.
EBO_NONE = 0x00000000,
/// Do not navigate further than the initial navigation.
EBO_NAVIGATEONCE = 0x00000001,
///
/// Use the following standard panes: Commands Module pane, Navigation pane, Details pane, and Preview pane. An implementer of
/// IExplorerPaneVisibility can modify the components of the Commands Module that are shown. For more information see,
/// IExplorerPaneVisibility::GetPaneState. If EBO_SHOWFRAMES is not set, Explorer browser uses a single view object.
///
EBO_SHOWFRAMES = 0X00000002,
/// Always navigate, even if you are attempting to navigate to the current folder.
EBO_ALWAYSNAVIGATE = 0x00000004,
/// Do not update the travel log.
EBO_NOTRAVELLOG = 0x00000008,
///
/// Do not use a wrapper window. This flag is used with legacy clients that need the browser parented directly on themselves.
///
EBO_NOWRAPPERWINDOW = 0x00000010,
/// Show WebView for SharePoint sites.
EBO_HTMLSHAREPOINTVIEW = 0x00000020,
/// Introduced in Windows Vista. Do not draw a border around the browser window.
EBO_NOBORDER = 0x00000040,
/// Introduced in Windows Vista. Do not persist the view state.
EBO_NOPERSISTVIEWSTATE = 0x00000080,
}
///
///
/// IExplorerBrowser is a browser object that can be either navigated or that can host a view of a data object. As a
/// full-featured browser object, it also supports an automatic travel log.
///
///
/// The Shell provides a default implementation of IExplorerBrowser as CLSID_ExplorerBrowser. Typically, a developer does not
/// need to provide a custom implementation of this interface.
///
///
/// The Windows Software Development Kit (SDK) provides full samples that demonstrate the use of and interaction with
/// IExplorerBrowser. Download the Explorer Browser Search Sample and the Explorer Browser Custom Contents Sample.
///
///
///
///
/// For example code that shows typical use of IExplorerBrowser and its methods, see the Explorer Browser Custom Contents and
/// Explorer Browser Custom Contents samples.
///
///
/// After calling this object's Initialize method, its Destroy method must be called to free any windowed resources that were
/// generated in the call to Initialize.
///
///
/// The object that hosts the ExplorerBrowser object should derive from IServiceProvider and implement QueryService to respond to any
/// queries for service. For example, the number of panes shown by the browser can be controlled by implementing
/// IExplorerPaneVisibility and responding to any SID_ExplorerPaneVisibility service requests.
///
///
/// Frames are disabled by default. To enable frames and get the default set of panes, set the EBO_SHOWFRAMES flag using the
/// IExplorerBrowser::SetOptions method. The default panes, listed as IExplorerPaneVisibility constants, are these:
///
///
/// - EP_NavPane
/// - EP_Commands
/// - EP_Commands_Organize
/// - EP_Commands_View
/// - EP_DetailsPane
/// - EP_PreviewPane
/// - EP_QueryPane
/// - EP_AdvQueryPane
/// - EP_StatusBar
/// - EP_Ribbon
///
/// See IExplorerPaneVisibility::GetPaneState for more information.
///
/// Clients of the ExplorerBrowser object can implement the ICommDlgBrowser, ICommDlgBrowser2, or ICommDlgBrowser3 interfaces and
/// respond to an SID_SExplorerBrowserFrame service request in their QueryService implementations that are called when any
/// ICommDlgBrowser interfaces are called on the browser (usually called from the view as a result of user actions). Note that
/// the client does not receive a call to ICommDlgBrowser::IncludeObject if a folder filter has been set on the browser by a call to IFolderFilterSite::SetFilter.
///
///
/// To remain compatible with some older applications, the default Shell view (DefView) performs filtering operations (for example,
/// searching operations executed by a search folder) on the UI thread. For new applications, this is typically not desired; the
/// search should execute on a background thread. To stop the UI thread from filtering and instead run filtering on a background
/// thread, provide ICommDlgBrowser2 through the SID_SExplorerBrowserFrame service request. When ICommDlgBrowser2::GetViewFlags is
/// called, it should return CDB2GVF_NOINCLUDEITEM. For example, if you navigate to a search folder in ExplorerBrowser and you do not
/// return CDB2GVF_NOINCLUDEITEM, the view can stop responding until the entire search is complete.
///
///
/// The Shell architecture has three main components: the browser, the views, and the data sources (for example, IShellFolder). The
/// ExplorerBrowser object maintains the current location and navigation to other locations throughout the Shell namespace. It also
/// keeps a travel log (forward and back history). The browser is notified when things happen in the view; for example, when the user
/// double-clicks a folder. In response, the browser navigates to that location. The data sources are the objects that supply the
/// items and folders in the namespace. They also have information about the location, such as the properties of the items and what
/// to add to the context menu when the view requests it. Additionally, the data sources know what view should be created to
/// represent their items at a location. In almost all instances, the folders create the Shell's default view (DefView). Therefore,
/// as the browser navigates, it receives an IShellFolder object for the new location and asks it what view to create. The browser
/// then creates that view and makes it visible, while hiding and then destroying the view that was showing the previous location.
/// The view is responsible for communicating with IShellFolder for the current location and requesting it to enumerate the
/// items, which allows the view to show these items to the user. As the user interacts with the items, the view communicates with
/// the IShellFolder to get any additional information it needs, such as specific properties of the items or the context menu
/// entries for the item.
///
///
/// If an application uses the default implementation provided by CLSID_ExplorerBrowser, inserting it into the window of an
/// application and then browsing to a location, ExplorerBrowser creates the proper IShellView as specified by the location that it
/// is browsing to. The application can then ask ExplorerBrowser to give it an interface on the current view, allowing the
/// application to manipulate the view directly if required. The default implementation of the Windows Explorer view object, created
/// by SHCreateShellFolderViewEx, supports the interface IShellView. You may verify that you have the default Shell folder
/// view object by calling IExplorerBrowser::GetCurrentView and then calling QueryInterface on the object returned using the
/// interface ID IID_CDefView.
///
///
/// Windows 7 and later. CExplorerBrowser can support in-place navigation by using IServiceProvider::QueryService with the
/// Service ID SID_SlnPlaceBrowser. When using SID_SInPlaceBrowser, the CExplorerBrowser state cannot be set to EBO_NAVIGATEONCE.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shobjidl_core/nn-shobjidl_core-iexplorerbrowser
[PInvokeData("shobjidl_core.h", MSDNShortId = "da2cf5d4-5a68-4d18-807b-b9d4e2712c10")]
[ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("dfd3b6b5-c10c-4be9-85f6-a66969f402f6"), CoClass(typeof(ExplorerBrowser))]
public interface IExplorerBrowser
{
/// Prepares the browser to be navigated.
/// A handle to the owner window or control.
///
/// A pointer to a RECT that contains the coordinates of the bounding rectangle that the browser will occupy. The coordinates are
/// relative to hwndParent.
///
/// A pointer to a FOLDERSETTINGS structure that determines how the folder will be displayed in the view.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void Initialize([In] IntPtr hwndParent, in RECT prc, [Optional] PFOLDERSETTINGS pfs);
/// Destroys the browser.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void Destroy();
/// Sets the size and position of the view windows created by the browser.
/// A pointer to a DeferWindowPos handle. This parameter can be NULL.
/// The coordinates that the browser will occupy.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void SetRect([In, Out] ref HDWP phdwp, [In] RECT rcBrowser);
/// Sets the name of the property bag.
///
/// A pointer to a constant, null-terminated, Unicode string that contains the name of the property bag. View state information
/// that is specific to the application of the client is stored (persisted) using this name.
///
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void SetPropertyBag([In, MarshalAs(UnmanagedType.LPWStr)] string pszPropertyBag);
/// Sets the default empty text.
/// A pointer to a constant, null-terminated, Unicode string that contains the empty text.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void SetEmptyText([In, MarshalAs(UnmanagedType.LPWStr)] string pszEmptyText);
/// Sets the folder settings for the current view.
/// A pointer to a FOLDERSETTINGS structure that contains the folder settings to be applied.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void SetFolderSettings(in FOLDERSETTINGS pfs);
/// Initiates a connection with IExplorerBrowser for event callbacks.
/// A pointer to the IExplorerBrowserEvents interface of the object to be advised of IExplorerBrowser events.
///
/// When this method returns, contains a token that uniquely identifies the event listener. This allows several event listeners
/// to be subscribed at a time.
///
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void Advise([In] IExplorerBrowserEvents psbe, out uint pdwCookie);
/// Terminates an advisory connection.
///
/// A connection token previously returned from IExplorerBrowser::Advise. Identifies the connection to be terminated.
///
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void Unadvise([In] uint dwCookie);
/// Sets the current browser options.
/// One or more EXPLORER_BROWSER_OPTIONS flags to be set.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void SetOptions([In] EXPLORER_BROWSER_OPTIONS dwFlag);
/// Gets the current browser options.
/// When this method returns, contains the current EXPLORER_BROWSER_OPTIONS for the browser.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void GetOptions(out EXPLORER_BROWSER_OPTIONS pdwFlag);
/// Browses to a pointer to an item identifier list (PIDL)
///
/// A pointer to a const ITEMIDLIST (item identifier list) that specifies an object's location as the destination to navigate to.
/// This parameter can be NULL. For more information, see Remarks.
///
/// A flag that specifies the category of the pidl. This affects how navigation is accomplished.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void BrowseToIDList([In] PIDL pidl, [In] SBSP uFlags);
/// Browses to an object.
/// A pointer to an object to browse to. If the object cannot be browsed, an error value is returned.
/// A flag that specifies the category of the pidl. This affects how navigation is accomplished.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
[PreserveSig]
HRESULT BrowseToObject([MarshalAs(UnmanagedType.IUnknown)] object punk, SBSP uFlags);
/// Creates a results folder and fills it with items.
///
/// An interface pointer on the source object that will fill the IResultsFolder. This can be an IDataObject or any object that
/// can be used with INamespaceWalk.
///
/// One of the EXPLORER_BROWSER_FILL_FLAGS values.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void FillFromObject([In, MarshalAs(UnmanagedType.IUnknown)] object punk, [In] EXPLORER_BROWSER_FILL_FLAGS dwFlags);
/// Removes all items from the results folder.
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
void RemoveAll();
/// Gets an interface for the current view of the browser.
/// A reference to the desired interface ID.
///
/// When this method returns, contains the interface pointer requested in . This will typically be
/// IShellView, IShellView2, IFolderView, or a related interface.
///
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
[return: MarshalAs(UnmanagedType.Interface, IidParameterIndex = 0)]
object GetCurrentView(in Guid riid);
}
/// Exposes methods for notification of Explorer browser navigation and view creation events.
[ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("361bbdc7-e6ee-4e13-be58-58e2240c810f")]
[PInvokeData("Shobjidl.h", MSDNShortId = "802d547f-41c2-4c4a-9f07-be615d7b86eb")]
public interface IExplorerBrowserEvents
{
/// Notifies clients of a pending Explorer browser navigation to a Shell folder.
///
/// Type: PCIDLIST_ABSOLUTE
/// A PIDL that specifies the folder.
///
///
/// Type: HRESULT
/// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
///
///
///
/// Explorer browser calls this method before it navigates to a folder, that is, before calling
/// IExplorerBrowserEvents::OnNavigationFailed or IExplorerBrowserEvents::OnNavigationComplete.
///
/// Returning any failure code from this method, including E_NOTIMPL, will cancel the navigation.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shobjidl_core/nf-shobjidl_core-iexplorerbrowserevents-onnavigationpending
// HRESULT OnNavigationPending( PCIDLIST_ABSOLUTE pidlFolder );
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
[PreserveSig]
HRESULT OnNavigationPending([In] IntPtr pidlFolder);
/// Notifies clients that the view of the Explorer browser has been created and can be modified.
///
/// Type: IShellView*
/// A pointer to an IShellView.
///
///
/// Type: HRESULT
/// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
///
///
/// An Explorer browser calls this method to enable the client to perform any modifications to the Explorer browser view before
/// it is shown; for example, to set view modes or folder flags.
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shobjidl_core/nf-shobjidl_core-iexplorerbrowserevents-onviewcreated
// HRESULT OnViewCreated( IShellView *psv );
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
[PreserveSig]
HRESULT OnViewCreated([In] IShellView psv);
/// Notifies clients that the Explorer browser has successfully navigated to a Shell folder.
///
/// Type: PCIDLIST_ABSOLUTE
/// A PIDL that specifies the folder.
///
///
/// Type: HRESULT
/// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
///
///
/// This method is called after method IExplorerBrowserEvents::OnViewCreated, assuming a successful view creation.
///
/// After a navigation and view creation, either IExplorerBrowserEvents::OnNavigationComplete or
/// IExplorerBrowserEvents::OnNavigationFailed is called depending on whether the destination could be navigated to. For example,
/// a failure to navigate includes a destination that is not reached either because there is no route to the path or the user has canceled.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shobjidl_core/nf-shobjidl_core-iexplorerbrowserevents-onnavigationcomplete
// HRESULT OnNavigationComplete( PCIDLIST_ABSOLUTE pidlFolder );
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
[PreserveSig]
HRESULT OnNavigationComplete([In] IntPtr pidlFolder);
/// Notifies clients that the Explorer browser has failed to navigate to a Shell folder.
///
/// Type: PCIDLIST_ABSOLUTE
/// A PIDL that specifies the folder.
///
///
/// Type: HRESULT
/// If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
///
///
/// This method is called after method IExplorerBrowserEvents::OnViewCreated, assuming a successful view creation.
///
/// After a navigation and view creation, either IExplorerBrowserEvents::OnNavigationComplete or
/// IExplorerBrowserEvents::OnNavigationFailed is called, depending on whether the destination could be navigated to. For
/// example, a failure to navigate includes a destination that is not reached either because there is no route to the path or the
/// user has canceled.
///
///
// https://docs.microsoft.com/en-us/windows/desktop/api/shobjidl_core/nf-shobjidl_core-iexplorerbrowserevents-onnavigationfailed
// HRESULT OnNavigationFailed( PCIDLIST_ABSOLUTE pidlFolder );
[MethodImpl(MethodImplOptions.InternalCall, MethodCodeType = MethodCodeType.Runtime)]
[PreserveSig]
HRESULT OnNavigationFailed([In] IntPtr pidlFolder);
}
/// Extension method to simplify using the method.
/// Type of the interface to get.
/// An instance.
/// Receives the interface pointer requested in .
public static T GetCurrentView(this IExplorerBrowser eb) where T : class => (T)eb.GetCurrentView(typeof(T).GUID);
/// The ExplorerBrowser class is the base CoClass for all I ExplorerBrowser interfaces.
[ComImport, Guid("71f96385-ddd6-48d3-a0c1-ae06e8b055fb"), ClassInterface(ClassInterfaceType.None)]
[PInvokeData("Shobjidl.h", MSDNShortId = "da2cf5d4-5a68-4d18-807b-b9d4e2712c10")]
public class ExplorerBrowser { }
}
}