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