GNOME.org
 

[evolution-data-server] Add ETimezoneCache interface.

commit 1cc260c6205a5c07d536b910947093f26734922a
Author: Matthew Barnes <mbarnes redhat com>
Date:   Wed Jan 2 14:26:14 2013 -0500

    Add ETimezoneCache interface.
    
    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.

 calendar/libecal/Makefile.am                       |    8 +-
 calendar/libecal/e-timezone-cache.c                |  147 ++++++++++++++++++++
 calendar/libecal/e-timezone-cache.h                |   82 +++++++++++
 calendar/libecal/libecal.h                         |    3 +-
 docs/reference/calendar/libecal/libecal-docs.sgml  |    1 +
 .../calendar/libecal/libecal-sections.txt          |   16 ++
 docs/reference/calendar/libecal/libecal.types      |    1 +
 7 files changed, 255 insertions(+), 3 deletions(-)
---
diff --git a/calendar/libecal/Makefile.am b/calendar/libecal/Makefile.am
index 69f4d22..8c24537 100644
--- a/calendar/libecal/Makefile.am
+++ b/calendar/libecal/Makefile.am
@@ -48,7 +48,9 @@ libecal_1_2_la_SOURCES =			\
 	e-cal-system-timezone.h			\
 	e-cal-util.c				\
 	e-cal-view.c				\
-	e-cal-view-private.h
+	e-cal-view-private.h			\
+	e-timezone-cache.c			\
+	$(NULL)
 
 libecal_1_2_la_LIBADD = 					\
 	$(top_builddir)/libedataserver/libedataserver-1.2.la 	\
@@ -76,7 +78,9 @@ libecalinclude_HEADERS =	\
 	e-cal-system-timezone.h	\
 	e-cal-types.h		\
 	e-cal-util.h		\
-	e-cal-view.h
+	e-cal-view.h		\
+	e-timezone-cache.h	\
+	$(NULL)
 
 %-$(API_VERSION).pc: %.pc
 	 cp $< $@
diff --git a/calendar/libecal/e-timezone-cache.c b/calendar/libecal/e-timezone-cache.c
new file mode 100644
index 0000000..4952c22
--- /dev/null
+++ b/calendar/libecal/e-timezone-cache.c
@@ -0,0 +1,147 @@
+/*
+ * e-timezone-cache.c
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with the program; if not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+/**
+ * SECTION: e-timezone-cache
+ * @include: libecal/libecal.h
+ * @short_description: An interface for caching time zone data
+ *
+ * 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.
+ **/
+
+#include "e-timezone-cache.h"
+
+G_DEFINE_INTERFACE (
+	ETimezoneCache,
+	e_timezone_cache,
+	G_TYPE_OBJECT)
+
+static void
+e_timezone_cache_default_init (ETimezoneCacheInterface *interface)
+{
+	/**
+	 * ETimezoneCache::timezone-added:
+	 * @cache: the #ETimezoneCache which emitted the signal
+	 * @zone: the newly-added #icaltimezone
+	 *
+	 * Emitted when a new #icaltimezone is added to @cache.
+	 **/
+	g_signal_new (
+		"timezone-added",
+		G_OBJECT_CLASS_TYPE (interface),
+		G_SIGNAL_RUN_FIRST,
+		G_STRUCT_OFFSET (ETimezoneCacheInterface, timezone_added),
+		NULL, NULL,
+		g_cclosure_marshal_VOID__POINTER,
+		G_TYPE_NONE, 1,
+		G_TYPE_POINTER);
+}
+
+/**
+ * e_timezone_cache_add_timezone:
+ * @cache: an #ETimezoneCache
+ * @zone: an #icaltimezone
+ *
+ * Adds a copy of @zone to @cache and emits a
+ * #ETimezoneCache::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().
+ *
+ * Since: 3.8
+ **/
+void
+e_timezone_cache_add_timezone (ETimezoneCache *cache,
+                               icaltimezone *zone)
+{
+	ETimezoneCacheInterface *interface;
+
+	g_return_if_fail (E_IS_TIMEZONE_CACHE (cache));
+	g_return_if_fail (zone != NULL);
+
+	interface = E_TIMEZONE_CACHE_GET_INTERFACE (cache);
+	g_return_if_fail (interface->add_timezone != NULL);
+
+	interface->add_timezone (cache, zone);
+}
+
+/**
+ * e_timezone_cache_get_timezone:
+ * @cache: an #ETimezoneCache
+ * @tzid: the TZID of a timezone
+ *
+ * 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.
+ *
+ * Returns: an #icaltimezone, or %NULL
+ *
+ * Since: 3.8
+ **/
+icaltimezone *
+e_timezone_cache_get_timezone (ETimezoneCache *cache,
+                               const gchar *tzid)
+{
+	ETimezoneCacheInterface *interface;
+
+	g_return_val_if_fail (E_IS_TIMEZONE_CACHE (cache), NULL);
+	g_return_val_if_fail (tzid != NULL, NULL);
+
+	interface = E_TIMEZONE_CACHE_GET_INTERFACE (cache);
+	g_return_val_if_fail (interface->get_timezone != NULL, NULL);
+
+	return interface->get_timezone (cache, tzid);
+}
+
+/**
+ * e_timezone_cache_list_timezones:
+ * @cache: an #ETimezoneCache
+ *
+ * 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.
+ *
+ * Returns: (transfer container) (element-type icaltimezone): a #GList of
+ *          #icaltimezone instances
+ *
+ * Since: 3.8
+ **/
+GList *
+e_timezone_cache_list_timezones (ETimezoneCache *cache)
+{
+	ETimezoneCacheInterface *interface;
+
+	g_return_val_if_fail (E_IS_TIMEZONE_CACHE (cache), NULL);
+
+	interface = E_TIMEZONE_CACHE_GET_INTERFACE (cache);
+	g_return_val_if_fail (interface->list_timezones != NULL, NULL);
+
+	return interface->list_timezones (cache);
+}
+
diff --git a/calendar/libecal/e-timezone-cache.h b/calendar/libecal/e-timezone-cache.h
new file mode 100644
index 0000000..be57cbc
--- /dev/null
+++ b/calendar/libecal/e-timezone-cache.h
@@ -0,0 +1,82 @@
+/*
+ * e-timezone-cache.h
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) version 3.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with the program; if not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+#if !defined (__LIBECAL_H_INSIDE__) && !defined (LIBECAL_COMPILATION)
+#error "Only <libecal/libecal.h> should be included directly."
+#endif
+
+#ifndef E_TIMEZONE_CACHE_H
+#define E_TIMEZONE_CACHE_H
+
+#include <glib-object.h>
+#include <libical/ical.h>
+
+/* Standard GObject macros */
+#define E_TYPE_TIMEZONE_CACHE \
+	(e_timezone_cache_get_type ())
+#define E_TIMEZONE_CACHE(obj) \
+	(G_TYPE_CHECK_INSTANCE_CAST \
+	((obj), E_TYPE_TIMEZONE_CACHE, ETimezoneCache))
+#define E_IS_TIMEZONE_CACHE(obj) \
+	(G_TYPE_CHECK_INSTANCE_TYPE \
+	((obj), E_TYPE_TIMEZONE_CACHE))
+#define E_TIMEZONE_CACHE_GET_INTERFACE(obj) \
+	(G_TYPE_INSTANCE_GET_INTERFACE \
+	((obj), E_TYPE_TIMEZONE_CACHE, ETimezoneCacheInterface))
+
+G_BEGIN_DECLS
+
+/**
+ * ETimezoneCache:
+ *
+ * Since: 3.8
+ **/
+typedef struct _ETimezoneCache ETimezoneCache;
+typedef struct _ETimezoneCacheInterface ETimezoneCacheInterface;
+
+/**
+ * ETimezoneCacheInterface:
+ *
+ * Since: 3.8
+ **/
+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);
+};
+
+GType		e_timezone_cache_get_type	(void) G_GNUC_CONST;
+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);
+
+G_END_DECLS
+
+#endif /* E_TIMEZONE_CACHE_H */
+
diff --git a/calendar/libecal/libecal.h b/calendar/libecal/libecal.h
index cb7ab65..eb4b7c1 100644
--- a/calendar/libecal/libecal.h
+++ b/calendar/libecal/libecal.h
@@ -23,6 +23,7 @@
 
 #include <libedataserver/libedataserver.h>
 
