** Fixes bug #531713

2008-05-14  Matthew Barnes  <mbarnes@redhat.com>

	** Fixes bug #531713

	* configure.in:
	Split the evolution-data-server version into major/minor/micro
	macros (wow, say that five times fast!) so we can pass them to
	libedataserver/eds-version.c.

	* libedataserver/Makefile.am:
	* libedataserver/eds-version.c:
	* libedataserver/eds-version.h:
	New sources files provide macros and functions for checking the
	version of evolution-data-server.  Would have been handy to have
	in a couple recent API breaks.

	* docs/references/libedataserver:
	Add developer documentation for the new symbols.


svn path=/trunk/; revision=8793

8 files changed, 325 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 15cf6eab4..80771d0cb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,22 @@
+2008-05-14  Matthew Barnes  <mbarnes@redhat.com>
+
+	** Fixes bug #531713
+
+	* configure.in:
+	Split the evolution-data-server version into major/minor/micro
+	macros (wow, say that five times fast!) so we can pass them to
+	libedataserver/eds-version.c.
+
+	* libedataserver/Makefile.am:
+	* libedataserver/eds-version.c:
+	* libedataserver/eds-version.h:
+	New sources files provide macros and functions for checking the
+	version of evolution-data-server.  Would have been handy to have
+	in a couple recent API breaks.
+
+	* docs/references/libedataserver:
+	Add developer documentation for the new symbols.
+
 2008-05-13  Matthew Barnes  <mbarnes@redhat.com>
 
 	* libebackend/libebackend.pc.in: Fix a typo.
diff --git a/configure.in b/configure.in
index c46a96ba4..7fc589199 100644
--- a/configure.in
+++ b/configure.in
@@ -1,7 +1,15 @@
  Process this file with autoconf to produce a configure script.
 AC_PREREQ(2.52)
 
-AC_INIT(evolution-data-server, 2.23.3)
+# Evolution-Data-Server version */
+m4_define([eds_major_version], [2])
+m4_define([eds_minor_version], [23])
+m4_define([eds_micro_version], [3])
+
+m4_define([eds_version],
+          [eds_major_version.eds_minor_version.eds_micro_version])
+
+AC_INIT(evolution-data-server, [eds_version])
 AC_CONFIG_SRCDIR(README)
 
 # Gross hack to enable 'make dist' on automake 1.9+tar 1.14.
@@ -38,6 +46,10 @@ AC_SUBST(API_VERSION)
 AC_DEFINE_UNQUOTED(BASE_VERSION, "$BASE_VERSION", [Base version (Major.Minor)])
 AC_DEFINE_UNQUOTED(API_VERSION, "$API_VERSION", [Api version (Major.Minor)])
 
+EDS_MAJOR_VERSION=eds_major_version
+EDS_MINOR_VERSION=eds_minor_version
+EDS_MICRO_VERSION=eds_micro_version
+
 # Libtool versioning
 LIBEDATASERVER_CURRENT=11
 LIBEDATASERVER_REVISION=0
@@ -87,6 +99,9 @@ LIBEBACKEND_CURRENT=0
 LIBEBACKEND_REVISION=0
 LIBEBACKEND_AGE=0
 
+AC_SUBST(EDS_MAJOR_VERSION)
+AC_SUBST(EDS_MINOR_VERSION)
+AC_SUBST(EDS_MICRO_VERSION)
 AC_SUBST(LIBEDATASERVER_CURRENT)
 AC_SUBST(LIBEDATASERVER_REVISION)
 AC_SUBST(LIBEDATASERVER_AGE)
@@ -1685,6 +1700,7 @@ libdb/Makefile
 libebackend/Makefile
 libebackend/libebackend.pc
 libedataserver/Makefile
+libedataserver/eds-version.h
 libedataserver/libedataserver.pc
 libedataserverui/Makefile
 libedataserverui/libedataserverui.pc
diff --git a/docs/reference/libedataserver/libedataserver-docs.sgml b/docs/reference/libedataserver/libedataserver-docs.sgml
index f9dc8e587..d0a736b62 100644
--- a/docs/reference/libedataserver/libedataserver-docs.sgml
+++ b/docs/reference/libedataserver/libedataserver-docs.sgml
@@ -34,6 +34,7 @@
     <xi:include href="xml/e-util.xml"/>
     <xi:include href="xml/e-url.xml"/>
     <xi:include href="xml/e-xml-hash-utils.xml"/>
+    <xi:include href="xml/eds-version.xml"/>
     <xi:include href="xml/md5-utils.xml"/>
   </chapter>
 
diff --git a/docs/reference/libedataserver/libedataserver-sections.txt b/docs/reference/libedataserver/libedataserver-sections.txt
index 986541f7e..667e7bd39 100644
--- a/docs/reference/libedataserver/libedataserver-sections.txt
+++ b/docs/reference/libedataserver/libedataserver-sections.txt
@@ -610,3 +610,16 @@ e_xml_parse_file
 e_xml_save_file
 e_xml_get_child_by_name
 </SECTION>
+
+<SECTION>
+<FILE>eds-version</FILE>
+<TITLE>Version Information</TITLE>
+eds_major_version
+eds_minor_version
+eds_micro_version
+eds_check_version
+EDS_MAJOR_VERSION
+EDS_MINOR_VERSION
+EDS_MICRO_VERSION
+EDS_CHECK_VERSION
+</SECTION>
diff --git a/docs/reference/libedataserver/tmpl/eds-version.sgml b/docs/reference/libedataserver/tmpl/eds-version.sgml
new file mode 100644
index 000000000..9a173afb2
--- /dev/null
+++ b/docs/reference/libedataserver/tmpl/eds-version.sgml
@@ -0,0 +1,79 @@
+<!-- ##### SECTION Title ##### -->
+Version Information
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### VARIABLE eds_major_version ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### VARIABLE eds_minor_version ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### VARIABLE eds_micro_version ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION eds_check_version ##### -->
+<para>
+
+</para>
+
+@required_major: 
+@required_minor: 
+@required_micro: 
+@Returns: 
+
+
+<!-- ##### MACRO EDS_MAJOR_VERSION ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO EDS_MINOR_VERSION ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO EDS_MICRO_VERSION ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO EDS_CHECK_VERSION ##### -->
+<para>
+
+</para>
+
+@major: 
+@minor: 
+@micro: 
+
+
diff --git a/libedataserver/Makefile.am b/libedataserver/Makefile.am
index 6b111da25..c4a3db268 100644
--- a/libedataserver/Makefile.am
+++ b/libedataserver/Makefile.am
@@ -37,6 +37,7 @@ libedataserver_1_2_la_SOURCES =		\
 	e-xml-utils.c			\
 	e-xml-hash-utils.c		\
 	libedataserver-private.h	\
+	eds-version.c			\
 	md5-utils.c
 
 libedataserver_1_2_la_LIBADD = 				\
@@ -74,6 +75,7 @@ libedataserverinclude_HEADERS =		\
 	e-data-server-util.h		\
 	e-xml-utils.h			\
 	e-xml-hash-utils.h		\
+	eds-version.h			\
 	md5-utils.h
 
 test_source_list_SOURCES = test-source-list.c
@@ -86,6 +88,7 @@ pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = libedataserver-$(API_VERSION).pc
 
 EXTRA_DIST = 						\
-	$(pkgconfig_DATA:-$(API_VERSION).pc=.pc.in)
+	$(pkgconfig_DATA:-$(API_VERSION).pc=.pc.in)	\
+	eds-version.h.in
 
 DISTCLEANFILES = $(pkgconfig_DATA)
