GnuCash  2.6.18
Files | Data Structures | Macros | Functions

Files

file  qofinstance.h
 Object instance holds common fields that most gnucash objects use.
 

Data Structures

struct  QofInstance
 
struct  QofInstanceClass
 

Macros

#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
 

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 GncGUIDqof_instance_get_guid (gconstpointer)
 
const GncGUIDqof_entity_get_guid (gconstpointer)
 
QofCollection * qof_instance_get_collection (gconstpointer inst)
 
void qof_instance_set_guid (gpointer inst, const GncGUID *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 *)
 
void qof_instance_set_editlevel (gpointer inst, gint level)
 
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. More...
 
void qof_instance_mark_clean (QofInstance *)
 
gboolean qof_instance_get_infant (const QofInstance *inst)
 
gint32 qof_instance_get_version (gconstpointer inst)
 
void qof_instance_set_version (gpointer inst, gint32 value)
 
void qof_instance_copy_version (gpointer to, gconstpointer from)
 
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)
 
gchar * qof_instance_get_display_name (const QofInstance *inst)
 
GList * qof_instance_get_referring_object_list (const QofInstance *inst)
 
gboolean qof_instance_refers_to_object (const QofInstance *inst, const QofInstance *ref)
 
GList * qof_instance_get_typed_referring_object_list (const QofInstance *inst, const QofInstance *ref)
 
GList * qof_instance_get_referring_object_list_from_collection (const QofCollection *coll, const QofInstance *ref)
 

Detailed Description

Qof Instances are a derived type of QofInstance. The Instance adds some common features and functions that most objects will want to use.

Macro Definition Documentation

◆ qof_instance_is_dirty

#define qof_instance_is_dirty   qof_instance_get_dirty

Return value of is_dirty flag

Definition at line 191 of file qofinstance.h.

Function Documentation

◆ qof_entity_get_guid()

const GncGUID* 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 484 of file qofinstance.c.

485 {
486  return ent ? qof_instance_get_guid(ent) : guid_null();
487 }
const GncGUID * qof_instance_get_guid(gconstpointer inst)
Definition: qofinstance.c:473
const GncGUID * guid_null(void)
Definition: guid.c:125

◆ qof_instance_books_equal()

gboolean qof_instance_books_equal ( gconstpointer  ptr1,
gconstpointer  ptr2 
)

See if two QofInstances share the same book.

Definition at line 572 of file qofinstance.c.

573 {
574  const QofInstancePrivate *priv1, *priv2;
575 
576  g_return_val_if_fail(QOF_IS_INSTANCE(ptr1), FALSE);
577  g_return_val_if_fail(QOF_IS_INSTANCE(ptr2), FALSE);
578 
579  priv1 = GET_PRIVATE(ptr1);
580  priv2 = GET_PRIVATE(ptr2);
581 
582  return (priv1->book == priv2->book);
583 }

◆ qof_instance_copy_book()

void qof_instance_copy_book ( gpointer  ptr1,
gconstpointer  ptr2 
)

Copy the book from one QofInstances to another.

Definition at line 563 of file qofinstance.c.

564 {
565  g_return_if_fail(QOF_IS_INSTANCE(ptr1));
566  g_return_if_fail(QOF_IS_INSTANCE(ptr2));
567 
568  GET_PRIVATE(ptr1)->book = GET_PRIVATE(ptr2)->book;
569 }

◆ qof_instance_copy_guid()

void qof_instance_copy_guid ( gpointer  to,
gconstpointer  from 
)

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

Definition at line 510 of file qofinstance.c.

511 {
512  g_return_if_fail(QOF_IS_INSTANCE(to));
513  g_return_if_fail(QOF_IS_INSTANCE(from));
514 
515  GET_PRIVATE(to)->guid = GET_PRIVATE(from)->guid;
516 }

◆ qof_instance_copy_version()

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 754 of file qofinstance.c.

755 {
756  g_return_if_fail(QOF_IS_INSTANCE(to));
757  g_return_if_fail(QOF_IS_INSTANCE(from));
758  GET_PRIVATE(to)->version = GET_PRIVATE(from)->version;
759 }

◆ qof_instance_copy_version_check()

void qof_instance_copy_version_check ( gpointer  to,
gconstpointer  from 
)

copy the instance version_check number

Definition at line 776 of file qofinstance.c.

777 {
778  g_return_if_fail(QOF_IS_INSTANCE(to));
779  g_return_if_fail(QOF_IS_INSTANCE(from));
780  GET_PRIVATE(to)->version_check = GET_PRIVATE(from)->version_check;
781 }

◆ qof_instance_get_book()

QofBook* qof_instance_get_book ( gconstpointer  )

Return the book pointer

Definition at line 548 of file qofinstance.c.

549 {
550  if (!inst) return NULL;
551  g_return_val_if_fail(QOF_IS_INSTANCE(inst), NULL);
552  return GET_PRIVATE(inst)->book;
553 }

◆ qof_instance_get_collection()

QofCollection* qof_instance_get_collection ( gconstpointer  inst)

Return the collection this instance belongs to

Definition at line 533 of file qofinstance.c.

534 {
535 
536  g_return_val_if_fail(QOF_IS_INSTANCE(ptr), NULL);
537  return GET_PRIVATE(ptr)->collection;
538 }

◆ qof_instance_get_destroying()

gboolean qof_instance_get_destroying ( gconstpointer  ptr)

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

Parameters
ptrThe 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 660 of file qofinstance.c.

661 {
662  g_return_val_if_fail(QOF_IS_INSTANCE(ptr), FALSE);
663  return GET_PRIVATE(ptr)->do_free;
664 }

◆ qof_instance_get_dirty_flag()

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
ptrThe 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 674 of file qofinstance.c.

675 {
676  g_return_val_if_fail(QOF_IS_INSTANCE(ptr), FALSE);
677  return GET_PRIVATE(ptr)->dirty;
678 }

◆ qof_instance_get_display_name()

gchar* qof_instance_get_display_name ( const QofInstance *  inst)

Returns a displayable name for this object. The returned string must be freed by the caller.

Definition at line 806 of file qofinstance.c.

807 {
808  g_return_val_if_fail( inst != NULL, NULL );
809 
810  if ( QOF_INSTANCE_GET_CLASS(inst)->get_display_name != NULL )
811  {
812  return QOF_INSTANCE_GET_CLASS(inst)->get_display_name(inst);
813  }
814  else
815  {
816  /* Not implemented - return default string */
817  return g_strdup_printf("Object %s %p",
819  inst);
820  }
821 }
QofCollection * qof_instance_get_collection(gconstpointer ptr)
Definition: qofinstance.c:533
QofIdType qof_collection_get_type(const QofCollection *col)
Definition: qofid.c:72

◆ qof_instance_get_guid()

const GncGUID* qof_instance_get_guid ( gconstpointer  )

Return the GncGUID of this instance

Definition at line 473 of file qofinstance.c.

474 {
475  QofInstancePrivate *priv;
476 
477  if (!inst) return NULL;
478  g_return_val_if_fail(QOF_IS_INSTANCE(inst), guid_null());
479  priv = GET_PRIVATE(inst);
480  return &(priv->guid);
481 }
const GncGUID * guid_null(void)
Definition: guid.c:125

◆ qof_instance_get_idata()

guint32 qof_instance_get_idata ( gconstpointer  inst)

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

Definition at line 783 of file qofinstance.c.

784 {
785  if (!inst)
786  {
787  return 0;
788  }
789  g_return_val_if_fail(QOF_IS_INSTANCE(inst), 0);
790  return GET_PRIVATE(inst)->idata;
791 }

◆ qof_instance_get_referring_object_list()

GList* qof_instance_get_referring_object_list ( const QofInstance *  inst)

Returns a list of objects which refer to a specific object. The list must be freed by the caller, but the objects on the list must not.

Definition at line 856 of file qofinstance.c.

857 {
859 
860  g_return_val_if_fail( inst != NULL, NULL );
861 
862  /* scan all collections */
863  data.inst = inst;
864  data.list = NULL;
865 
866  qof_book_foreach_collection(qof_instance_get_book(inst),
867  get_referring_object_helper,
868  &data);
869  return data.list;
870 }
QofBook * qof_instance_get_book(gconstpointer inst)
Definition: qofinstance.c:548

◆ qof_instance_get_referring_object_list_from_collection()

GList* qof_instance_get_referring_object_list_from_collection ( const QofCollection *  coll,
const QofInstance *  ref 
)

Returns a list of objects from the collection which refer to the specific object. The list must be freed by the caller but the objects on the list must not.

Definition at line 884 of file qofinstance.c.

885 {
887 
888  g_return_val_if_fail( coll != NULL, NULL );
889  g_return_val_if_fail( ref != NULL, NULL );
890 
891  data.inst = ref;
892  data.list = NULL;
893 
894  qof_collection_foreach(coll, get_typed_referring_object_instance_helper, &data);
895  return data.list;
896 }
void qof_collection_foreach(const QofCollection *col, QofInstanceForeachCB cb_func, gpointer user_data)
Definition: qofid.c:317

◆ qof_instance_get_slots()

