[tracker/version-macros: 9/9] libtracker-sparql, common: Added TRACKER_CHECK_VERSION.

[Martyn James Russell <mr src gnome org>]

commit d735db87b96cfefd48f8c5038f35cd6a6232503c
Author: Martyn Russell <martyn lanedo com>
Date:   Thu Mar 31 20:29:41 2011 +0100

    libtracker-sparql, common: Added TRACKER_CHECK_VERSION.
    
    Some work is needed to clean up the documentation, but it does exist.

 configure.ac                                       |   11 ++++
 docs/reference/libtracker-sparql/Makefile.am       |    8 ++--
 .../libtracker-sparql/libtracker-sparql-docs.sgml  |    2 +
 .../libtracker-sparql-sections.txt                 |   17 ++++++
 src/libtracker-common/tracker-utils.c              |   54 ++++++++++++++++++++
 src/libtracker-common/tracker-utils.h              |   16 ++++++
 6 files changed, 104 insertions(+), 4 deletions(-)
---
diff --git a/configure.ac b/configure.ac
index c94f05e..834f5c9 100644
--- a/configure.ac
+++ b/configure.ac
@@ -64,6 +64,7 @@ TRACKER_BINARY_AGE=tracker_binary_age
 TRACKER_VERSION=tracker_version
 TRACKER_API_VERSION=tracker_api_version
 TRACKER_BINARY_VERSION=tracker_binary_version
+
 AC_SUBST(TRACKER_MAJOR_VERSION)
 AC_SUBST(TRACKER_MINOR_VERSION)
 AC_SUBST(TRACKER_MICRO_VERSION)
@@ -73,6 +74,16 @@ AC_SUBST(TRACKER_API_VERSION)
 AC_SUBST(TRACKER_VERSION)
 AC_SUBST(TRACKER_BINARY_VERSION)
 
+AC_DEFINE(TRACKER_MAJOR_VERSION, [tracker_major_version],
+          [Define to the Tracker major version])
+AC_DEFINE(TRACKER_MINOR_VERSION, [tracker_minor_version],
+          [Define to the Tracker minor version])
+AC_DEFINE(TRACKER_MICRO_VERSION, [tracker_micro_version],
+          [Define to the Tracker micro version])
+AC_DEFINE(TRACKER_INTERFACE_AGE, [tracker_interface_age],
+          [Define to the Tracker interface age])
+AC_DEFINE(TRACKER_BINARY_AGE, [tracker_binary_age],
+          [Define to the Tracker binary age])
 
 # libtool versioning
 LT_RELEASE=tracker_lt_release
diff --git a/docs/reference/libtracker-sparql/Makefile.am b/docs/reference/libtracker-sparql/Makefile.am
index 3649b66..df6c09b 100644
--- a/docs/reference/libtracker-sparql/Makefile.am
+++ b/docs/reference/libtracker-sparql/Makefile.am
@@ -18,11 +18,11 @@ SCAN_OPTIONS=--deprecated-guards="TRACKER_DISABLE_DEPRECATED"
 DOC_SOURCE_DIR = ../../../src/libtracker-sparql
 
 # Used for dependencies
