GnuCash: Instance

#define qof_instance_is_dirty qof_instance_get_dirty

Return value of is_dirty flag

Definition at line 185 of file qofinstance.h.

const GUID* qof_entity_get_guid ( gconstpointer )

Deprecated:: Use qof_instance_get_guid instead. Works like qof_instance_get_guid, but returns NULL on NULL

Definition at line 469 of file qofinstance.c.

00470 {
00471     return ent ? qof_instance_get_guid(ent) : guid_null();
00472 }

gboolean qof_instance_books_equal	(	gconstpointer	ptr1,
		gconstpointer	ptr2
	)

See if two QofInstances share the same book.

Definition at line 557 of file qofinstance.c.

00558 {
00559   const QofInstancePrivate *priv1, *priv2;
00560 
00561   g_return_val_if_fail(QOF_IS_INSTANCE(ptr1), FALSE);
00562   g_return_val_if_fail(QOF_IS_INSTANCE(ptr2), FALSE);
00563 
00564   priv1 = GET_PRIVATE(ptr1);
00565   priv2 = GET_PRIVATE(ptr2);
00566 
00567   return (priv1->book == priv2->book);
00568 }

gint qof_instance_compare_version	(	gconstpointer	inst1,
		gconstpointer	inst2
	)

Compare the version numbers of two instances.

Definition at line 753 of file qofinstance.c.

00754 {
00755     g_return_val_if_fail(QOF_IS_INSTANCE(inst1), 1);
00756     g_return_val_if_fail(QOF_IS_INSTANCE(inst2), -1);
00757     return GET_PRIVATE(inst2)->version - GET_PRIVATE(inst1)->version;
00758 }

void qof_instance_copy_book	(	gpointer	ptr1,
		gconstpointer	ptr2
	)

Copy the book from one QofInstances to another.

Definition at line 548 of file qofinstance.c.

00549 {
00550   g_return_if_fail(QOF_IS_INSTANCE(ptr1));
00551   g_return_if_fail(QOF_IS_INSTANCE(ptr2));
00552 
00553   GET_PRIVATE(ptr1)->book = GET_PRIVATE(ptr2)->book;
00554 }

void qof_instance_copy_guid	(	gpointer	to,
		gconstpointer	from
	)

Copy the GUID from one instance to another. This routine should be used with extreme caution, since GUID values are everywhere assumed to be unique.

Definition at line 495 of file qofinstance.c.

00496 {
00497     g_return_if_fail(QOF_IS_INSTANCE(to));
00498     g_return_if_fail(QOF_IS_INSTANCE(from));
00499 
00500     GET_PRIVATE(to)->guid = GET_PRIVATE(from)->guid;
00501 }

void qof_instance_copy_version	(	gpointer	to,
		gconstpointer	from
	)

Copy the version number on this instance. The version number is used to manage multi-user updates.

Definition at line 768 of file qofinstance.c.

00769 {
00770     g_return_if_fail(QOF_IS_INSTANCE(to));
00771     g_return_if_fail(QOF_IS_INSTANCE(from));
00772     GET_PRIVATE(to)->version = GET_PRIVATE(from)->version;
00773 }

void qof_instance_copy_version_check	(	gpointer	to,
		gconstpointer	from
	)

copy the instance version_check number

Definition at line 802 of file qofinstance.c.

00803 {
00804     g_return_if_fail(QOF_IS_INSTANCE(to));
00805     g_return_if_fail(QOF_IS_INSTANCE(from));
00806     GET_PRIVATE(to)->version_check = GET_PRIVATE(from)->version_check;
00807 }

void qof_instance_gemini	(	QofInstance *	to,
		const QofInstance *	from
	)

Pair things up. This routine inserts a kvp value into each instance containing the guid of the other. In this way, if one has one of the pair, one can always find the other by looking up it's guid. Typically, you will want to use qof_instance_lookup_twin() to find the twin. (The current implementation assumes the two instances belong to different books, and will not add gemini kvp's unless the books differ. Note that the gemini kvp includes the book guid as well, so that the right book can be found.

Definition at line 827 of file qofinstance.c.