KvpFrame* qof_instance_get_slots ( const QofInstance *  )

Return the pointer to the kvp_data

Definition at line 586 of file qofinstance.c.

587 {
588  if (!inst) return NULL;
589  return inst->kvp_data;
590 }

◆ qof_instance_get_type()

GType qof_instance_get_type ( void  )

Return the GType of a QofInstance

◆ qof_instance_get_typed_referring_object_list()

GList* qof_instance_get_typed_referring_object_list ( const QofInstance *  inst,
const QofInstance *  ref 
)

Returns a list of my type of object which refers to an object. For example, when called as qof_instance_get_typed_referring_object_list(taxtable, account); it will return the list of taxtables which refer to a specific account. The result should be the same regardless of which taxtable object is used. The list must be freed by the caller but the objects on the list must not.

Definition at line 899 of file qofinstance.c.

900 {
901  g_return_val_if_fail( inst != NULL, NULL );
902  g_return_val_if_fail( ref != NULL, NULL );
903 
904  if ( QOF_INSTANCE_GET_CLASS(inst)->get_typed_referring_object_list != NULL )
905  {
906  return QOF_INSTANCE_GET_CLASS(inst)->get_typed_referring_object_list(inst, ref);
907  }
908  else
909  {
910  /* Not implemented - by default, loop through all objects of this object's type and check
911  them individually. */
912  QofCollection* coll;
913 
914  coll = qof_instance_get_collection(inst);
916  }
917 }
GList * qof_instance_get_referring_object_list_from_collection(const QofCollection *coll, const QofInstance *ref)
Definition: qofinstance.c:884
QofCollection * qof_instance_get_collection(gconstpointer ptr)
Definition: qofinstance.c:533

◆ qof_instance_get_version()

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 740 of file qofinstance.c.

741 {
742  g_return_val_if_fail(QOF_IS_INSTANCE(inst), 0);
743  return GET_PRIVATE(inst)->version;
744 }

◆ qof_instance_get_version_check()

guint32 qof_instance_get_version_check ( gconstpointer  inst)

Get the instance version_check number

Definition at line 762 of file qofinstance.c.

763 {
764  g_return_val_if_fail(QOF_IS_INSTANCE(inst), 0);
765  return GET_PRIVATE(inst)->version_check;
766 }

◆ qof_instance_guid_compare()

gint qof_instance_guid_compare ( const gconstpointer  ptr1,
const gconstpointer  ptr2 
)

Compare the GncGUID 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 519 of file qofinstance.c.

520 {
521  const QofInstancePrivate *priv1, *priv2;
522 
523  g_return_val_if_fail(QOF_IS_INSTANCE(ptr1), -1);
524  g_return_val_if_fail(QOF_IS_INSTANCE(ptr2), 1);
525 
526  priv1 = GET_PRIVATE(ptr1);
527  priv2 = GET_PRIVATE(ptr2);
528 
529  return guid_compare(&priv1->guid, &priv2->guid);
530 }

◆ qof_instance_init_data()

void qof_instance_init_data ( QofInstance *  ,
QofIdType  ,
QofBook *   
)

Initialise the settings associated with an instance

Definition at line 282 of file qofinstance.c.

283 {
284  QofInstancePrivate *priv;
285  QofCollection *col;
286  QofIdType col_type;
287 
288  g_return_if_fail(QOF_IS_INSTANCE(inst));
289  priv = GET_PRIVATE(inst);
290  g_return_if_fail(!priv->book);
291 
292  priv->book = book;
293  col = qof_book_get_collection (book, type);
294  g_return_if_fail(col != NULL);
295 
296  /* XXX We passed redundant info to this routine ... but I think that's
297  * OK, it might eliminate programming errors. */
298 
299  col_type = qof_collection_get_type(col);
300  if (g_strcmp0(col_type, type))
301  {
302  PERR ("attempt to insert \"%s\" into \"%s\"", type, col_type);
303  return;
304  }
305  priv = GET_PRIVATE(inst);
306  inst->e_type = CACHE_INSERT (type);
307 
308  do
309  {
310  guid_new(&priv->guid);
311 
312  if (NULL == qof_collection_lookup_entity (col, &priv->guid))
313  break;
314 
315  PWARN("duplicate id created, trying again");
316  }
317  while (1);
318 
319  priv->collection = col;
320 
321  qof_collection_insert_entity (col, inst);
322 }
void guid_new(GncGUID *guid)
Definition: guid.c:537
QofInstance * qof_collection_lookup_entity(const QofCollection *col, const GncGUID *guid)
Definition: qofid.c:211
#define PERR(format, args...)
Definition: qoflog.h:232
#define PWARN(format, args...)
Definition: qoflog.h:238
const gchar * QofIdType
Definition: qofid.h:80
void qof_collection_insert_entity(QofCollection *, QofInstance *)
Definition: qofid.c:94
QofIdType qof_collection_get_type(const QofCollection *col)
Definition: qofid.c:72
QofCollection * qof_book_get_collection(const QofBook *book, QofIdType entity_type)
Definition: qofbook.c:306
QofCollection * collection
Definition: qofinstance.c:71

