SHHandleUpdateImage function (shlobj_core.h)

Article
02/22/2024

[SHHandleUpdateImage is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions.]

Handles the SHCNE_UPDATEIMAGE Shell change notification.

Syntax

int SHHandleUpdateImage(
  [in] PCIDLIST_ABSOLUTE pidlExtra
);

Parameters

[in] pidlExtra

Type: PCIDLIST_ABSOLUTE

The index in the system image list that has changed, specified in the pidl2 parameter of IShellChangeNotify::OnChange.

Return value

Type: int

Returns -1 on failure or the index of the changed image list entry on success.

Remarks

Use SHHandleUpdateImage only when the pidl2 parameter received by your change notification callback is non-NULL.

Examples

The following example demonstrates the use of SHHandleUpdateImage in the implementation of IShellChangeNotify::OnChange.

STDMETHODIMP CMyShellChangeNotify::OnChange(LONG lEvent, 
                                            LPCITEMIDLIST pidl1, 
                                            LPCITEMIDLIST pidl2)
{
    HRESULT hr = E_FAIL;
    int iImage;

    switch(lEvent)
    {
        // An image in the system image list has changed.
        case SHCNE_UPDATEIMAGE:
        {
            hr = S_OK;

            if (pidl2)
                iImage = SHHandleUpdateImage(pidl2);
            else
                iImage = *(int UNALIGNED *)((BYTE *)pidl1 + 2);
               
            if (iImage != -1)
            {
                // Process iImage as desired.
            }
            break;
        }
        // Other cases
    }
    return hr;
}

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	shlobj_core.h (include Shlobj.h)
Library	Shell32.lib
DLL	Shell32.dll (version 5.0 or later)