GetProcessReference function (shlwapi.h)

Article
01/26/2024

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.

Note If GetProcessReference is successful, the component must release the host's reference when it is no longer needed. Otherwise, all resources associated with the process will remain in memory. The IUnknown interface pointed to by *punk can only be used to release this reference. Components cannot use (*punk)->QueryInterface to request other interface pointers.

GetProcessReference succeeds only if it is called from an application which had previously called SetProcessReference to set a process reference.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	shlwapi.h
Library	Shlwapi.lib
DLL	Api-ms-win-shcore-thread-L1-1-0.dll