GetProcessReference function (shlwapi.h)

Retrieves the process-specific object supplied by SetProcessReference, incrementing the reference count to keep the process alive.

Syntax

LWSTDAPI GetProcessReference(
  [out] IUnknown **punk
);

Parameters

[out] punk

The address of a pointer that, when this function returns successfully, points to the object supplied to the process by SetProcessReference. Your application is responsible for freeing this resource when it is no longer needed.

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

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 Windows 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.

GetProcessReference allows components that run in a host process to hold a reference on the host process. GetProcessReference 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 (*punk)->Release to release the host's reference and allow the process to terminate.

Requirements

See also

SHGetInstanceExplorer

SetProcessReference

Windows API Sets