1 /*
2 * e-timezone-cache.c
3 *
4 * This library is free software: you can redistribute it and/or modify it
5 * under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation.
7 *
8 * This library is distributed in the hope that it will be useful, but
9 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
10 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
11 * for more details.
12 *
13 * You should have received a copy of the GNU Lesser General Public License
14 * along with this library. If not, see <http://www.gnu.org/licenses/>.
15 *
16 */
17
18 /**
19 * SECTION: e-timezone-cache
20 * @include: libecal/libecal.h
21 * @short_description: An interface for caching time zone data
22 *
23 * Several classes (both client-side and server-side) cache #ICalTimezone
24 * instances internally, indexed by their TZID strings. Classes which do
25 * this should implement #ETimezoneCacheInterface to provide a consistent
26 * API for accessing time zone data.
27 **/
28
29 #include "e-timezone-cache.h"
30
G_DEFINE_INTERFACE(ETimezoneCache,e_timezone_cache,G_TYPE_OBJECT)31 G_DEFINE_INTERFACE (
32 ETimezoneCache,
33 e_timezone_cache,
34 G_TYPE_OBJECT)
35
36 static void
37 e_timezone_cache_default_init (ETimezoneCacheInterface *iface)
38 {
39 /**
40 * ETimezoneCache::timezone-added:
41 * @cache: the #ETimezoneCache which emitted the signal
42 * @zone: the newly-added #ICalTimezone
43 *
44 * Emitted when a new #icaltimezone is added to @cache.
45 **/
46 g_signal_new (
47 "timezone-added",
48 G_OBJECT_CLASS_TYPE (iface),
49 G_SIGNAL_RUN_FIRST,
50 G_STRUCT_OFFSET (ETimezoneCacheInterface, timezone_added),
51 NULL, NULL, NULL,
52 G_TYPE_NONE, 1,
53 I_CAL_TYPE_TIMEZONE);
54 }
55
56 /**
57 * e_timezone_cache_add_timezone:
58 * @cache: an #ETimezoneCache
59 * @zone: an #ICalTimezone
60 *
61 * Adds a copy of @zone to @cache and emits an
62 * #ETimezoneCache::timezone-added signal. The @cache will use the TZID
63 * string returned by i_cal_timezone_get_tzid() as the lookup key, which can
64 * be passed to e_timezone_cache_get_timezone() to obtain @zone again.
65 *
66 * If the @cache already has an #ICalTimezone with the same TZID string
67 * as @zone, the @cache will remain unchanged to avoid invalidating any
68 * #ICalTimezone pointers which may have already been returned through
69 * e_timezone_cache_get_timezone().
70 *
71 * Since: 3.8
72 **/
73 void
e_timezone_cache_add_timezone(ETimezoneCache * cache,ICalTimezone * zone)74 e_timezone_cache_add_timezone (ETimezoneCache *cache,
75 ICalTimezone *zone)
76 {
77 ETimezoneCacheInterface *iface;
78
79 g_return_if_fail (E_IS_TIMEZONE_CACHE (cache));
80 g_return_if_fail (zone != NULL);
81
82 iface = E_TIMEZONE_CACHE_GET_INTERFACE (cache);
83 g_return_if_fail (iface->tzcache_add_timezone != NULL);
84
85 iface->tzcache_add_timezone (cache, zone);
86 }
87
88 /**
89 * e_timezone_cache_get_timezone:
90 * @cache: an #ETimezoneCache
91 * @tzid: the TZID of a timezone
92 *
93 * Obtains an #ICalTimezone by its TZID string. If no match is found,
94 * the function returns %NULL. The returned #ICalTimezone is owned by
95 * the @cache and should not be modified or freed.
96 *
97 * Returns: (transfer none) (nullable): an #ICalTimezone, or %NULL
98 *
99 * Since: 3.8
100 **/
101 ICalTimezone *
e_timezone_cache_get_timezone(ETimezoneCache * cache,const gchar * tzid)102 e_timezone_cache_get_timezone (ETimezoneCache *cache,
103 const gchar *tzid)
104 {
105 ETimezoneCacheInterface *iface;
106
107 g_return_val_if_fail (E_IS_TIMEZONE_CACHE (cache), NULL);
108 g_return_val_if_fail (tzid != NULL, NULL);
109
110 iface = E_TIMEZONE_CACHE_GET_INTERFACE (cache);
111 g_return_val_if_fail (iface->tzcache_get_timezone != NULL, NULL);
112
113 return iface->tzcache_get_timezone (cache, tzid);
114 }
115
116 /**
117 * e_timezone_cache_list_timezones:
118 * @cache: an #ETimezoneCache
119 *
120 * Returns a list of #ICalTimezone instances that were explicitly added to
121 * the @cache through e_timezone_cache_add_timezone(). In particular, any
122 * built-in time zone data that e_timezone_cache_get_timezone() may use to
123 * match a TZID string is excluded from the returned list.
124 *
125 * Free the returned list with g_list_free(). The list elements are owned
126 * by the @cache and should not be modified or freed.
127 *
128 * Returns: (transfer container) (element-type ICalTimezone): a #GList of
129 * #ICalTimezone instances
130 *
131 * Since: 3.8
132 **/
133 GList *
e_timezone_cache_list_timezones(ETimezoneCache * cache)134 e_timezone_cache_list_timezones (ETimezoneCache *cache)
135 {
136 ETimezoneCacheInterface *iface;
137
138 g_return_val_if_fail (E_IS_TIMEZONE_CACHE (cache), NULL);
139
140 iface = E_TIMEZONE_CACHE_GET_INTERFACE (cache);
141 g_return_val_if_fail (iface->tzcache_list_timezones != NULL, NULL);
142
143 return iface->tzcache_list_timezones (cache);
144 }
145