All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
pdftron::PDF::DocumentPreviewCache Class Reference

#include <DocumentPreviewCache.h>

Public Types

enum  preview_result {
  e_failure, e_success, e_security_error, e_cancel,
typedef void(* PreviewHandler )(preview_result result, const char *utf8_filepath, void *custom_data)

Static Public Member Functions

static void Initialize (UInt64 max_cache_bytes, double max_disk_percentage)
static void GetBitmapWithPath (const UString &filepath, UInt32 min_x_size, UInt32 min_y_size, PreviewHandler proc, void *custom_data)
static void CancelAllRequests ()
static void CancelRequest (const UString &filepath)
static void IrrelevantChangeMade (const UString &filepath)
static void ClearCache ()

Detailed Description


DocumentPreviewCache is a persistent cache that provides thumbnails for browsing in PDFNet. The cache is placed in the sub-directory 'trn_DocumentPreviewCache' of the PDFNet Resources folder, which can be set by calling PDFNet::SetPersistentCachePath. In the case the PersistentCachePath is not set the files will be stored in the system temp path (PDFNet::GetSystemTempPath()). The cache will be used by any PDFNet process that uses the resource path. If more than one PDFNet process is running concurrently, the first process to acquire a lock on the cache will use it. Subsequent processes will not read or modify the cache.

DocumentPreviewCache will store references to generated JPG thumbnails and keeps track of the dimensions of the thumbnail and the filesize of the specific pdf documents. Furthermore it takes care that the size constraints (max_cache_bytes, max_disk_percentage) are met and in cleans the oldest (in terms of last request) thumbs from the cache in case of a overflow.

If the user requests a file that is already in the cache and the requested thumb dimensions are smaller or equal than the ones of the cache-version the URL of the cached thumb is given back. If the dimensions are bigger the thumb gets rendered again, the old thumb gets replaced and the URL is given back.

If the size of the pdf document changes the thumb will be rendered again even when there is a version of that thumbnail in the cache. In case that the user wants to suppress the re-rendering of that specific thumb (e.g. when the change on the pdf document was made on another page than the first page which is used for the thumb), IrrelevantChangeMade has to be called.

Definition at line 44 of file DocumentPreviewCache.h.

Member Typedef Documentation

typedef void(* pdftron::PDF::DocumentPreviewCache::PreviewHandler)(preview_result result, const char *utf8_filepath, void *custom_data)

Callback for GetBitmap

resultContains the information about the result of GetBitmap
utf8_filepathAn UTF-8, null terminated C-String containing the file path of the retrieved thumbnail. In case of failure utf8_filepath is empty.
custom_dataCustom data specified by the user.

Definition at line 65 of file DocumentPreviewCache.h.

Member Enumeration Documentation

thumb_result contains the valid result states of requesting a thumbnail


The thumbnail could not be retrieved.


Successful retrieval of the thumbnail.


Failure due to password restriction.


The request was cancelled before it was processed.


Failure due to encountering a PDF package.

Definition at line 50 of file DocumentPreviewCache.h.

Member Function Documentation

static void pdftron::PDF::DocumentPreviewCache::CancelAllRequests ( )

CancelAllRequests cancels all pending requests. The ThumbPreviewHandler of each pending request will signal that the thumb could not be found.

static void pdftron::PDF::DocumentPreviewCache::CancelRequest ( const UString filepath)

CancelRequest cancels all pending thumbnail requests associated with 'filepath'. If the cancel request is processed earlier than the path of the thumbnail could be retrieved the respective request will be cancelled and the ThumbPreviewHandler will signal that the thumb could not be found.

filepath- URL of pdf file
static void pdftron::PDF::DocumentPreviewCache::ClearCache ( )

Remove the cache from the disk completely, deleting any thumbnails. You may want to do this if you detect some kind of corruption, or if the user wants to clear out disk space used by your application.

static void pdftron::PDF::DocumentPreviewCache::GetBitmapWithPath ( const UString filepath,
UInt32  min_x_size,
UInt32  min_y_size,
PreviewHandler  proc,
void *  custom_data 

GetBitmap gets the path to the thumbnail in the DocumentPreviewCache associated with the document at 'filepath'. The decision if the thumb should be re-rendered is based on two factors. First if the current version fulfills the minimal dimensions 'min_x_size' x 'min_y_size' and second if the size of the pdf document hasn't changed. To signal an edit of the pdf document without a resulting re-rendering of the thumb see IrrelevantChangeMade.

filepath- The URL of the pdf file.
min_x_size- Minimal width of the thumbnail.
min_y_size- Minimal height of the thumbnail.
proc- A callback function that will be called after the thumbnail is retrieved, or if that retrieval fails.
custom_data- Custom data to be passed to the ThumbPreviewHandler.
static void pdftron::PDF::DocumentPreviewCache::Initialize ( UInt64  max_cache_bytes,
double  max_disk_percentage 

Initialize the thumbnail cache. If the cache already exists, it will shrink to conform to these limits immediately.

max_cache_bytesThe absolute maximum size on disk for the temporary thumbnail cache in bytes.
max_disk_percentageThe maximum percentage of free disk space that the cache can take up (0 - 1.0).
static void pdftron::PDF::DocumentPreviewCache::IrrelevantChangeMade ( const UString filepath)

IrrelevantChangeMade should be called if the size of the pdf file at 'filepath' was changed but the thumbnail should not be re-generated. This should be done when no editing was done on the first page of the document or merely annotations were added on the front page.

filepath- URL of pdf file

The documentation for this class was generated from the following file: