ETimezoneCache

## ETimezoneCache ETimezoneCache — An interface for caching time zone data |

## Synopsis

    #include <libecal/libecal.h>

                        ETimezoneCache;
    struct              ETimezoneCacheInterface;
    void                e_timezone_cache_add_timezone       (ETimezoneCache *cache,
                                                             icaltimezone *zone);
    icaltimezone *      e_timezone_cache_get_timezone       (ETimezoneCache *cache,
                                                             const gchar *tzid);
    GList *             e_timezone_cache_list_timezones     (ETimezoneCache *cache);

## Object Hierarchy

      GInterface
       +----ETimezoneCache

## Prerequisites

ETimezoneCache requires GObject.

## Known Implementations

ETimezoneCache is implemented by ECalClient.

## Signals

      "timezone-added"                                 : Run First

## Description

Several classes (both client-side and server-side) cache icaltimezone instances internally, indexed by their TZID strings. Classes which do this should implement ETimezoneCacheInterface to provide a consistent API for accessing time zone data.

## Details

### ETimezoneCache

    typedef struct _ETimezoneCache ETimezoneCache;

Since 3.8

### struct ETimezoneCacheInterface

    struct ETimezoneCacheInterface {
    	GTypeInterface parent_interface;

    	/* Methods */
    	void		(*add_timezone)		(ETimezoneCache *cache,
    						 icaltimezone *zone);
    	icaltimezone * (*get_timezone)		(ETimezoneCache *cache,
    						 const gchar *tzid);
    	GList *		(*list_timezones) (ETimezoneCache *cache);

    	/* Signals */
    	void		(*timezone_added) (ETimezoneCache *cache,
    						 icaltimezone *zone);
    };

Since 3.8

### e_timezone_cache_add_timezone ()

    void                e_timezone_cache_add_timezone       (ETimezoneCache *cache,
                                                             icaltimezone *zone);

Adds a copy of `zone` to `cache` and emits a "timezone-added" signal. The `cache` will use the TZID string returned by `icaltimezone_get_tzid()` as the lookup key, which can be passed to `e_timezone_cache_get_timezone()` to obtain `zone` again.

If the `cache` already has an icaltimezone with the same TZID string as `zone`, the `cache` will remain unchanged to avoid invalidating any icaltimezone pointers which may have already been returned through `e_timezone_cache_get_timezone()`.

`cache` : | an ETimezoneCache
`zone` : | an icaltimezone

Since 3.8

### e_timezone_cache_get_timezone ()

    icaltimezone *      e_timezone_cache_get_timezone       (ETimezoneCache *cache,
                                                             const gchar *tzid);

Obtains an icaltimezone by its TZID string. If no match is found, the function returns `NULL`. The returned icaltimezone is owned by the `cache` and should not be modified or freed.

`cache` : | an ETimezoneCache
`tzid` : | the TZID of a timezone
Returns : | an icaltimezone, or `NULL`

Since 3.8

### e_timezone_cache_list_timezones ()

    GList *             e_timezone_cache_list_timezones     (ETimezoneCache *cache);

Returns a list of icaltimezone instances that were explicitly added to the `cache` through `e_timezone_cache_add_timezone()`. In particular, any built-in time zone data that `e_timezone_cache_get_timezone()` may use to match a TZID string is excluded from the returned list.

Free the returned list with `g_list_free()`. The list elements are owned by the `cache` and should not be modified or freed.

`cache` : | an ETimezoneCache
Returns : | a GList of icaltimezone instances. [transfer container][element-type icaltimezone]

Since 3.8

## Signal Details

### The `"timezone-added"` signal

    void                user_function                      (ETimezoneCache *cache,
                                                            gpointer        zone,
                                                            gpointer        user_data)      : Run First

Emitted when a new icaltimezone is added to `cache`.

`cache` : | the ETimezoneCache which emitted the signal
`zone` : | the newly-added icaltimezone
`user_data` : | user data set when the signal handler was connected.