add version-comarison hooks,

rename the 'new' function to 'create' to avoid reserved-word collision in C++


git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@10041 57a11ea4-9604-0410-9ed3-97b8803252fd

src/engine/Account.c

@@ -2836,13 +2836,14 @@ static QofObject account_object_def = {
   interface_version:     QOF_OBJECT_VERSION,
   e_type:                GNC_ID_ACCOUNT,
   type_label:            "Account",
-  new:                   NULL,
+  create:                NULL,
   book_begin:            NULL,
   book_end:              NULL,
   is_dirty:              NULL,
   mark_clean:            NULL,
   foreach:               qof_collection_foreach,
-  printable:             (const char* (*)(gpointer)) xaccAccountGetName
+  printable:             (const char* (*)(gpointer)) xaccAccountGetName,
+  version_cmp:           (int (*)(gpointer,gpointer)) qof_instance_version_cmp,
 };
 
 gboolean xaccAccountRegister (void)

src/engine/FreqSpec.c

@@ -88,8 +88,8 @@
 #include "gnc-date.h"
 #include "gnc-engine-util.h"
 #include "gnc-event-p.h"
-#include "messages.h"
 #include "gnc-trace.h"
+#include "messages.h"
 #include "qofbook.h"
 #include "qofbook-p.h"
 #include "qofid-p.h"
@@ -181,8 +181,8 @@ xaccFreqSpecInit( FreqSpec *fs, QofBook *book )
    g_return_if_fail( fs );
    g_return_if_fail (book);
 
-   col = qof_book_get_collection (book, GNC_ID_FREQSPEC);
+   col = qof_book_get_collection (book, QOF_ID_FREQSPEC);
-   qof_entity_init (&fs->entity, GNC_ID_FREQSPEC, col);
+   qof_entity_init (&fs->entity, QOF_ID_FREQSPEC, col);
 
    fs->type = INVALID;
    fs->uift = UIFREQ_ONCE;

src/engine/FreqSpec.h

@@ -17,7 +17,7 @@
  * Boston, MA  02111-1307,  USA       gnu@gnu.org                   *
  *                                                                  *
 \********************************************************************/
-/** @addtogroup Engine
+/** @addtogroup QOF
     @{ */
 /** @addtogroup FreqSpec Specifying Recurring Dates (Periods)
     @{ */
@@ -34,7 +34,7 @@
 
 #include <glib.h>
 
-#include "gnc-engine.h"
+#include "qofid.h"
 #include "guid.h"
 #include "qofbook.h"
 

src/engine/Group.c

@@ -1263,13 +1263,14 @@ static QofObject group_object_def =
   interface_version: QOF_OBJECT_VERSION,
   e_type:            GNC_ID_GROUP,
   type_label:        "AccountGroup",
-  new:               NULL,
+  create:            NULL,
   book_begin:        group_book_begin,
   book_end:          group_book_end,
   is_dirty:          group_is_dirty,
   mark_clean:        group_mark_clean,
   foreach:           NULL,
   printable:         NULL,
+  version_cmp:       NULL,
 };
 
 gboolean 

src/engine/SX-book.c

@@ -269,13 +269,14 @@ static QofObject sxtt_object_def =
   interface_version: QOF_OBJECT_VERSION,
   e_type:            GNC_ID_SXTT,
   type_label:        "Scheduled Transaction Templates",
-  new:               NULL,
+  create:            NULL,
   book_begin:        sxtt_book_begin,
   book_end:          sxtt_book_end,
   is_dirty:          book_sxlist_notsaved,
   mark_clean:        book_sxns_mark_saved,
   foreach:           NULL,
   printable:         NULL,
+  version_cmp:       NULL,
 };
 
 gboolean 

src/engine/Transaction.c

