IThumbnailCache interface (thumbcache.h)

Exposes methods for a system thumbnail cache that is shared across applications.

Inheritance

The IThumbnailCache interface inherits from the IUnknown interface. IThumbnailCache also has these types of members:

Methods

The IThumbnailCache interface has these methods.

Remarks

The Thumbnail Cache API is designed to provide applications with a unified method to retrieve and cache thumbnails. In Windows XP, thumbnail caching is done on a per-folder basis, and the cache is maintained in a Thumbs.db file within each folder. While this approach provides spatial locality, it does not support previews and queries across folders. The thumbnail cache in Windows Vista addresses this shortcoming by providing a global cache.

To cache a thumbnail, an application must first obtain an IShellItem that represents the item for which a thumbnail will be obtained, and then pass the IShellItem to a call to IThumbnailCache::GetThumbnail. If the flags parameter to IThumbnailCache::GetThumbnail includes the flag WTS_EXTRACT, and the thumbnail is not already cached, a thumbnail will be extracted and placed in the cache. If the flag WTS_FORCEEXTRACTION is set, the cache is ignored and a new thumbnail is always extracted. See the IThumbnailCache::GetThumbnail topic for more details on the flags passed to IThumbnailCache::GetThumbnail.

If a thumbnail is not already in the cache, it will be automatically extracted from the source file using the existing implementation(s) of IExtractImage or IThumbnailProvider that is registered on the operating system. Your application does not have to provide an implementation of the thumbnail extractor.

When IThumbnailCache::GetThumbnail returns, its pThumbnailID parameter receives a WTS_THUMBNAILID structure that contains the unique ID of the thumbnail. If this ID is saved, it can then be passed to IThumbnailCache::GetThumbnailByID to retrieve the cached thumbnail. Alternatively, IThumbnailCache::GetThumbnail may be called with the WTS_CACHEONLY flag set. In this case, a thumbnail will be returned only if it is already cached. The disadvantage of using IThumbnailCache::GetThumbnail rather than IThumbnailCache::GetThumbnailByID, is that an IShellItem must still be provided.

Multiple threads can be used to access the thumbnail cache to improve performance. IThumbnailCache::GetThumbnail may be called on a higher priority thread with either the WTS_INCACHEONLY or the WTS_FASTEXTRACT flag set, so that cached thumbnails are retrieved immediately. Then if the image is not in the cache, or WTS_LOWQUALITY indicates the cached image was not of ideal quality, a lower priority thread may be used to call IThumbnailCache::GetThumbnail with the WTS_EXTRACT flag set, so that a thumbnail may be extracted.

Requirements