CamelDataCache: Camel Reference Manual

## CamelDataCache CamelDataCache |

## Functions

gboolean | (*CamelDataCacheRemoveFunc) ()
CamelDataCache * | camel_data_cache_new ()
const gchar * | camel_data_cache_get_path ()
void | camel_data_cache_set_path ()
gboolean | camel_data_cache_get_expire_enabled ()
void | camel_data_cache_set_expire_enabled ()
void | camel_data_cache_set_expire_age ()
void | camel_data_cache_set_expire_access ()
GIOStream * | camel_data_cache_add ()
GIOStream * | camel_data_cache_get ()
gint | camel_data_cache_remove ()
gchar * | camel_data_cache_get_filename ()
void | camel_data_cache_clear ()
void | camel_data_cache_foreach_remove ()

## Properties

gboolean | expire-enabled | Read / Write / Construct
char * | path | Read / Write / Construct

## Object Hierarchy

        GObject
        ╰── CamelDataCache

## Description

## Functions

### CamelDataCacheRemoveFunc ()

    gboolean
    (*CamelDataCacheRemoveFunc) (CamelDataCache *cdc,
                                 const gchar *filename,
                                 gpointer user_data);

A callback called for each found file in the cache, used by `camel_data_cache_foreach_remove()`. The `filename` corresponds to the result of `camel_data_cache_get_filename()`.

#### Parameters

cdc | a CamelDataCache |
filename | a file name found in the cache |
user_data | user data passed to `camel_data_cache_foreach_remove()` |

#### Returns

`TRUE`, to delete the file, `FALSE` to keep in in the cache

Since: 3.26

### camel_data_cache_new ()

    CamelDataCache *
    camel_data_cache_new (const gchar *path,
                          GError **error);

Create a new data cache.

#### Parameters

path | Base path of cache, subdirectories will be created here. |
error | return location for a GError, or `NULL` |

#### Returns

A new cache object, or NULL if the base path cannot be written to.

### camel_data_cache_get_path ()

    const gchar *
    camel_data_cache_get_path (CamelDataCache *cdc);

Returns the path to the data cache.

#### Parameters

cdc | a CamelDataCache |

#### Returns

the path to the data cache

Since: 2.32

### camel_data_cache_set_path ()

    void
    camel_data_cache_set_path (CamelDataCache *cdc,
                               const gchar *path);

Sets the path to the data cache.

#### Parameters

cdc | a CamelDataCache |
path | path to the data cache |

Since: 2.32

### camel_data_cache_get_expire_enabled ()

    gboolean
    camel_data_cache_get_expire_enabled (CamelDataCache *cdc);

Gets whether expire of cache data is enabled.

This is a complementary property for `camel_data_cache_set_expire_age()` and `camel_data_cache_set_expire_access()`, which allows to disable expiry without touching the two values. Having expire enabled, but not have set any of the two times, still behaves like not having expiry enabled.

#### Parameters

cdc | a CamelDataCache |

#### Returns

Whether expire is enabled.

Since: 3.24

### camel_data_cache_set_expire_enabled ()

    void
    camel_data_cache_set_expire_enabled (CamelDataCache *cdc,
                                         gboolean expire_enabled);

Sets whether expire of cache data is enabled.

This is a complementary property for `camel_data_cache_set_expire_age()` and `camel_data_cache_set_expire_access()`, which allows to disable expiry without touching the two values. Having expire enabled, but not have set any of the two times, still behaves like not having expiry enabled.

#### Parameters

cdc | a CamelDataCache |
expire_enabled | a value to set |

Since: 3.24

### 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.

#### Parameters

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.

#### Parameters

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

### camel_data_cache_add ()

    GIOStream *
    camel_data_cache_add (CamelDataCache *cdc,
                          const gchar *path,
                          const gchar *key,
                          GError **error);

Add a new item to the cache, returning a GIOStream to the new item.

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.

The returned GIOStream is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

#### Parameters

cdc | A CamelDataCache |
path | Relative path of item to add. |
key | Key of item to add. |
error | return location for a GError, or `NULL` |

#### Returns

a GIOStream for the new cache item, or `NULL`.

[transfer full]

### camel_data_cache_get ()

    GIOStream *
    camel_data_cache_get (CamelDataCache *cdc,
                          const gchar *path,
                          const gchar *key,
                          GError **error);

Lookup an item in the cache. If the item exists, a GIOStream 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.

The returned GIOStream is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

#### Parameters

cdc | A CamelDataCache |
path | Path to the (sub) cache the item exists in. |
key | Key for the cache item. |
error | return location for a GError, or `NULL` |

#### Returns

a GIOStream for the requested cache item, or `NULL`.

[transfer full]

### camel_data_cache_remove ()

    gint
    camel_data_cache_remove (CamelDataCache *cdc,
                             const gchar *path,
                             const gchar *key,
                             GError **error);

Remove/expire a cache item.

#### Parameters

cdc | A CamelDataCache |
path | Path to the (sub) cache the item exists in. |
key | Key for the cache item. |
error | return location for a GError, or `NULL` |

#### Returns

0 on success, -1 on error

### camel_data_cache_get_filename ()

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

Lookup the filename for an item in the cache

#### Parameters

cdc | A CamelDataCache |
path | Path to the (sub) cache the item exists in. |
key | Key for the cache item. |

#### Returns

The filename for a cache item

Since: 2.26

### camel_data_cache_clear ()

    void
    camel_data_cache_clear (CamelDataCache *cdc,
                            const gchar *path);

Clear cache's content in `path` .

#### Parameters

cdc | a CamelDataCache |
path | Path to the (sub) cache the item exists in. |

Since: 3.2

### camel_data_cache_foreach_remove ()

    void
    camel_data_cache_foreach_remove (CamelDataCache *cdc,
                                     const gchar *path,
                                     CamelDataCacheRemoveFunc func,
                                     gpointer user_data);

Traverses the `cdc` sub-cache identified by `path` and calls `func` for each found file. If the `func` returns `TRUE`, then the file is removed, if `FALSE`, it's kept in the cache.

#### Parameters

cdc | a CamelDataCache |
path | Path to the (sub) cache the items exist in |
func | a callback to call for each found file in the cache. | [scope call][closure user_data]
user_data | user data passed to `func` |

Since: 3.26

## Property Details

### The `“expire-enabled”` property

      “expire-enabled”           gboolean

Owner: CamelDataCache

Flags: Read / Write / Construct

Default value: TRUE

### The `“path”` property

      “path”                     char *

Owner: CamelDataCache

Flags: Read / Write / Construct

Default value: NULL