-HFILE_GLOB = $(top_srcdir)/src/libtracker-sparql/*.h
-CFILE_GLOB = $(top_srcdir)/src/libtracker-sparql/*.c
+HFILE_GLOB = $(top_srcdir)/src/libtracker-sparql/*.h $(top_srcdir)/src/libtracker-common/tracker-utils.h $(top_srcdir)/config.h
+CFILE_GLOB = $(top_srcdir)/src/libtracker-sparql/*.c $(top_srcdir)/src/libtracker-common/tracker-utils.c
 
-# Header files to ignore when scanning
-IGNORE_HFILES =
+# Header files to ignore when scanning (Ignore all files except tracker-utils from libtracker-common)
+IGNORE_HFILES = $(shell ls $(top_srcdir)/src/libtracker-common/*.h 2>/dev/null | grep -v tracker-utils)
 
 # CFLAGS and LDFLAGS for compiling scan program. Only needed
 # if $(DOC_MODULE).types is non-empty.
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
index 6931dde..ae54dfe 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
@@ -7,6 +7,7 @@
 <!ENTITY tracker-sparql-connection SYSTEM "xml/tracker-sparql-connection.xml">
 <!ENTITY tracker-sparql-cursor SYSTEM "xml/tracker-sparql-cursor.xml">
 <!ENTITY tracker-misc SYSTEM "xml/tracker-misc.xml">
+<!ENTITY tracker-version SYSTEM "xml/tracker-version.xml">
 <!ENTITY tracker-examples SYSTEM "examples.sgml">
 ]>
 <book id="index">
@@ -37,6 +38,7 @@
     &tracker-sparql-connection;
     &tracker-sparql-cursor;
     &tracker-misc;
+    &tracker-version;
   </part>
 
   <!-- The Examples -->
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
index daf848d..81c0fdb 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -155,3 +155,20 @@ TrackerSparqlCursorPrivate
 tracker_sparql_cursor_construct
 tracker_sparql_cursor_set_connection
 </SECTION>
+
+<SECTION>
+<TITLE>Version Information</TITLE>
+<FILE>tracker-version</FILE>
+tracker_major_version
+tracker_minor_version
+tracker_micro_version
+tracker_binary_age
+tracker_interface_age
+tracker_check_version
+
+<SUBSECTION>
+TRACKER_MAJOR_VERSION
+TRACKER_MINOR_VERSION
+TRACKER_MICRO_VERSION
+TRACKER_CHECK_VERSION
+</SECTION>
diff --git a/src/libtracker-common/tracker-utils.c b/src/libtracker-common/tracker-utils.c
index 8051662..afad85b 100644
--- a/src/libtracker-common/tracker-utils.c
+++ b/src/libtracker-common/tracker-utils.c
@@ -29,6 +29,60 @@
 
 #include "tracker-utils.h"
 
+const guint tracker_major_version = TRACKER_MAJOR_VERSION;
+const guint tracker_minor_version = TRACKER_MINOR_VERSION;
+const guint tracker_micro_version = TRACKER_MICRO_VERSION;
+const guint tracker_interface_age = TRACKER_INTERFACE_AGE;
+const guint tracker_binary_age = TRACKER_BINARY_AGE;
+
+/**
+ * tracker_check_version:
+ * @required_major: the required major version.
+ * @required_minor: the required minor version.
+ * @required_micro: the required micro version.
+ *
+ * Checks that the Tracker library in use is compatible with the
+ * given version. Generally you would pass in the constants
+ * #TRACKER_MAJOR_VERSION, #TRACKER_MINOR_VERSION, #TRACKER_MICRO_VERSION
+ * as the three arguments to this function; that produces
+ * a check that the library in use is compatible with
+ * the version of Tracker the application or module was compiled
+ * against.
+ *
+ * Compatibility is defined by two things: first the version
+ * of the running library is newer than the version
+ * @required_major required_minor  required_micro  Second
+ * the running library must be binary compatible with the
+ * version @required_major required_minor  required_micro
+ * (same major version.)
+ *
+ * Return value: %NULL if the Tracker library is compatible with the
+ *   given version, or a string describing the version mismatch.
+ *   The returned string is owned by Tracker and must not be modified
+ *   or freed.
+ *
+ * Since: 0.10
+ **/
+const gchar *
+tracker_check_version (guint required_major,
+                       guint required_minor,
+                       guint required_micro)
+{
+	gint tracker_effective_micro = 100 * TRACKER_MINOR_VERSION + TRACKER_MICRO_VERSION;
+	gint required_effective_micro = 100 * required_minor + required_micro;
+
+	if (required_major > TRACKER_MAJOR_VERSION)
+		return "Tracker version too old (major mismatch)";
+	if (required_major < TRACKER_MAJOR_VERSION)
+		return "Tracker version too new (major mismatch)";
+	if (required_effective_micro < tracker_effective_micro - TRACKER_BINARY_AGE)
+		return "Tracker version too new (micro mismatch)";
+	if (required_effective_micro > tracker_effective_micro)
+		return "Tracker version too old (micro mismatch)";
+
+	return NULL;
+}
+
 inline gboolean
 tracker_is_empty_string (const char *str)
 {
diff --git a/src/libtracker-common/tracker-utils.h b/src/libtracker-common/tracker-utils.h
index 2112100..4019653 100644
--- a/src/libtracker-common/tracker-utils.h
+++ b/src/libtracker-common/tracker-utils.h
@@ -29,6 +29,22 @@ G_BEGIN_DECLS
 #error "only <libtracker-common/tracker-common.h> must be included directly."
 #endif
 
+GLIB_VAR const guint tracker_major_version;
+GLIB_VAR const guint tracker_minor_version;
+GLIB_VAR const guint tracker_micro_version;
+GLIB_VAR const guint tracker_interface_age;
+GLIB_VAR const guint tracker_binary_age;
+
+const gchar * tracker_check_version (guint required_major,
+                                     guint required_minor,
+                                     guint required_micro);
+
+#define TRACKER_CHECK_VERSION(major,minor,micro)    \
+    (TRACKER_MAJOR_VERSION > (major) || \
+     (TRACKER_MAJOR_VERSION == (major) && TRACKER_MINOR_VERSION > (minor)) || \
+     (TRACKER_MAJOR_VERSION == (major) && TRACKER_MINOR_VERSION == (minor) && \
+      TRACKER_MICRO_VERSION >= (micro)))
+
 gboolean tracker_is_empty_string            (const char   *str);
 gboolean tracker_is_blank_string            (const char   *str);
 gchar *  tracker_seconds_estimate_to_string (gdouble       seconds_elapsed,