IShellIconOverlay::GetOverlayIndex method

Gets the overlay index in the system image list.

Syntax


HRESULT GetOverlayIndex(
  [in]      PCUITEMID_CHILD pidl,
  [in, out] int             *pIndex
);

Parameters

pidl [in]

Type: PCUITEMID_CHILD

Pointer to an ITEMIDLIST structure that identifies the object whose icon is being displayed.

pIndex [in, out]

Type: int*

Pointer to a value that states the overlay index (one-based) in the system image list. This index is equivalent to the iOverlay value that is specified when you add an overlay image to a private image list with the ImageList::SetOverlayImage function.

Return value

Type: HRESULT

This method can return one of these values.

Return codeDescription
S_OK

The index of an overlay was found.

S_FALSE

No overlay exists for this file.

E_FAIL

The PIDL is invalid.

E_INVALIDARG

The argument is invalid, for example, if pIndex is NULL.

E_PENDING

The calling application passed OI_ASYNC to signify that the operation of calculating the overlay index will take some time.

 

Remarks

To retrieve the overlay index in the system image list, call SHGetIconOverlayIndex.

If you set pIndex to point to OI_ASYNC when you call this method, the Shell icon overlay handler might return E_PENDING instead of storing the overlay index in pIndex. This return value indicates that computing the overlay is a slow operation and should be handled in the background. When an IShellIconOverlay implementation returns E_PENDING, it is called back on a background worker thread without the OI_ASYNC flag. If you do not use OI_ASYNC when you call GetOverlayIndex, the overlay handler must compute the overlay index and store the value in pIndex before returning.

Requirements

Minimum supported client

Windows 2000 Professional, Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Shlobj.h

DLL

Shell32.dll (version 5.0 or later)

See also

IShellIconOverlay

 

 

Show: