1 /********************************************************************\ 2 * qofid.h -- QOF entity type identification system * 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 23 #ifndef QOF_ID_H 24 #define QOF_ID_H 25 26 #ifdef __cplusplus 27 extern "C" 28 { 29 #endif 30 31 /** @addtogroup Entity 32 @{ */ 33 /** @addtogroup Entities 34 35 This file defines an API that adds types to the GncGUID's. 36 GncGUID's with types can be used to identify and reference 37 typed entities. 38 39 The idea here is that a GncGUID can be used to uniquely identify 40 some thing. By adding a type, one can then talk about the 41 type of thing identified. By adding a collection, one can 42 then work with a handle to a collection of things of a given 43 type, each uniquely identified by a given ID. QOF Entities 44 can be used independently of any other part of the system. 45 In particular, Entities can be useful even if one is not using 46 the Query and Object parts of the QOF system. 47 48 Identifiers are globally-unique and permanent, i.e., once 49 an entity has been assigned an identifier, it retains that same 50 identifier for its lifetime. 51 Identifiers can be encoded as hex strings. 52 53 GncGUID Identifiers are 'typed' with strings. The native ids used 54 by QOF are defined below. 55 -# An id with type QOF_ID_NONE does not 56 refer to any entity. 57 -# An id with type QOF_ID_NULL does not refer 58 to any entity, and will never refer to any entity. 59 =# An identifier with any other type may refer to an 60 actual entity, but that is not guaranteed as that entity does 61 not have to exist within the current book. (See ::PARTIAL_QOFBOOK). 62 Also, creating a new entity from a data source involves creating 63 a temporary GncGUID and then setting the value from the data source. 64 If an id does refer to an entity, the type of the entity will match 65 the type of the identifier. 66 67 If you have a type name, and you want to have a way of finding 68 a collection that is associated with that type, then you must use 69 Books. 70 71 Entities can refer to other entities as well as to the basic 72 QOF types, using the qofclass parameters. 73 74 @{ */ 75 /** @file qofid.h 76 @brief QOF entity type identification system 77 @author Copyright (C) 2000 Dave Peticolas <peticola@cs.ucdavis.edu> 78 @author Copyright (C) 2003 Linas Vepstas <linas@linas.org> 79 */ 80 81 #include <string.h> 82 #include "guid.h" 83 84 /** QofIdType declaration */ 85 typedef const gchar * QofIdType; 86 /** QofIdTypeConst declaration */ 87 typedef const gchar * QofIdTypeConst; 88 89 typedef struct QofCollection_s QofCollection; 90 91 #include "qofinstance.h" 92 93 #define QOF_ID_NONE NULL 94 #define QOF_ID_NULL "null" 95 96 #define QOF_ID_BOOK "Book" 97 #define QOF_ID_SESSION "Session" 98 99 #define QSTRCMP g_strcmp0 100 101 /** return TRUE if object is of the given type */ 102 #define QOF_CHECK_TYPE(obj,type) (((obj) != NULL) && \ 103 (0 == QSTRCMP((type),(((QofInstance *)(obj))->e_type)))) 104 105 /** cast object to the indicated type, 106 print error message if its bad */ 107 #define QOF_CHECK_CAST(obj,e_type,c_type) ( \ 108 QOF_CHECK_TYPE((obj),(e_type)) ? \ 109 (c_type *) (obj) : \ 110 (c_type *) ({ \ 111 g_log (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, \ 112 "Error: Bad QofInstance at %s:%d", __FILE__, __LINE__); \ 113 (obj); \ 114 })) 115 116 117 /** QofCollection declaration 118 119 @param e_type QofIdType 120 @param is_dirty gboolean 121 @param hash_of_entities GHashTable 122 @param data gpointer, place where object class can hang arbitrary data 123 124 */ 125 126 /** @name Collections of Entities 127 @{ */ 128 129 /** create a new collection of entities of type */ 130 QofCollection * qof_collection_new (QofIdType type); 131 132 /** return the number of entities in the collection. */ 133 guint qof_collection_count (const QofCollection *col); 134 135 /** destroy the collection */ 136 void qof_collection_destroy (QofCollection *col); 137 138 /** return the type that the collection stores */ 139 QofIdType qof_collection_get_type (const QofCollection *); 140 141 /** Find the entity going only from its guid */ 142 /*@ dependent @*/ 143 QofInstance * qof_collection_lookup_entity (const QofCollection *, const GncGUID *); 144 145 /** Callback type for qof_collection_foreach */ 146 typedef void (*QofInstanceForeachCB) (QofInstance *, gpointer user_data); 147 148 /** Call the callback for each entity in the collection. */ 149 void qof_collection_foreach (const QofCollection *, QofInstanceForeachCB, 150 gpointer user_data); 151 152 /** Store and retrieve arbitrary object-defined data 153 * 154 * XXX We need to add a callback for when the collection is being 155 * destroyed, so that the user has a chance to clean up anything 156 * that was put in the 'data' member here. 157 */ 158 gpointer qof_collection_get_data (const QofCollection *col); 159 void qof_collection_set_data (QofCollection *col, gpointer user_data); 160 161 /** Return value of 'dirty' flag on collection */ 162 gboolean qof_collection_is_dirty (const QofCollection *col); 163 164 /** @name QOF_TYPE_COLLECT: Linking one entity to many of one type 165 166 \note These are \b NOT the same as the main collections in the book. 167 168 QOF_TYPE_COLLECT is a secondary collection, used to select entities 169 of one object type as references of another entity. 170 \sa QOF_TYPE_CHOICE. 171 172 @{ 173 */ 174 /** \brief Add an entity to a QOF_TYPE_COLLECT. 175 176 \note These are \b NOT the same as the main collections in the book. 177 178 Entities can be 179 freely added and merged across these secondary collections, they 180 will not be removed from the original collection as they would 181 by using ::qof_instance_insert_entity or ::qof_instance_remove_entity. 182 183 */ 184 gboolean 185 qof_collection_add_entity (QofCollection *coll, QofInstance *ent); 186 187 void qof_collection_remove_entity (QofInstance *ent); 188 189 /** \brief Compare two secondary collections. 190 191 Performs a deep comparison of the collections. Each QofInstance in 192 each collection is looked up in the other collection, via the GncGUID. 193 194 \return 0 if the collections are identical or both are NULL 195 otherwise -1 if target is NULL or either collection contains an entity with an invalid 196 GncGUID or if the types of the two collections do not match, 197 or +1 if merge is NULL or if any entity exists in one collection but 198 not in the other. 199 */ 200 gint 201 qof_collection_compare (QofCollection *target, QofCollection *merge); 202 203 /** \brief Create a secondary collection from a GList 204 205 @param type The QofIdType of the QofCollection \b and of 206 \b all entities in the GList. 207 @param glist GList of entities of the same QofIdType. 208 209 @return NULL if any of the entities fail to match the 210 QofCollection type, else a pointer to the collection 211 on success. 212 */ 213 QofCollection* 214 qof_collection_from_glist (QofIdType type, const GList *glist); 215 216 /** @} */ 217 /** @} */ 218 219 #ifdef __cplusplus 220 } 221 #endif 222 223 #endif /* QOF_ID_H */ 224 /** @} */ 225 /** @} */ 226