@@ -3204,13 +3204,14 @@ static QofObject split_object_def = {
   interface_version:       QOF_OBJECT_VERSION,
   e_type:                  GNC_ID_SPLIT,
   type_label:              "Split",
-  new:                     NULL,
+  create:                  NULL,
   book_begin:              NULL,
   book_end:                NULL,
   is_dirty:                NULL,
   mark_clean:              NULL,
   foreach:                 qof_collection_foreach,
-  printable:               (const char* (*)(gpointer)) xaccSplitGetMemo
+  printable:               (const char* (*)(gpointer)) xaccSplitGetMemo,
+  version_cmp:             NULL,
 };
 
 static gpointer 
@@ -3299,13 +3300,14 @@ static QofObject trans_object_def = {
   interface_version:   QOF_OBJECT_VERSION,
   e_type:              GNC_ID_TRANS,
   type_label:          "Transaction",
-  new:                 NULL,
+  create:              NULL,
   book_begin:          NULL,
   book_end:            NULL,
   is_dirty:            NULL,
   mark_clean:          NULL,
   foreach:             qof_collection_foreach,
-  printable:           (const char* (*)(gpointer)) xaccTransGetDescription
+  printable:           (const char* (*)(gpointer)) xaccTransGetDescription,
+  version_cmp:         (int (*)(gpointer,gpointer)) qof_instance_version_cmp,
 };
 
 static gboolean

src/engine/gnc-commodity.c

@@ -1598,13 +1598,14 @@ static QofObject commodity_table_object_def =
   interface_version: QOF_OBJECT_VERSION,
   e_type:            GNC_ID_COMMODITY_TABLE,
   type_label:        "CommodityTable",
-  new:               NULL,
+  create:            NULL,
   book_begin:        commodity_table_book_begin,
   book_end:          commodity_table_book_end,
   is_dirty:          NULL,
   mark_clean:        NULL,
   foreach:           NULL,
   printable:         NULL,
+  version_cmp:       NULL,
 };
 
 gboolean 

src/engine/gnc-pricedb.c

@@ -2057,13 +2057,14 @@ static QofObject pricedb_object_def =
   interface_version: QOF_OBJECT_VERSION,
   e_type:            GNC_ID_PRICE,
   type_label:        "Price",
-  new:               NULL,
+  create:            NULL,
   book_begin:        pricedb_book_begin,
   book_end:          pricedb_book_end,
   is_dirty:          pricedb_is_dirty,
   mark_clean:        pricedb_mark_clean,
   foreach:           pricedb_foreach,
   printable:         pricedb_printable,
+  version_cmp:       NULL,
 };
 
 gboolean 

src/engine/qofgobj.c

@@ -296,13 +296,14 @@ qof_gobject_register (QofType e_type, GObjectClass *obclass)
   /* We could let the user specify a "nick" here, but
    * the actual class name seems reasonable, e.g. for debugging. */
   class_def->type_label = G_OBJECT_CLASS_NAME (obclass);
-  class_def->new = NULL;
+  class_def->create = NULL;
   class_def->book_begin = NULL;
   class_def->book_end = NULL;
   class_def->is_dirty = NULL;
   class_def->mark_clean = NULL;
   class_def->foreach = qof_gobject_foreach;
   class_def->printable = NULL;
+  class_def->version_cmp = NULL;
  
   qof_object_register (class_def);
 }

src/engine/qofinstance-p.h

@@ -59,6 +59,14 @@ struct QofInstance_s
    * important keys. */
    KvpFrame *kvp_data;
 
+   /** Timestamp used to track the last modification to this 
+    *  instance.  Typically used to compare two versions of the
+    *  same object, to see which is newer.  When used with the 
+    *  SQL backend, this field is reserved for SQL use, to compare
+    *  the version in local memory to the remote, server version.
+    */
+   Timespec last_update;
+
    /** Keep track of nesting level of begin/end edit calls */
    int    editlevel;
 
@@ -74,6 +82,12 @@ void qof_instance_mark_clean (QofInstance *);
 
 void qof_instance_set_slots (QofInstance *, KvpFrame *);
 
+/** Set the last_update time. Reserved for use by the SQL backend;
+ *  used for comparing version in local memory to that in remote 
+ *  server. 
+ */
+void qof_instance_set_last_update (QofInstance *inst, Timespec ts);
+
 /* @} */
 /* @} */
 /* @} */

src/engine/qofinstance.c

@@ -44,40 +44,42 @@ static short module = MOD_ENGINE;
 void 
 qof_instance_init (QofInstance *inst, QofIdType type, QofBook *book)
 {
-   QofCollection *col;
+	QofCollection *col;
 
-   inst->book = book;
+	inst->book = book;
 	inst->kvp_data = kvp_frame_new();
+	inst->last_update.tv_sec = 0;
+	inst->last_update.tv_nsec = -1;
 	inst->editlevel = 0;
 	inst->do_free = FALSE;
 	inst->dirty = FALSE;
 
-   col = qof_book_get_collection (book, type);
+	col = qof_book_get_collection (book, type);
 	qof_entity_init (&inst->entity, type, col);
 }
 
 void 
 qof_instance_release (QofInstance *inst)
 {
-   kvp_frame_delete (inst->kvp_data);
+	kvp_frame_delete (inst->kvp_data);
 	inst->editlevel = 0;
 	inst->do_free = FALSE;
-   inst->dirty = FALSE;
+	inst->dirty = FALSE;
 	qof_entity_release (&inst->entity);
 }
 
 const GUID *
 qof_instance_get_guid (QofInstance *inst)
 {
-   if (!inst) return NULL;
+	if (!inst) return NULL;
-   return &inst->entity.guid;
+	return &inst->entity.guid;
 }
 
 QofBook * 
 qof_instance_get_book (QofInstance *inst)
 {
-   if (!inst) return NULL;
+	if (!inst) return NULL;
-   return inst->book;
+	return inst->book;
 }
 
 KvpFrame* 
@@ -87,11 +89,35 @@ qof_instance_get_slots (QofInstance *inst)
   return inst->kvp_data;
 }
 
+Timespec
+qof_instance_get_last_update (QofInstance *inst)
+{
+	if (!inst) 
+	{
+		Timespec ts = {0,-1}; 
+		return ts;
+	}
+	return inst->last_update;
+}
+
+int 
+qof_instance_version_cmp (QofInstance *left, QofInstance *right)
+{
+	if (!left && !right) return 0;
+	if (!left) return -1;
+	if (!right) return +1;
+	if (left->last_update.tv_sec < right->last_update.tv_sec) return -1;
+	if (left->last_update.tv_sec > right->last_update.tv_sec) return +1;
+	if (left->last_update.tv_nsec < right->last_update.tv_nsec) return -1;
+	if (left->last_update.tv_nsec > right->last_update.tv_nsec) return +1;
+	return 0;
+}
+
 gboolean
 qof_instance_is_dirty (QofInstance *inst)
 {
-  if (!inst) return FALSE;
+	if (!inst) return FALSE;
-  return inst->dirty;
+	return inst->dirty;
 }
 
 /* ========================================================== */
@@ -112,11 +138,18 @@ qof_instance_set_slots (QofInstance *inst, KvpFrame *frm)
   {
     kvp_frame_delete(inst->kvp_data);
   }
-                                                                                
+
   inst->dirty = TRUE;
   inst->kvp_data = frm;
 }
 
+void
+qof_instance_set_last_update (QofInstance *inst, Timespec ts)
+{
+  if (!inst) return;
+  inst->last_update = ts;
+}
+
 /* ========================================================== */
 
 void
