IUnknown_Set function (shlwapi.h)

Changes the value of a Component Object Model (COM) interface pointer and releases the previous interface.


void IUnknown_Set(
  [in, out]      IUnknown **ppunk,
  [in, optional] IUnknown *punk


[in, out] ppunk

Type: IUnknown**

The address of a COM interface pointer to receive the pointer assigned to punk. If the previous value of the pointer is non-NULL, the function releases that interface by calling its IUnkown::Release method.

[in, optional] punk

Type: IUnknown*

The interface pointer to be copied to ppunk. If the value is non-NULL, the function increments the interface's reference count.

Return value



This function mimics the behavior of a smart pointer. Conceptually, the function does the following:

  • Releases the original interface, if ppunk is non-NULL
  • Assigns punk to ppunk
  • Calls IUnknown::AddRef on the interface pointed to by punk, if punk is non-NULL.


void sample()
  IUnknown *punk = NULL;
  IStream* pstm = NULL;

  if (SUCCEEDED(CreateStreamOnHGlobal(NULL, TRUE, &pstm)) {
    // since punk == NULL, this merely copies the value and AddRef()s it
    IUnknown_Set(&punk, pstm);

    if (SUCCEEDED(CreateStreamOnHGlobal(NULL, TRUE, &pstm)) {
      // this call will release the old value of punk before copying the
      // new value and AddRef()ing it
      IUnknown_Set(&punk, pstm);

  // This call will release whatever punk points to, if anything.

  // at this point, punk == NULL


Minimum supported client Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server Windows 2000 Server, Windows Server 2003 [desktop apps only]
Target Platform Windows
Header shlwapi.h
DLL Shlwapi.dll (version 5.0 or later)