00828 {
00829   QofInstancePrivate *from_priv, *to_priv, *fb_priv, *tb_priv;
00830   time_t now;
00831 
00832   g_return_if_fail(QOF_IS_INSTANCE(to));
00833   g_return_if_fail(QOF_IS_INSTANCE(from));
00834 
00835   from_priv = GET_PRIVATE(from);
00836   to_priv = GET_PRIVATE(to);
00837   fb_priv = GET_PRIVATE(from_priv->book);
00838   tb_priv = GET_PRIVATE(to_priv->book);
00839 
00840   /* Books must differ for a gemini to be meaningful */
00841   if (from_priv->book == to_priv->book)
00842     return;
00843 
00844   now = time(0);
00845 
00846   /* Make a note of where the copy came from */
00847   gnc_kvp_bag_add (to->kvp_data, "gemini", now,
00848                                   "inst_guid", &from_priv->guid,
00849                                   "book_guid", &fb_priv->guid,
00850                                   NULL);
00851   gnc_kvp_bag_add (from->kvp_data, "gemini", now,
00852                                   "inst_guid", &to_priv->guid,
00853                                   "book_guid", &tb_priv->guid,
00854                                   NULL);
00855 
00856   to_priv->dirty = TRUE;
00857 }

QofBook* qof_instance_get_book ( gconstpointer )

Return the book pointer

Definition at line 533 of file qofinstance.c.

00534 {
00535     if (!inst) return NULL;
00536     g_return_val_if_fail(QOF_IS_INSTANCE(inst), NULL);
00537     return GET_PRIVATE(inst)->book;
00538 }

QofCollection* qof_instance_get_collection ( gconstpointer inst )

Return the collection this instance belongs to

Definition at line 518 of file qofinstance.c.

00519 {
00520     
00521     g_return_val_if_fail(QOF_IS_INSTANCE(ptr), NULL);
00522     return GET_PRIVATE(ptr)->collection;
00523 }

gboolean qof_instance_get_destroying ( gconstpointer ptr )

Retrieve the flag that indicates whether or not this object is about to be destroyed.

Parameters:

ptr

The object whose flag should be retrieved.

Returns:: TRUE if the object has been marked for destruction. FALSE if the object is not marked for destruction, or if a bad parameter is passed to the function.

Definition at line 661 of file qofinstance.c.

00662 {
00663     g_return_val_if_fail(QOF_IS_INSTANCE(ptr), FALSE);
00664     return GET_PRIVATE(ptr)->do_free;
00665 }

gboolean qof_instance_get_dirty_flag ( gconstpointer ptr )

Retrieve the flag that indicates whether or not this object has been modified. This is specifically the flag on the object. It does not perform any other checking which might normally be performed when testing to see if an object is dirty. If there is any question, use the qof_instance_is_dirty() function instead.

Parameters:

ptr

The object whose flag should be retrieved.

Returns:: TRUE if the object has been modified and not saved. FALSE if the object has not been modified, or if a bad parameter is passed to the function.

Definition at line 675 of file qofinstance.c.

00676 {
00677     g_return_val_if_fail(QOF_IS_INSTANCE(ptr), FALSE);
00678     return GET_PRIVATE(ptr)->dirty;
00679 }

const GUID* qof_instance_get_guid ( gconstpointer )

Return the GUID of this instance

Definition at line 458 of file qofinstance.c.

00459 {
00460     QofInstancePrivate *priv;
00461 
00462     if (!inst) return NULL;
00463     g_return_val_if_fail(QOF_IS_INSTANCE(inst), guid_null());
00464     priv = GET_PRIVATE(inst);
00465     return &(priv->guid);
00466 }

guint32 qof_instance_get_idata ( gconstpointer inst )

get the instance tag number used for kvp management in sql backends.

Definition at line 809 of file qofinstance.c.

00810 {
00811         if(!inst) { return 0; }
00812         g_return_val_if_fail(QOF_IS_INSTANCE(inst), 0);
00813         return GET_PRIVATE(inst)->idata;
00814 }

Timespec qof_instance_get_last_update ( const QofInstance * inst )

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.

Definition at line 594 of file qofinstance.c.

00595 {
00596     if (!inst) {
00597         Timespec ts = {0,-1};
00598         return ts;
00599     }
00600     return GET_PRIVATE(inst)->last_update;
00601 }

KvpFrame* qof_instance_get_slots ( const QofInstance * )

Return the pointer to the kvp_data

Definition at line 571 of file qofinstance.c.

00572 {
00573     if (!inst) return NULL;
00574     return inst->kvp_data;
00575 }

GType qof_instance_get_type ( void )

Return the GType of a QofInstance

gint32 qof_instance_get_version ( gconstpointer inst )

Get the version number on this instance. The version number is used to manage multi-user updates.

Definition at line 746 of file qofinstance.c.

00747 {
00748     g_return_val_if_fail(QOF_IS_INSTANCE(inst), 0);
00749     return GET_PRIVATE(inst)->version;
00750 }

guint32 qof_instance_get_version_check ( gconstpointer inst )

Get the instance version_check number

Definition at line 788 of file qofinstance.c.

00789 {
00790     g_return_val_if_fail(QOF_IS_INSTANCE(inst), 0);
00791     return GET_PRIVATE(inst)->version_check;
00792 }

gint qof_instance_guid_compare	(	const gconstpointer	ptr1,
		const gconstpointer	ptr2
	)

Compare the GUID values of two instances. This routine returns 0 if the two values are equal, <0 if the first is smaller than the second, or >0 if the second is smaller tan the first.

Definition at line 504 of file qofinstance.c.

00505 {
00506     const QofInstancePrivate *priv1, *priv2;
00507 
00508     g_return_val_if_fail(QOF_IS_INSTANCE(ptr1), -1);
00509     g_return_val_if_fail(QOF_IS_INSTANCE(ptr2),  1);
00510 
00511     priv1 = GET_PRIVATE(ptr1);
00512     priv2 = GET_PRIVATE(ptr2);
00513 
00514     return guid_compare(&priv1->guid, &priv2->guid);
00515 }

void qof_instance_increment_version	(	gpointer	inst,
		guint32	new_check
	)

Increment the instance version number

Definition at line 776 of file qofinstance.c.

00777 {
00778     QofInstancePrivate *priv;
00779 
00780     g_return_if_fail(QOF_IS_INSTANCE(inst));
00781 
00782     priv = GET_PRIVATE(inst);
00783     priv->version++;
00784     priv->version_check = new_check;
00785 }

void qof_instance_init_data	(	QofInstance *	,
		QofIdType	,
		QofBook *
	)

Initialise the settings associated with an instance

Definition at line 276 of file qofinstance.c.

00277 {
00278         QofInstancePrivate *priv;
00279         QofCollection *col;
00280         QofIdType col_type;
00281 
00282         g_return_if_fail(QOF_IS_INSTANCE(inst));
00283         priv = GET_PRIVATE(inst);
00284         g_return_if_fail(!priv->book);
00285 
00286         priv->book = book;
00287         col = qof_book_get_collection (book, type);
00288         g_return_if_fail(col != NULL);
00289   
00290         /* XXX We passed redundant info to this routine ... but I think that's
00291          * OK, it might eliminate programming errors. */
00292 
00293         col_type = qof_collection_get_type(col);
00294         if (safe_strcmp(col_type, type)) {
00295             PERR ("attempt to insert \"%s\" into \"%s\"", type, col_type);
00296             return;
00297         }
00298         priv = GET_PRIVATE(inst);
00299         inst->e_type = CACHE_INSERT (type);
00300 
00301         do {
00302           guid_new(&priv->guid);
00303 
00304           if (NULL == qof_collection_lookup_entity (col, &priv->guid))
00305             break;
00306 
00307           PWARN("duplicate id created, trying again");
00308         } while(1);
00309  
00310         priv->collection = col;
00311 
00312         qof_collection_insert_entity (col, inst);
00313 }

QofInstance* qof_instance_lookup_twin	(	const QofInstance *	src,
		QofBook *	book
	)

The qof_instance_lookup_twin() routine will find the "twin" of this instance 'src' in the given other 'book' (if the twin exists).

When instances are gemini'ed or cloned, both of the pair are marked with the guid of thier copy, thus allowing the sibling-copy of an instance to be found. Since the sibling may end up in a different book, we need a way of finding it, given only that we know the book, and that we know its twin.

That's what this routine does. Given some book 'book', and an instance 'src', it will find the sibling instance of 'src' that is in 'book', and return it. If not found, it returns NULL. This routine uses the 'gemini' kvp values to do its work.

Definition at line 860 of file qofinstance.c.