@@ -146,23 +179,23 @@ QofInstance *
 qof_instance_lookup_twin (QofInstance *src, QofBook *target_book)
 {
 	QofCollection *col;
-   KvpFrame *fr;
+	KvpFrame *fr;
-   GUID * twin_guid;
+	GUID * twin_guid;
-   QofInstance * twin;
+	QofInstance * twin;
-                                                                                
-   if (!src || !target_book) return NULL;
-   ENTER (" ");
 
-   fr = gnc_kvp_bag_find_by_guid (src->kvp_data, "gemini",
+	if (!src || !target_book) return NULL;
-                    "book_guid", &target_book->entity.guid);
+	ENTER (" ");
-                                                                                
+
-   twin_guid = kvp_frame_get_guid (fr, "inst_guid");
+	fr = gnc_kvp_bag_find_by_guid (src->kvp_data, "gemini",
+	                             "book_guid", &target_book->entity.guid);
+
+	twin_guid = kvp_frame_get_guid (fr, "inst_guid");
 
 	col = qof_book_get_collection (target_book, src->entity.e_type);
-   twin = (QofInstance *) qof_collection_lookup_entity (col, twin_guid);
+	twin = (QofInstance *) qof_collection_lookup_entity (col, twin_guid);
 
-   LEAVE (" found twin=%p", twin);
+	LEAVE (" found twin=%p", twin);
-   return twin;
+	return twin;
 }
 
 /* ========================== END OF FILE ======================= */

src/engine/qofinstance.h

@@ -30,13 +30,14 @@
 /** @file qofinstance.h 
  *  @brief Object instance holds common fields that most gnucash objects use.
  * 
- *  @author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
+ *  @author Copyright (C) 2003,2004 Linas Vepstas <linas@linas.org>
  */
 
 #ifndef QOF_INSTANCE_H
 #define QOF_INSTANCE_H
 
 #include "guid.h"
+#include "gnc-date.h"
 #include "kvp_frame.h"
 #include "qofbook.h"
 #include "qofid.h"
@@ -61,10 +62,26 @@ QofBook * qof_instance_get_book (QofInstance *);
 /** Return the GUID of this instance */
 const GUID * qof_instance_get_guid (QofInstance *);
 
-/** return the pointer to the kvp_data */
+/** Return the pointer to the kvp_data */
 KvpFrame* qof_instance_get_slots (QofInstance *);
 
-/** return value of is_dirty flag */
+/** Return the last time this instance was modified.  If QofInstances
+ *  are used with the QofObject storage backends, then the instance
+ *  update times are reserved for use by the backend, for managing
+ *  multi-user updates.  Non-backend code should not set the update 
+ *  times. 
+ */
+Timespec qof_instance_get_last_update (QofInstance *inst);
+
+/** Compare two instances, based on thier last update times. 
+ *  Returns a negative, zero or positive value, respectively, 
+ *  if 'left' is earlier, same as or later than 'right'.  
+ *  Accepts NULL pointers, NULL's are by definition earlier
+ *  than any value.
+ */
+int qof_instance_version_cmp (QofInstance *left, QofInstance *right);
+
+/** Return value of is_dirty flag */
 gboolean qof_instance_is_dirty (QofInstance *);
 
 /** Pair things up.  This routine inserts a kvp value into each instance

src/engine/qofobject.c

@@ -51,8 +51,8 @@ qof_object_new_instance (QofIdTypeConst type_name, QofBook *book)
   obj = qof_object_lookup (type_name);
   if (!obj) return NULL;
 
-  if (obj->new) 
+  if (obj->create) 
-    return (obj->new (book));
+    return (obj->create (book));
 
   return NULL;
 }

src/engine/qofobject.h

@@ -72,7 +72,7 @@ struct _QofObject
    *  NULL if the object type doesn't provide a way of creating new 
    *  instances. 
    */
-  gpointer            (*new)(QofBook *);
+  gpointer            (*create)(QofBook *);
 
   /** book_begin is called from within the Book routines to create
    * module-specific hooks in a book whenever a book is created.

src/engine/test/test-object.c

@@ -25,13 +25,14 @@ static QofObject bus_obj = {
   interface_version:  QOF_OBJECT_VERSION,
   e_type:             TEST_MODULE_NAME,
   type_label:         TEST_MODULE_DESC,
-  new:                NULL,
+  create:             NULL,
   book_begin:         NULL,
   book_end:           NULL,
   is_dirty:           NULL,
   mark_clean:         NULL,
   foreach:            obj_foreach,
   printable:          printable,
+  version_cmp:        NULL,
 };
 
 static void