1 /********************************************************************\
2  * qofinstance.h -- fields common to all object instances           *
3  *                                                                  *
4  * This program is free software; you can redistribute it and/or    *
5  * modify it under the terms of the GNU General Public License as   *
6  * published by the Free Software Foundation; either version 2 of   *
7  * the License, or (at your option) any later version.              *
8  *                                                                  *
9  * This program is distributed in the hope that it will be useful,  *
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of   *
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the    *
12  * GNU General Public License for more details.                     *
13  *                                                                  *
14  * You should have received a copy of the GNU General Public License*
15  * along with this program; if not, contact:                        *
16  *                                                                  *
17  * Free Software Foundation           Voice:  +1-617-542-5942       *
18  * 51 Franklin Street, Fifth Floor    Fax:    +1-617-542-2652       *
19  * Boston, MA  02110-1301,  USA       gnu@gnu.org                   *
20  *                                                                  *
21 \********************************************************************/
22 /** @addtogroup Class
23     @{ */
24 /** @addtogroup Instance
25     Qof Instances are a derived type of QofEntity.  The Instance
26     adds some common features and functions that most objects
27     will want to use.
28 
29     @{ */
30 /** @file qofinstance.h
31  *  @brief Object instance holds common fields that most QofObjects use.
32  *
33  *  @author Copyright (C) 2003,2004 Linas Vepstas <linas@linas.org>
34  */
35 
36 #ifndef QOF_INSTANCE_H
37 #define QOF_INSTANCE_H
38 
39 #include "guid.h"
40 #include "qofbook.h"
41 #include "qofid.h"
42 #include "qoftime.h"
43 #include "kvpframe.h"
44 
45 /* --- type macros --- */
46 /* cheesy, but will do for now, eventually should be more gtk-like, handle
47  * thunks, etc.  */
48 #define QOF_INSTANCE(object) ((QofInstance *)(object))
49 
50 typedef struct QofInstance_s QofInstance;
51 
52 /** Initialise the memory associated with an instance */
53 void qof_instance_init (QofInstance *, QofIdType, QofBook *);
54 
55 /** release the data associated with this instance. Dont actually free
56  * the memory associated with the instance. */
57 void qof_instance_release (QofInstance * inst);
58 
59 /** Return the book pointer */
60 QofBook *qof_instance_get_book (QofInstance *);
61 
62 /** Return the GUID of this instance */
63 const GUID *qof_instance_get_guid (QofInstance *);
64 
65 /** Return the pointer to the kvp_data */
66 KvpFrame *qof_instance_get_slots (QofInstance *);
67 
68 /** Return the last time this instance was modified.  If QofInstances
69  *  are used with the QofObject storage backends, then the instance
70  *  update times are reserved for use by the backend, for managing
71  *  multi-user updates.  Non-backend code should not set the update
72  *  times.
73  */
74 QofTime *qof_instance_get_update_time (QofInstance * inst);
75 
76 /** Compare two instances, based on thier last update times.
77  *  Returns a negative, zero or positive value, respectively,
78  *  if 'left' is earlier, same as or later than 'right'.
79  *  Accepts NULL pointers, NULL's are by definition earlier
80  *  than any value.
81  */
82 gint qof_instance_version_cmp (QofInstance * left, QofInstance * right);
83 
84 /** Return value of is_dirty flag */
85 gboolean qof_instance_is_dirty (QofInstance *);
86 
87 /** \brief Set the dirty flag
88 
89 Sets this instance AND the collection as dirty.
90 */
91 void qof_instance_set_dirty (QofInstance * inst);
92 
93 gboolean qof_instance_check_edit (QofInstance * inst);
94 
95 gboolean qof_instance_do_free (QofInstance * inst);
96 
97 void qof_instance_mark_free (QofInstance * inst);
98 
99 QofInstance *qof_instance_create (QofIdType type, QofBook * book);
100 
101 /** Pair things up.  This routine inserts a kvp value into each instance
102  *  containing the guid of the other.  In this way, if one has one of the
103  *  pair, one can always find the other by looking up it's guid.  Typically,
104  *  you will want to use qof_instance_lookup_twin() to find the twin.
105  *  (The current implementation assumes the two instances belong to different
106  *  books, and will not add gemini kvp's unless the books differ.  Note that
107  *  the gemini kvp includes the book guid as well, so that the right book can
108  *  be found.
109  */
110 void qof_instance_gemini (QofInstance * to, QofInstance * from);
111 
112 /** The qof_instance_lookup_twin() routine will find the "twin" of this
113  *    instance 'src' in the given other 'book' (if the twin exists).
114  *
115  *    When instances are gemini'ed or cloned, both of the pair are marked
116  *    with the guid of thier copy, thus allowing the sibling-copy of
117  *    an instance to be found.  Since the sibling may end up in a
118  *    different book, we need a way of finding it, given only that we
119  *    know the book, and that we know its twin.
120  *
121  *    That's what this routine does.  Given some book 'book', and an
122  *    instance 'src', it will find the sibling instance of 'src' that is
123  *    in 'book', and return it.  If not found, it returns NULL.  This
124  *    routine uses the 'gemini' kvp values to do its work.
125  */
126 QofInstance *qof_instance_lookup_twin (QofInstance * src, QofBook * book);
127 
128 /* @} */
129 /* @} */
130 #endif /* QOF_INSTANCE_H */
131