00861 {
00862         QofCollection *col;
00863         KvpFrame *fr;
00864         GUID * twin_guid;
00865         QofInstance * twin;
00866         QofInstancePrivate *bpriv;
00867 
00868         if (!src || !target_book) return NULL;
00869         ENTER (" ");
00870 
00871         bpriv = GET_PRIVATE(QOF_INSTANCE(target_book));
00872         fr = gnc_kvp_bag_find_by_guid (src->kvp_data, "gemini",
00873                                      "book_guid", &bpriv->guid);
00874 
00875         twin_guid = kvp_frame_get_guid (fr, "inst_guid");
00876 
00877         col = qof_book_get_collection (target_book, src->e_type);
00878         twin = (QofInstance *) qof_collection_lookup_entity (col, twin_guid);
00879 
00880         LEAVE (" found twin=%p", twin);
00881         return twin;
00882 }

void qof_instance_set_book	(	gconstpointer	inst,
		QofBook *	book
	)

Set the book pointer

Definition at line 541 of file qofinstance.c.

00542 {
00543     g_return_if_fail(QOF_IS_INSTANCE(inst));
00544     GET_PRIVATE(inst)->book = book;
00545 }

void qof_instance_set_destroying	(	gpointer	ptr,
		gboolean	value
	)

Set the flag that indicates whether or not this object is about to be destroyed.

Parameters:

	ptr	The object whose flag should be set.
	value	The new value to be set for this object.

Definition at line 668 of file qofinstance.c.

00669 {
00670     g_return_if_fail(QOF_IS_INSTANCE(ptr));
00671     GET_PRIVATE(ptr)->do_free = value;
00672 }

void qof_instance_set_dirty ( QofInstance * inst )

Set the dirty flag.

Sets this instance AND the collection as dirty.

Definition at line 725 of file qofinstance.c.

00726 {
00727         QofInstancePrivate *priv;
00728         QofCollection *coll;
00729 
00730         priv = GET_PRIVATE(inst);
00731         priv->dirty = TRUE;
00732         if (!qof_get_alt_dirty_mode()) {
00733           coll = priv->collection;
00734           qof_collection_mark_dirty(coll);
00735         }
00736 }

void qof_instance_set_guid	(	gpointer	inst,
		const GUID *	guid
	)

Set the GUID of this instance

Definition at line 475 of file qofinstance.c.

00476 {
00477     QofInstancePrivate *priv;
00478     QofInstance *inst;
00479     QofCollection *col;
00480 
00481     g_return_if_fail(QOF_IS_INSTANCE(ptr));
00482 
00483     inst = QOF_INSTANCE(ptr);
00484     priv = GET_PRIVATE(inst);
00485     if (guid_equal (guid, &priv->guid))
00486         return;
00487 
00488     col = priv->collection;
00489     qof_collection_remove_entity(inst);
00490     priv->guid = *guid;
00491     qof_collection_insert_entity(col, inst);
00492 }

void qof_instance_set_version	(	gpointer	inst,
		gint32	value
	)

Set the version number on this instance. The version number is used to manage multi-user updates.

Definition at line 761 of file qofinstance.c.

00762 {
00763     g_return_if_fail(QOF_IS_INSTANCE(inst));
00764     GET_PRIVATE(inst)->version = vers;
00765 }

void qof_instance_set_version_check	(	gpointer	inst,
		guint32	value
	)

Set the instance version_check number

Definition at line 795 of file qofinstance.c.

00796 {
00797     g_return_if_fail(QOF_IS_INSTANCE(inst));
00798     GET_PRIVATE(inst)->version_check = value;
00799 }

int qof_instance_version_cmp	(	const QofInstance *	left,
		const QofInstance *	right
	)

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.

Definition at line 643 of file qofinstance.c.

00644 {
00645         QofInstancePrivate *lpriv, *rpriv;
00646 
00647         if (!left && !right) return 0;
00648         if (!left) return -1;
00649         if (!right) return +1;
00650 
00651         lpriv = GET_PRIVATE(left);
00652         rpriv = GET_PRIVATE(right);
00653         if (lpriv->last_update.tv_sec  < rpriv->last_update.tv_sec) return -1;
00654         if (lpriv->last_update.tv_sec  > rpriv->last_update.tv_sec) return +1;
00655         if (lpriv->last_update.tv_nsec < rpriv->last_update.tv_nsec) return -1;
00656         if (lpriv->last_update.tv_nsec > rpriv->last_update.tv_nsec) return +1;
00657         return 0;
00658 }


Files
file	qofinstance.h
	Object instance holds common fields that most gnucash objects use.
Data Structures
struct	QofInstance_s
struct	_QofInstanceClass
Defines
#define	QOF_TYPE_INSTANCE (qof_instance_get_type ())
#define	QOF_INSTANCE(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), QOF_TYPE_INSTANCE, QofInstance))
#define	QOF_INSTANCE_CLASS(k) (G_TYPE_CHECK_CLASS_CAST((k), QOF_TYPE_INSTANCE, QofInstanceClass))
#define	QOF_IS_INSTANCE(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), QOF_TYPE_INSTANCE))
#define	QOF_IS_INSTANCE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), QOF_TYPE_INSTANCE))
#define	QOF_INSTANCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), QOF_TYPE_INSTANCE, QofInstanceClass))
#define	qof_instance_is_dirty qof_instance_get_dirty
Typedefs
typedef _QofInstanceClass	QofInstanceClass
typedef QofInstance_s	QofInstance
typedef _QofBook	QofBook
	QofBook reference.
Functions
GType	qof_instance_get_type (void)
void	qof_instance_init_data (QofInstance , QofIdType, QofBook )
QofBook *	qof_instance_get_book (gconstpointer)
void	qof_instance_set_book (gconstpointer inst, QofBook *book)
void	qof_instance_copy_book (gpointer ptr1, gconstpointer ptr2)
gboolean	qof_instance_books_equal (gconstpointer ptr1, gconstpointer ptr2)
const GUID *	qof_instance_get_guid (gconstpointer)
const GUID *	qof_entity_get_guid (gconstpointer)
QofCollection *	qof_instance_get_collection (gconstpointer inst)
void	qof_instance_set_guid (gpointer inst, const GUID *guid)
void	qof_instance_copy_guid (gpointer to, gconstpointer from)
gint	qof_instance_guid_compare (const gconstpointer ptr1, const gconstpointer ptr2)
KvpFrame *	qof_instance_get_slots (const QofInstance *)
Timespec	qof_instance_get_last_update (const QofInstance *inst)
gint	qof_instance_get_editlevel (gconstpointer ptr)
void	qof_instance_increase_editlevel (gpointer ptr)
void	qof_instance_decrease_editlevel (gpointer ptr)
void	qof_instance_reset_editlevel (gpointer ptr)
int	qof_instance_version_cmp (const QofInstance left, const QofInstance right)
gboolean	qof_instance_get_destroying (gconstpointer ptr)
void	qof_instance_set_destroying (gpointer ptr, gboolean value)
gboolean	qof_instance_get_dirty_flag (gconstpointer ptr)
void	qof_instance_print_dirty (const QofInstance *entity, gpointer dummy)
gboolean	qof_instance_get_dirty (QofInstance *)
void	qof_instance_set_dirty (QofInstance *inst)
	Set the dirty flag.
void	qof_instance_mark_clean (QofInstance *)
void	qof_instance_set_editlevel (gpointer inst, gint level)
gboolean	qof_instance_check_edit (const QofInstance *inst)
gboolean	qof_instance_get_infant (const QofInstance *inst)
gint32	qof_instance_get_version (gconstpointer inst)
gint	qof_instance_compare_version (gconstpointer inst1, gconstpointer inst2)
void	qof_instance_set_version (gpointer inst, gint32 value)
void	qof_instance_copy_version (gpointer to, gconstpointer from)
void	qof_instance_increment_version (gpointer inst, guint32 new_check)
guint32	qof_instance_get_version_check (gconstpointer inst)
void	qof_instance_set_version_check (gpointer inst, guint32 value)
void	qof_instance_copy_version_check (gpointer to, gconstpointer from)
guint32	qof_instance_get_idata (gconstpointer inst)
void	qof_instance_set_idata (gpointer inst, guint32 idata)
void	qof_instance_gemini (QofInstance to, const QofInstance from)
QofInstance *	qof_instance_lookup_twin (const QofInstance src, QofBook book)

Instance
[Entity: Types, Identity and Instance Framework]

Detailed Description

Files

Data Structures

Defines

Typedefs

Functions

Define Documentation

Function Documentation

Instance [Entity: Types, Identity and Instance Framework]

Detailed Description

Files

Data Structures

Defines

Typedefs

Functions

Define Documentation

Function Documentation

Instance
[Entity: Types, Identity and Instance Framework]