diff --git a/libedataserver/eds-version.c b/libedataserver/eds-version.c
new file mode 100644
index 000000000..5a7e22d98
--- /dev/null
+++ b/libedataserver/eds-version.c
@@ -0,0 +1,62 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
+/*
+ * Copyright (C) 2008 Novell, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of version 2 of the GNU Lesser General Public
+ * License as published by the Free Software Foundation.
+ *
+ * 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
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#include "eds-version.h"
+
+const guint eds_major_version = EDS_MAJOR_VERSION;
+const guint eds_minor_version = EDS_MINOR_VERSION;
+const guint eds_micro_version = EDS_MICRO_VERSION;
+
+/**
+ * eds_check_version:
+ * @required_major: the required major version
+ * @required_minor: the required minor version
+ * @required_micro: the required micro version
+ *
+ * Checks that the Evolution-Data-Server library in use is compatible with
+ * the given version.  Generally you would pass in the constants
+ * #EDS_MAJOR_VERSION, #EDS_MINOR_VERSION, #EDS_MICRO_VERSION as the three
+ * arguments to this function.  That produces a check that the library in
+ * use is compatible with the version of Evolution-Data-Server the
+ * application or module was compiled against.
+ *
+ * Returns: %NULL if the Evolution-Data-Server library is compatible with
+ * the given version, or a string describing the version mismatch.  The
+ * returned string is owned by libedataserver and must not be modified or
+ * freed.
+ *
+ * Since: 2.24
+ **/
+const gchar *
+eds_check_version (guint required_major,
+                   guint required_minor,
+                   guint required_micro)
+{
+	gint eds_effective_micro = 100 * EDS_MINOR_VERSION + EDS_MICRO_VERSION;
+	gint required_effective_micro = 100 * required_minor + required_micro;
+
+	if (required_major > EDS_MAJOR_VERSION)
+		return "EDS version too old (major mismatch)";
+	if (required_major < EDS_MAJOR_VERSION)
+		return "EDS version too new (major mismatch)";
+	if (required_effective_micro > eds_effective_micro)
+		return "EDS version too old (micro mismatch)";
+
+	return NULL;
+}
diff --git a/libedataserver/eds-version.h b/libedataserver/eds-version.h
new file mode 100644
index 000000000..72b2d4cfe
--- /dev/null
+++ b/libedataserver/eds-version.h
@@ -0,0 +1,130 @@
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
+/*
+ * Copyright (C) 2008 Novell, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of version 2 of the GNU Lesser General Public
+ * License as published by the Free Software Foundation.
+ *
+ * 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
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#ifndef EDS_VERSION_H
+#define EDS_VERSION_H
+
+#include <glib.h>
+
+/**
+ * EDS_MAJOR_VERSION:
+ *
+ * The major version number of the Evolution-Data-Server library.  Like
+ * eds_major_version(), but from the headers used at application compile
+ * time, rather than from the library linked against at application run
+ * time.
+ *
+ * Since: 2.24
+ **/
+#define EDS_MAJOR_VERSION 2
+
+/**
+ * EDS_MINOR_VERSION:
+ *
+ * The minor version number of the Evolution-Data-Server library.  Like
+ * eds_minor_version(), but from the headers used at application compile
+ * time, rather than from the library linked against at application run
+ * time.
+ *
+ * Since: 2.24
+ **/
+#define EDS_MINOR_VERSION 23
+
+/**
+ * EDS_MICRO_VERSION:
+ *
+ * The micro version number of the Evolution-Data-Server library.  Like
+ * eds_micro_version(), but from the headers used at application compile
+ * time, rather than from the library linked against at application run
+ * time.
+ *
+ * Since: 2.24
+ **/
+#define EDS_MICRO_VERSION 3
+
+/**
+ * EDS_CHECK_VERSION:
+ * @major: the major version number
+ * @minor: the minor version number
+ * @micro: the micro version number
+ *
+ * Checks the version of the Evolution-Data-Server library.  Returns
+ * %TRUE if the version of the EDS header files is the same as or newer
+ * than the passed-in version.
+ *
+ * Since: 2.24
+ **/
+#define EDS_CHECK_VERSION(major,minor,micro) \
+	(EDS_MAJOR_VERSION > (major) || \
+	(EDS_MAJOR_VERSION == (major) && EDS_MINOR_VERSION > (minor)) || \
+	(EDS_MAJOR_VERSION == (major) && EDS_MINOR_VERSION == (minor)) && \
+	 EDS_MICRO_VERSION >= (micro))
+
+G_BEGIN_DECLS
+
+/**
+ * eds_major_version:
+ *
+ * The major version number of the Evolution-Data-Server libraries.
+ * (e.g. in Evolution-Data-Server 2.24.1 this is 2.)
+ *
+ * This variable is in the library, so it represents the EDS library you
+ * have linked against.  Contrast with the EDS_MAJOR_VERSION macro, which
+ * represents the major version of the EDS headers you have included.
+ *
+ * Since: 2.24
+ **/
+extern const guint eds_major_version;
+
+/**
+ * eds_minor_version:
+ *
+ * The minor version number of the Evolution-Data-Server libraries.
+ * (e.g. in Evolution-Data-Server 2.24.1 this is 24.)
+ *
+ * This variable is in the library, so it represents the EDS library you
+ * have linked against.  Contrast with the EDS_MINOR_VERSION macro, which
+ * represents the minor version of the EDS headers you have included.
+ *
+ * Since: 2.24
+ **/
+extern const guint eds_minor_version;
+
+/**
+ * eds_micro_version:
+ *
+ * The micro version number of the Evolution-Data-Server libraries.
+ * (e.g. in Evolution-Data-Server 2.24.1 this is 1.)
+ *
+ * This variable is in the library, so it represents the EDS library you
+ * have linked against.  Contrast with the EDS_MICRO_VERSION macro, which
+ * represents the micro version of the EDS headers you have included.
+ *
+ * Since: 2.24
+ **/
+extern const guint eds_micro_version;
+
+
+const gchar *	eds_check_version		(guint required_major,
+						 guint required_minor,
+						 guint required_micro);
+
+G_END_DECLS
+
+#endif /* EDS_VERSION_H */