Edit

IThumbnailCache::GetThumbnail method (thumbcache.h)

  • Article

Gets a cached thumbnail for a given Shell item.

Syntax

HRESULT GetThumbnail(
  [in]            IShellItem      *pShellItem,
  [in]            UINT            cxyRequestedThumbSize,
  [in]            WTS_FLAGS       flags,
  [out, optional] ISharedBitmap   **ppvThumb,
  [out, optional] WTS_CACHEFLAGS  *pOutFlags,
  [out, optional] WTS_THUMBNAILID *pThumbnailID
);

Parameters

[in] pShellItem

Type: IShellItem*

A pointer to the Shell item for which to retrieve a thumbnail.

[in] cxyRequestedThumbSize

Type: UINT

The requested thumbnail size in pixels. The maximum value is 1024.

[in] flags

Type: WTS_FLAGS

A combination of values from the WTS_FLAGS enumeration. See the Remarks section for rules and a list of possible combinations.

[out, optional] ppvThumb

Type: ISharedBitmap**

The address of an ISharedBitmap pointer that, when this method returns successfully, receives the object used to access the thumbnail. This parameter may be NULL.

[out, optional] pOutFlags

Type: WTS_CACHEFLAGS*

A pointer to a value that, when this method returns successfully, receives a combination of the following flags from the WTS_CACHEFLAGS enumeration.

WTS_DEFAULT (0x00000000)

0x00000000.

WTS_LOWQUALITY (0x00000001)

0x00000001. Set when the returned bitmap dimensions are less than cxyRequestedThumbSize.

WTS_CACHED (0x00000002)

0x00000002. Set when the returned image is in the cache.

[out, optional] pThumbnailID

Type: WTS_THUMBNAILID*

A pointer to a value that, when this method returns successfully, receives a unique ID for the returned thumbnail. This parameter may be NULL, in which case the thumbnail ID is discarded.

Return value

Type: HRESULT

Returns S_OK if successful or a standard COM error value otherwise, including the following:

Return code Description
E_INVALIDARG
 A parameter is invalid.
WTS_E_FAILEDEXTRACTION
 The Shell item does not support thumbnail extraction. For example, .exe or .lnk items.
WTS_E_EXTRACTIONTIMEDOUT
 The extraction took longer than the maximum allowable time. The extraction was not completed.
WTS_E_SURROGATEUNAVAILABLE
 A surrogate process was not available to be used for the extraction process.
WTS_E_FASTEXTRACTIONNOTSUPPORTED
 The WTS_FASTEXTRACT flag was set, but fast extraction is not available.

Remarks

If a thumbnail is extracted, it will be cached unless WTS_EXTRACTDONOTCACHE is specified.

The following combinations are valid for the flags parameter.

WTS_INCACHEONLY
WTS_FASTEXTRACT
WTS_EXTRACT
WTS_EXTRACT | WTS_SLOWRECLAIM
WTS_FORCEEXTRACTION
WTS_FORCEEXTRACTION | WTS_SLOWRECLAIM
WTS_EXTRACTDONOTCACHE
 

GetImage also uses this cache and can provide an easier way to retrieve the thumbnail. However, GetImage is more general and will retrieve an icon as a fallback.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header thumbcache.h

See also

IShellItemImageFactory::GetImage

IThumbnailCache