Edit

SHSetInstanceExplorer function (shlobj_core.h)

  • Article

Provides an interface that allows hosted Shell extensions and other components to prevent their host process from closing prematurely. The host process is typically Windows Explorer or Windows Internet Explorer, but this function can also be used by other applications.

Syntax

void SHSetInstanceExplorer(
  [in, optional] IUnknown *punk
);

Parameters

[in, optional] punk

Type: IUnknown*

A pointer to a free-threaded IUnknown. Components can use this interface (through SHGetInstanceExplorer) to prevent the host process from terminating. This value can be NULL, in which case the process reference is no longer made available to components.

Return value

None

Remarks

Windows Explorer and Internet Explorer can use SHSetInstanceExplorer to allow components such as Shell extensions to extend the lifetime of the process. Other applications can also use SHSetInstanceExplorer to allow for the same capability. For instance, the browser message loop and the proxy desktop use SHSetInstanceExplorer to let other threads extend their lifetime.

Applications other than Windows Explorer and Internet Explorer that call this function might encounter compatibility problems because some components use SHGetInstanceExplorer to detect whether they are being hosted from within Windows Explorer or Internet Explorer.

The interface pointer passed to SHSetInstanceExplorer must reference a free-threaded object.

Each time a component calls SHGetInstanceExplorer, the system calls the AddRef method before returning the interface pointer to the calling component. The component then calls the IUnknown::Release method when processing is complete. The process that calls SHSetInstanceExplorer must not terminate while the reference count of the provided interface pointer is nonzero.

For further information on how components use the process references, see SHGetInstanceExplorer.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header shlobj_core.h (include Shlobj.h)
Library Shell32.lib
DLL Shell32.dll (version 5.0 or later)
API set ext-ms-win-shell-shell32-l1-2-1 (introduced in Windows 10, version 10.0.10240)

See also

SHGetInstanceExplorer