+#include <libecal/e-cal.h>
 #include <libecal/e-cal-check-timezones.h>
 #include <libecal/e-cal-client-view.h>
 #include <libecal/e-cal-client.h>
@@ -34,7 +35,7 @@
 #include <libecal/e-cal-types.h>
 #include <libecal/e-cal-util.h>
 #include <libecal/e-cal-view.h>
-#include <libecal/e-cal.h>
+#include <libecal/e-timezone-cache.h>
 
 #undef __LIBECAL_H_INSIDE__
 
diff --git a/docs/reference/calendar/libecal/libecal-docs.sgml b/docs/reference/calendar/libecal/libecal-docs.sgml
index 2ac25cc..cc84b66 100644
--- a/docs/reference/calendar/libecal/libecal-docs.sgml
+++ b/docs/reference/calendar/libecal/libecal-docs.sgml
@@ -19,6 +19,7 @@
     <xi:include href="xml/e-cal-util.xml"/>
     <xi:include href="xml/e-cal-system-timezone.xml"/>
     <xi:include href="xml/e-cal-check-timezones.xml"/>
+    <xi:include href="xml/e-timezone-cache.xml"/>
   </chapter>
 
   <chapter>
diff --git a/docs/reference/calendar/libecal/libecal-sections.txt b/docs/reference/calendar/libecal/libecal-sections.txt
index e174fc2..5a51b22 100644
--- a/docs/reference/calendar/libecal/libecal-sections.txt
+++ b/docs/reference/calendar/libecal/libecal-sections.txt
@@ -523,3 +523,19 @@ ECalViewPrivate
 e_cal_view_new
 </SECTION>
 
+<SECTION>
+<FILE>e-timezone-cache</FILE>
+<TITLE>ETimezoneCache</TITLE>
+ETimezoneCache
+ETimezoneCacheInterface
+e_timezone_cache_add_timezone
+e_timezone_cache_get_timezone
+e_timezone_cache_list_timezones
+<SUBSECTION Standard>
+E_TIMEZONE_CACHE
+E_IS_TIMEZONE_CACHE
+E_TYPE_TIMEZONE_CACHE
+E_TIMEZONE_CACHE_GET_INTERFACE
+e_timezone_cache_get_type
+</SECTION>
+
diff --git a/docs/reference/calendar/libecal/libecal.types b/docs/reference/calendar/libecal/libecal.types
index 1e53d31..526da59 100644
--- a/docs/reference/calendar/libecal/libecal.types
+++ b/docs/reference/calendar/libecal/libecal.types
@@ -5,3 +5,4 @@ e_cal_client_get_type
 e_cal_client_view_get_type
 e_cal_component_get_type
 e_cal_view_get_type
+e_timezone_cache_get_type
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]