SHGetInstanceExplorer function (shlobj_core.h)

Retrieves 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

SHSTDAPI SHGetInstanceExplorer(
  [out] IUnknown **ppunk
);

Parameters

[out] ppunk

Type: IUnknown**

When this function returns successfully, contains the address of the host process' IUnknown interface pointer. This is a free-threaded interface used to prevent the host process from terminating. If the function call fails, this value is set to NULL.

Return value

Type: HRESULT

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

Remarks

There are a number of components, such as Shell extension handlers, that are implemented as DLLs and run in a host process such as Windows Explorer (Explorer.exe) or Internet Explorer (Iexplore.exe). Typically, when the user closes the host process, the component is shut down immediately as well. Such an abrupt termination can create problems for some components. For example, if a component is using a background thread to download data or run user-interface functions, it might need additional time to safely shut itself down.

SHGetInstanceExplorer allows components that run in a host process to hold a reference on the host process. SHGetInstanceExplorer increments the host's reference count and returns a pointer to the host's IUnknown interface. By holding that reference, a component can prevent the host process from closing prematurely. After the component has completed its necessary processing, it should call (*ppunk)->Release to release the host's reference and allow the process to terminate.

Requirements