class KIOCache

Basic functionality for an on-disk cache. More...

Definition#include <kio_cache.h>
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Methods

Public Static Methods

Protected Static Methods


Detailed Description

KIOCache provides basic functionality to maintain a local on-disk cache for remote documents. KIOCache provides methods to check if a document is in cache and valid (i.e. not yet expired), if a certain URL can be cached at all, to retrieve documents and additional data (such as mime type or expiration date) from cache, to insert documents into the cache and finally to save the cache to and load it from disk and to clear the cache. Some additional methods cover cache settings like which documents should be cached, how to handle documents without explicit expiration date and so on.

Right now, only documents retrieved by the HTTP protocol can be cached, but don't depend on this, this may (and most probably will) change in future.

KIOCache should not be used directly to perform cached IO, the recommended way to access documents from the cache is by using KIOCachedJob. This class provides transparent access to cached documents and handles all the tedious details such as checking if a document is in cache and valid (and retrieving it from the source if not) for you.

void enableCache ( bool enable )
[static]

Enables or disables the cache.

void enableSaveCache ( bool enable )
[static]

Enables or disables saving the cache.

bool isEnabled ()
[static]

Check enable status

void readConfig (KConfig &config)
[static]

Reads the cache configuration from config. Cache config entries are expected in section [Cache].

KConfig & storeConfig (KConfig &config)
[static]

Stores the cache configuration in config. Cache config entries are written to section [Cache]. The modified KConfig object is returned.

bool readCache ()
[static]

Reads the stored cache content from disk. Actually, only the info on which documents are in cache and where they are stored on disk is read, the actual document content is not read until it is needed.

Cache info is stored as a KDE config file. Every cache entry has its own section [Cacheentry #], where # is the number of the entry, starting with 1. Note that these numbers are only used to create unique section names when writing the cache, they have nothing to do with local file names for the cached document's content. Cache entry numbers must be consecutive for readCache() to work correctly. If there are numbers missing, only entries up to the first missing number will be read back.

return TRUE on success, FALSE if nothing can be read back.

bool storeCache ()
[static]

Writes the cache content to disk in a form that is understood by readCache and creates an index.html file in the cache directory reflecting the current cache content.

Note that some part of the cache content (namely the cached documents) will be written immediately when a document is entered into cache, but other associated data will be kept in memory. After a successful storeCache() however the complete cache content at the time of calling is guaranteed to be on disk.

Returns: TRUE on success, FALSE if the cache content cannot be stored.

QString storeIndex ()
[static]

Returns: the full path of the written index file or an empty string in case of an error.

bool clear ()
[static]

Clears the cache.

QString htmlIndex ()
[static]

Returns a QString containing an HTML document which describes the current cache contents. Useful for presenting in an HTML widget or for storing as index.html file in the cache directory.

bool isValid (const QString &url)
[static]

Check if the document referenced by url is in cache and the cached copy is valid, i.e. not yet expired. Use isCached if you want to check for cached documents that may already have expired.

bool isCached (const QString &url)
[static]

Check if the document referenced by url is in cache. This returns true even if the document is no longer valid. Use

See also: isValid, if, you, want, to, check, document, validity.

const KIOCacheEntry& lookup (const QString &url)
[static]

Get the document referenced by url from the cache. If there is no matching document in cache, an empty KIOCacheEntry is returned. Note that a returned document may no longer be valid, use isValid to check for validity.

bool isCacheable (const QString &_url)
[static]

Put a document into the cache. At least the url field (see KIOCacheEntry) of entry must be set to a (syntactically) correct url. The document will be stored in cache if its URL is cacheable (see isCacheable) and if the document has not yet expired (as indicated by entry->expiresAt()).

Note: entry must point to a KIOCacheEntry allocated with new and may not be deleted or modified by the caller if insert() returns TRUE. KIOCache stores this pointer in its internal dictionary in this case. If insert() returns FALSE however, the caller is responsible for deleting entry.

/** Indicates if the document referenced by url may be stored in cache at all. The test is based on the URL only, document content, expiration date or other information is not used. Hence, a document may be rejected by insert even if isCacheable returned TRUE, e.g. because it has already expired at the time insert is called for this document.

Currently, isCacheable returns TRUE if the protocol part of url is listed in cacheProtocols and the hostname part is not listed in excludeHosts. These settings are user configurable.

In future, isCacheable probably will be extended to check other criteria as well.

Returns: FALSE if the document referenced by URL may not be stored in cache, TRUE otherwise.

const QString& cacheRoot ()
[static]

Returns the name of the directory where all the cached files reside.

QString trimURL (const QString &url)
[static]

Trim url, that is remove all parts of url that should not be used in the cache key. Right now, only the reference part is removed, so 'http://www.somewhere.org/something#index_1' and 'http://www.somewhere.org/something#index_2' will both be cached as 'http://www.somewhere.org/something'.

Returns: the trimmed URL

QDateTime defaultExpire (const KIOCacheEntry *entry)
[protected static]

Calculate a default expiration date time for entry based on user settings and the date fields that are set in entry.

Returns: A default expiration date and time.

QString localKey (const KIOCacheEntry *entry)
[protected static]

Calculate a local file name for the document in entry. This local file name consists of the prefix 'entry-', the current date and time, a '.', a sequence number, another '.' and the filename part of the documents URL.


Generated by: root@tantive.terraplex.com on Sun Feb 27 17:39:31 2000, using kdoc 2.0a33.