Export (0) Print
Expand All
0 out of 1 rated this helpful - Rate this topic

GetProcessReference function

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

Syntax


LWSTDAPI GetProcessReference(
  _Out_  IUnknown **punk
);

Parameters

punk [out]

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.

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 from an application which had previously called SetProcessReference to set a process reference.

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Shlwapi.h

Library

Shlwapi.lib

DLL

Api-ms-win-shcore-thread-L1-1-0.dll

See also

SetProcessReference
SHGetInstanceExplorer
Windows API Sets

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.