◆ qof_instance_refers_to_object()

gboolean qof_instance_refers_to_object ( const QofInstance *  inst,
const QofInstance *  ref 
)

Does this object refer to a specific object

Definition at line 920 of file qofinstance.c.

921 {
922  g_return_val_if_fail( inst != NULL, FALSE );
923  g_return_val_if_fail( ref != NULL, FALSE );
924 
925  if ( QOF_INSTANCE_GET_CLASS(inst)->refers_to_object != NULL )
926  {
927  return QOF_INSTANCE_GET_CLASS(inst)->refers_to_object(inst, ref);
928  }
929  else
930  {
931  /* Not implemented - default = NO */
932  return FALSE;
933  }
934 }

◆ qof_instance_set_book()

void qof_instance_set_book ( gconstpointer  inst,
QofBook *  book 
)

Set the book pointer

Definition at line 556 of file qofinstance.c.

557 {
558  g_return_if_fail(QOF_IS_INSTANCE(inst));
559  GET_PRIVATE(inst)->book = book;
560 }

◆ qof_instance_set_destroying()

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
ptrThe object whose flag should be set.
valueThe new value to be set for this object.

Definition at line 667 of file qofinstance.c.

668 {
669  g_return_if_fail(QOF_IS_INSTANCE(ptr));
670  GET_PRIVATE(ptr)->do_free = value;
671 }

◆ qof_instance_set_dirty()

void qof_instance_set_dirty ( QofInstance *  inst)

Set the dirty flag.

Sets this instance AND the collection as dirty.

Definition at line 723 of file qofinstance.c.

724 {
725  QofInstancePrivate *priv;
726  QofCollection *coll;
727 
728  priv = GET_PRIVATE(inst);
729  priv->dirty = TRUE;
730 }

◆ qof_instance_set_guid()

void qof_instance_set_guid ( gpointer  inst,
const GncGUID guid 
)

Set the GncGUID of this instance

Definition at line 490 of file qofinstance.c.

491 {
492  QofInstancePrivate *priv;
493  QofInstance *inst;
494  QofCollection *col;
495 
496  g_return_if_fail(QOF_IS_INSTANCE(ptr));
497 
498  inst = QOF_INSTANCE(ptr);
499  priv = GET_PRIVATE(inst);
500  if (guid_equal (guid, &priv->guid))
501  return;
502 
503  col = priv->collection;
504  qof_collection_remove_entity(inst);
505  priv->guid = *guid;
506  qof_collection_insert_entity(col, inst);
507 }
gboolean guid_equal(const GncGUID *guid_1, const GncGUID *guid_2)
Definition: guid.c:708
void qof_collection_insert_entity(QofCollection *, QofInstance *)
Definition: qofid.c:94
QofCollection * collection
Definition: qofinstance.c:71

◆ qof_instance_set_version()

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 747 of file qofinstance.c.

748 {
749  g_return_if_fail(QOF_IS_INSTANCE(inst));
750  GET_PRIVATE(inst)->version = vers;
751 }

◆ qof_instance_set_version_check()

void qof_instance_set_version_check ( gpointer  inst,
guint32  value 
)

Set the instance version_check number

Definition at line 769 of file qofinstance.c.

770 {
771  g_return_if_fail(QOF_IS_INSTANCE(inst));
772  GET_PRIVATE(inst)->version_check = value;
773 }

◆ qof_instance_version_cmp()

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

Compare two instances, based on their 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 642 of file qofinstance.c.

643 {
644  QofInstancePrivate *lpriv, *rpriv;
645 
646  if (!left && !right) return 0;
647  if (!left) return -1;
648  if (!right) return +1;
649 
650  lpriv = GET_PRIVATE(left);
651  rpriv = GET_PRIVATE(right);
652  if (lpriv->last_update.tv_sec < rpriv->last_update.tv_sec) return -1;
653  if (lpriv->last_update.tv_sec > rpriv->last_update.tv_sec) return +1;
654  if (lpriv->last_update.tv_nsec < rpriv->last_update.tv_nsec) return -1;
655  if (lpriv->last_update.tv_nsec > rpriv->last_update.tv_nsec) return +1;
656  return 0;
657 }