## CamelDataCache

CamelDataCache

## Synopsis

                        CamelDataCache;
    CamelDataCache *    camel_data_cache_new                (const char *path,
                                                             guint32 flags,
                                                             CamelException *ex);
    void                camel_data_cache_set_expire_age     (CamelDataCache *cdc,
                                                             time_t when);
    void                camel_data_cache_set_expire_access  (CamelDataCache *cdc,
                                                             time_t when);
    int                 camel_data_cache_rename             (CamelDataCache *cache,
                                                             const char *old,
                                                             const char *new,
                                                             CamelException *ex);
    CamelStream *       camel_data_cache_add                (CamelDataCache *cdc,
                                                             const char *path,
                                                             const char *key,
                                                             CamelException *ex);
    CamelStream *       camel_data_cache_get                (CamelDataCache *cdc,
                                                             const char *path,
                                                             const char *key,
                                                             CamelException *ex);
    int                 camel_data_cache_remove             (CamelDataCache *cdc,
                                                             const char *path,
                                                             const char *key,
                                                             CamelException *ex);
    int                 camel_data_cache_clear              (CamelDataCache *cache,
                                                             const char *path,
                                                             CamelException *ex);
    gchar *             camel_data_cache_get_filename       (CamelDataCache *cdc,
                                                             const char *path,
                                                             const char *key,
                                                             CamelException *ex);

## Description

## Details

### CamelDataCache

    typedef struct {
    	CamelObject parent_object;

    	struct _CamelDataCachePrivate *priv;

    	char *path;
    	guint32 flags;

    	time_t expire_age;
    	time_t expire_access;
    } CamelDataCache;

### camel_data_cache_new ()

    CamelDataCache *    camel_data_cache_new                (const char *path,
                                                             guint32 flags,
                                                             CamelException *ex);

Create a new data cache.

`path` : | Base path of cache, subdirectories will be created here.
`flags` : | Open flags, none defined.
`ex` : |
Returns : | A new cache object, or NULL if the base path cannot be written to.

### camel_data_cache_set_expire_age ()

    void                camel_data_cache_set_expire_age     (CamelDataCache *cdc,
                                                             time_t when);

Set the cache expiration policy for aged entries.

Items in the cache older than `when` seconds may be flushed at any time. Items are expired in a lazy manner, so it is indeterminate when the items will physically be removed.

Note you can set both an age and an access limit. The age acts as a hard limit on cache entries.

`cdc` : | A CamelDataCache
`when` : | Timeout for age expiry, or -1 to disable.

### camel_data_cache_set_expire_access ()

    void                camel_data_cache_set_expire_access  (CamelDataCache *cdc,
                                                             time_t when);

Set the cache expiration policy for access times.

Items in the cache which haven't been accessed for `when` seconds may be expired at any time. Items are expired in a lazy manner, so it is indeterminate when the items will physically be removed.

Note you can set both an age and an access limit. The age acts as a hard limit on cache entries.

`cdc` : | A CamelDataCache
`when` : | Timeout for access, or -1 to disable access expiry.

### camel_data_cache_rename ()

    int                 camel_data_cache_rename             (CamelDataCache *cache,
                                                             const char *old,
                                                             const char *new,
                                                             CamelException *ex);

Rename a cache path. All cache items accessed from the old path are accessible using the new path.

CURRENTLY UNIMPLEMENTED

`cache` : |
`old` : |
`new` : |
`ex` : |
Returns : | -1 on error.

### camel_data_cache_add ()

    CamelStream *       camel_data_cache_add                (CamelDataCache *cdc,
                                                             const char *path,
                                                             const char *key,
                                                             CamelException *ex);

Add a new item to the cache.

The key and the path combine to form a unique key used to store the item.

Potentially, expiry processing will be performed while this call is executing.

`cdc` : | A CamelDataCache
`path` : | Relative path of item to add.
`key` : | Key of item to add.
`ex` : |
Returns : | A CamelStream (file) opened in read-write mode. The caller must unref this when finished.

### camel_data_cache_get ()

    CamelStream *       camel_data_cache_get                (CamelDataCache *cdc,
                                                             const char *path,
                                                             const char *key,
                                                             CamelException *ex);

Lookup an item in the cache. If the item exists, a stream is returned for the item. The stream may be shared by multiple callers, so ensure the stream is in a valid state through external locking.

`cdc` : | A CamelDataCache
`path` : | Path to the (sub) cache the item exists in.
`key` : | Key for the cache item.
`ex` : |
Returns : | A cache item, or NULL if the cache item does not exist.

### camel_data_cache_remove ()

    int                 camel_data_cache_remove             (CamelDataCache *cdc,
                                                             const char *path,
                                                             const char *key,
                                                             CamelException *ex);

Remove/expire a cache item.

`cdc` : | A CamelDataCache
`path` : |
`key` : |
`ex` : |
Returns : |

### camel_data_cache_clear ()

    int                 camel_data_cache_clear              (CamelDataCache *cache,
                                                             const char *path,
                                                             CamelException *ex);

Clear all items in a given cache path or all items in the cache.

CURRENTLY_UNIMPLEMENTED

`cache` : |
`path` : | Path to clear, or NULL to clear all items in all paths.
`ex` : |
Returns : | -1 on error.

### camel_data_cache_get_filename ()

    gchar *             camel_data_cache_get_filename       (CamelDataCache *cdc,
                                                             const char *path,
                                                             const char *key,
                                                             CamelException *ex);

Lookup the filename for an item in the cache

`cdc` : | A CamelDataCache
`path` : | Path to the (sub) cache the item exists in.
`key` : | Key for the cache item.
`ex` : |
Returns : | The filename for a cache item