Edit

IExplorerBrowser::BrowseToObject method (shobjidl_core.h)

  • Article

Browses to an object.

Syntax

HRESULT BrowseToObject(
  [in] IUnknown *punk,
  [in] UINT     uFlags
);

Parameters

[in] punk

Type: IUnknown*

A pointer to an object to browse to. If the object cannot be browsed, an error value is returned.

[in] uFlags

Type: UINT

A flag that specifies the category of the pidl. This affects how navigation is accomplished. Must be the value zero, or a bitwise combination of the following values.

SBSP_ABSOLUTE

An absolute PIDL, relative to the desktop.

SBSP_RELATIVE

A relative PIDL, relative to the current folder.

SBSP_PARENT

Browse the parent folder, ignore the PIDL.

SBSP_NAVIGATEBACK

Navigate back, ignore the PIDL.

SBSP_NAVIGATEFORWARD

Navigate forward, ignore the PIDL.

SBSP_KEEPWORDWHEELTEXT

Windows Vista and later. This flag indicates that any search text entered by a WordWheel (the Search box in Windows Explorer) should be preserved during this navigation, so that items at the new location are filtered in the same way they were filtered at the previous location.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

uFlags may be any of the EXPLORER_BROWSER_FILL_FLAGS or any of the flags defined in BrowseObject's wFlags parameter, except for flags that indicate navigation.

This method calls GetIDList and browses to the pidl returned. It operates in the same way as IExplorerBrowser::BrowseToIDList, except that punk cannot be NULL. Standard usage is to browse to an IShellFolder or an IShellItem. An error will be returned if the object passed in cannot be browsed through. An object that can be browsed through implements either IPersistFolder2 or IPersistIDList.

The first navigation of IExplorerBrowser is synchronous. After that, all navigations are asynchronous. As a result, calls to IExplorerBrowser::BrowseToObject will succeed if you properly set up the pending navigation, but that does not guarantee the navigation will succeed. To be informed of success and failure, clients should implement IExplorerBrowserEvents and respond appropriately in OnNavigationComplete and OnNavigationFailed.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header shobjidl_core.h (include Shobjidl.h)