IThumbnailCache::GetThumbnail method

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

pShellItem [in]

Type: IShellItem*

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

cxyRequestedThumbSize [in]

Type: UINT

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

flags [in]

Type: WTS_FLAGS

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

ppvThumb [out, optional]

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.

pOutFlags [out, optional]

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.

pThumbnailID [out, optional]

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 codeDescription
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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Thumbcache.h

IDL

Thumbcache.idl

See also

IThumbnailCache
IShellItemImageFactory::GetImage

 

 

Show: