Instance

Qof Instances are a derived type of QofInstance. More...

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
	Return value of is_dirty flag.

Functions
GType	qof_instance_get_type (void)
	Return the GType of a QofInstance.
void	qof_instance_init_data (QofInstance *, QofIdType, QofBook *)
	Initialise the settings associated with an instance.
QofBook *	qof_instance_get_book (gconstpointer)
	Return the book pointer.
void	qof_instance_set_book (gconstpointer inst, QofBook *book)
	Set the book pointer.
void	qof_instance_copy_book (gpointer ptr1, gconstpointer ptr2)
	Copy the book from one QofInstances to another.
gboolean	qof_instance_books_equal (gconstpointer ptr1, gconstpointer ptr2)
	See if two QofInstances share the same book.
const GncGUID *	qof_instance_get_guid (gconstpointer)
	Return the GncGUID of this instance.
const GncGUID *	qof_entity_get_guid (gconstpointer)
QofCollection *	qof_instance_get_collection (gconstpointer inst)
	Return the collection this instance belongs to.
gint	qof_instance_guid_compare (const gconstpointer ptr1, const gconstpointer ptr2)
	Compare the GncGUID values of two instances.
gint	qof_instance_get_editlevel (gconstpointer ptr)
int	qof_instance_version_cmp (const QofInstance *left, const QofInstance *right)
	Compare two instances, based on their last update times.
gboolean	qof_instance_get_destroying (gconstpointer ptr)
	Retrieve the flag that indicates whether or not this object is about to be destroyed.
gboolean	qof_instance_get_dirty_flag (gconstpointer ptr)
	Retrieve the flag that indicates whether or not this object has been modified.
void	qof_instance_print_dirty (const QofInstance *entity, gpointer dummy)
gboolean	qof_instance_get_dirty (QofInstance *)
gboolean	qof_instance_get_infant (const QofInstance *inst)
void	qof_instance_get (const QofInstance *inst, const gchar *first_param,...)
	Wrapper for g_object_get.
void	qof_instance_set (QofInstance *inst, const gchar *first_param,...)
	Wrapper for g_object_set Group setting multiple parameters in a single begin/commit/rollback.
guint32	qof_instance_get_idata (gconstpointer inst)
	get the instance tag number used for kvp management in sql backends.
gchar *	qof_instance_get_display_name (const QofInstance *inst)
	Returns a displayable name for this object.
GList *	qof_instance_get_referring_object_list (const QofInstance *inst)
	Returns a list of objects which refer to a specific object.
gboolean	qof_instance_refers_to_object (const QofInstance *inst, const QofInstance *ref)
	Does this object refer to a specific object.
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.
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.

Variables
GObject	QofInstance::object
QofIdType	QofInstance::e_type
	Entity type.
KvpFrame *	QofInstance::kvp_data
GObjectClass	QofInstanceClass::parent_class
gchar *(*	QofInstanceClass::get_display_name )(const QofInstance *)
gboolean(*	QofInstanceClass::refers_to_object )(const QofInstance *inst, const QofInstance *ref)
GList *(*	QofInstanceClass::get_typed_referring_object_list )(const QofInstance *inst, 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

#define QOF_INSTANCE

(

o

)

(G_TYPE_CHECK_INSTANCE_CAST ((o), QOF_TYPE_INSTANCE, QofInstance))

Definition at line 57 of file qofinstance.h.

{
    GObject object;
    QofIdType        e_type;           
    KvpFrame *kvp_data;
};
 
struct _QofInstanceClass
{
    GObjectClass parent_class;
 
    /* Returns a displayable string to represent this object */
    gchar* (*get_display_name)(const QofInstance*);
 
    /* Does this object refer to a specific object */
    gboolean (*refers_to_object)(const QofInstance* inst, const QofInstance* ref);
 
    /* Returns a list of my type of object which refers to an object */
    GList* (*get_typed_referring_object_list)(const QofInstance* inst, const QofInstance* ref);
};
 
GType qof_instance_get_type(void);
 
void qof_instance_init_data (QofInstance *, QofIdType, QofBook *);
 
/*@ dependent @*/
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);
 
/*@ dependent @*/
const GncGUID * qof_instance_get_guid (gconstpointer);
 
/*@ dependent @*/
const GncGUID * qof_entity_get_guid (gconstpointer);
 
/*@ dependent @*/
QofCollection* qof_instance_get_collection (gconstpointer inst);
 
gint qof_instance_guid_compare(const gconstpointer ptr1, const gconstpointer ptr2);
 
gint qof_instance_get_editlevel (gconstpointer ptr);
 
int qof_instance_version_cmp (const QofInstance *left, const QofInstance *right);
 
gboolean qof_instance_get_destroying (gconstpointer ptr);
 
gboolean qof_instance_get_dirty_flag (gconstpointer ptr);
 
void qof_instance_print_dirty (const QofInstance *entity, gpointer dummy);
 
#define qof_instance_is_dirty qof_instance_get_dirty
gboolean qof_instance_get_dirty (QofInstance *);
 
gboolean qof_instance_get_infant(const QofInstance *inst);
 
void qof_instance_get (const QofInstance *inst, const gchar *first_param, ...);
 
void qof_instance_set (QofInstance *inst, const gchar *first_param, ...);
 
guint32 qof_instance_get_idata (gconstpointer inst);
 
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);
 
#ifdef __cplusplus
}
#endif
 
/* @} */
/* @} */
#endif /* QOF_INSTANCE_H */

QOF_INSTANCE_CLASS

#define QOF_INSTANCE_CLASS

(

k

)

(G_TYPE_CHECK_CLASS_CAST((k), QOF_TYPE_INSTANCE, QofInstanceClass))

Definition at line 59 of file qofinstance.h.

QOF_INSTANCE_GET_CLASS

#define QOF_INSTANCE_GET_CLASS

(

o

)

(G_TYPE_INSTANCE_GET_CLASS ((o), QOF_TYPE_INSTANCE, QofInstanceClass))

Definition at line 65 of file qofinstance.h.

qof_instance_is_dirty

#define qof_instance_is_dirty   qof_instance_get_dirty

Return value of is_dirty flag.

Definition at line 166 of file qofinstance.h.

QOF_IS_INSTANCE

#define QOF_IS_INSTANCE

(

o

)

(G_TYPE_CHECK_INSTANCE_TYPE ((o), QOF_TYPE_INSTANCE))

Definition at line 61 of file qofinstance.h.

QOF_IS_INSTANCE_CLASS

#define QOF_IS_INSTANCE_CLASS

(

k

)

(G_TYPE_CHECK_CLASS_TYPE ((k), QOF_TYPE_INSTANCE))

Definition at line 63 of file qofinstance.h.

QOF_TYPE_INSTANCE

#define QOF_TYPE_INSTANCE   (qof_instance_get_type ())

Definition at line 56 of file qofinstance.h.

Function Documentation

qof_entity_get_guid()

const GncGUID * qof_entity_get_guid

(

gconstpointer

ent

)

Deprecated:

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

Definition at line 457 of file qofinstance.cpp.

{
    return ent ? qof_instance_get_guid(ent) : guid_null();
}

qof_instance_books_equal()

gboolean qof_instance_books_equal	(	gconstpointer	ptr1,
		gconstpointer	ptr2
	)

See if two QofInstances share the same book.

Definition at line 545 of file qofinstance.cpp.

{
    const QofInstancePrivate *priv1, *priv2;
 
    g_return_val_if_fail(QOF_IS_INSTANCE(ptr1), FALSE);
    g_return_val_if_fail(QOF_IS_INSTANCE(ptr2), FALSE);
 
    priv1 = GET_PRIVATE(ptr1);
    priv2 = GET_PRIVATE(ptr2);
 
    return (priv1->book == priv2->book);
}

qof_instance_copy_book()

void qof_instance_copy_book	(	gpointer	ptr1,
		gconstpointer	ptr2
	)

Copy the book from one QofInstances to another.

Definition at line 536 of file qofinstance.cpp.

{
    g_return_if_fail(QOF_IS_INSTANCE(ptr1));
    g_return_if_fail(QOF_IS_INSTANCE(ptr2));
 
    GET_PRIVATE(ptr1)->book = GET_PRIVATE(ptr2)->book;
}

qof_instance_get()

void qof_instance_get	(	const QofInstance *	inst,
		const gchar *	first_param,
			...
	)

Wrapper for g_object_get.

Definition at line 29 of file gmock-qofinstance.cpp.

{
    va_list ap;
    ASSERT_TRUE (QOF_IS_INSTANCE (inst));
 
    va_start (ap, first_prop);
    g_object_get_valist (G_OBJECT (inst), first_prop, ap);
    va_end (ap);
}

qof_instance_get_book()

QofBook * qof_instance_get_book

(

gconstpointer

inst

)

Return the book pointer.

Definition at line 521 of file qofinstance.cpp.

{
    if (!inst) return nullptr;
    g_return_val_if_fail(QOF_IS_INSTANCE(inst), nullptr);
    return GET_PRIVATE(inst)->book;
}

qof_instance_get_collection()

QofCollection * qof_instance_get_collection

(

gconstpointer

inst

)

Return the collection this instance belongs to.

Definition at line 506 of file qofinstance.cpp.

{
 
    g_return_val_if_fail(QOF_IS_INSTANCE(ptr), nullptr);
    return GET_PRIVATE(ptr)->collection;
}

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

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 631 of file qofinstance.cpp.

{
    g_return_val_if_fail(QOF_IS_INSTANCE(ptr), FALSE);
    return GET_PRIVATE(ptr)->do_free;
}

qof_instance_get_dirty()

gboolean qof_instance_get_dirty

(

QofInstance *

inst

)

Definition at line 680 of file qofinstance.cpp.

{
    QofInstancePrivate *priv;
 
    if (!inst)
    {
        return FALSE;
    }
 
    priv = GET_PRIVATE(inst);
    return priv->dirty;
}

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

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 645 of file qofinstance.cpp.

{
    g_return_val_if_fail(QOF_IS_INSTANCE(ptr), FALSE);
    return GET_PRIVATE(ptr)->dirty;
}

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 776 of file qofinstance.cpp.

{
    g_return_val_if_fail( inst != nullptr, nullptr );
 
    if ( QOF_INSTANCE_GET_CLASS(inst)->get_display_name != nullptr )
    {
        return QOF_INSTANCE_GET_CLASS(inst)->get_display_name(inst);
    }
    else
    {
        /* Not implemented - return default string */
        return g_strdup_printf("Object %s %p",
                               qof_collection_get_type(qof_instance_get_collection(inst)),
                               inst);
    }
}

qof_instance_get_editlevel()

gint qof_instance_get_editlevel

(

gconstpointer

ptr

)

Definition at line 591 of file qofinstance.cpp.

{
    g_return_val_if_fail(QOF_IS_INSTANCE(ptr), 0);
    return GET_PRIVATE(ptr)->editlevel;
}

qof_instance_get_guid()

const GncGUID * qof_instance_get_guid

(

gconstpointer

inst

)

Return the GncGUID of this instance.

Definition at line 446 of file qofinstance.cpp.

{
    QofInstancePrivate *priv;
 
    if (!inst) return nullptr;
    g_return_val_if_fail(QOF_IS_INSTANCE(inst), guid_null());
    priv = GET_PRIVATE(inst);
    return &(priv->guid);
}

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 753 of file qofinstance.cpp.

{
    if (!inst)
    {
        return 0;
    }
    g_return_val_if_fail(QOF_IS_INSTANCE(inst), 0);
    return GET_PRIVATE(inst)->idata;
}

qof_instance_get_infant()

gboolean qof_instance_get_infant

(

const QofInstance *

inst

)

Definition at line 703 of file qofinstance.cpp.

{
    g_return_val_if_fail(QOF_IS_INSTANCE(inst), FALSE);
    return GET_PRIVATE(inst)->infant;
}

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 826 of file qofinstance.cpp.

{
    GetReferringObjectHelperData data;
 
    g_return_val_if_fail( inst != nullptr, nullptr );
 
    /* scan all collections */
    data.inst = inst;
    data.list = nullptr;
 
    qof_book_foreach_collection(qof_instance_get_book(inst),
                                get_referring_object_helper,
                                &data);
    return data.list;
}

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 854 of file qofinstance.cpp.

{
    GetReferringObjectHelperData data;
 
    g_return_val_if_fail( coll != nullptr, nullptr );
    g_return_val_if_fail( ref != nullptr, nullptr );
 
    data.inst = ref;
    data.list = nullptr;
 
    qof_collection_foreach(coll, get_typed_referring_object_instance_helper, &data);
    return data.list;
}

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 869 of file qofinstance.cpp.

{
    g_return_val_if_fail( inst != nullptr, nullptr );
    g_return_val_if_fail( ref != nullptr, nullptr );
 
    if ( QOF_INSTANCE_GET_CLASS(inst)->get_typed_referring_object_list != nullptr )
    {
        return QOF_INSTANCE_GET_CLASS(inst)->get_typed_referring_object_list(inst, ref);
    }
    else
    {
        /* Not implemented - by default, loop through all objects of this object's type and check
           them individually. */
        QofCollection* coll;
 
        coll = qof_instance_get_collection(inst);
        return qof_instance_get_referring_object_list_from_collection(coll, ref);
    }
}

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 492 of file qofinstance.cpp.

{
    const QofInstancePrivate *priv1, *priv2;
 
    g_return_val_if_fail(QOF_IS_INSTANCE(ptr1), -1);
    g_return_val_if_fail(QOF_IS_INSTANCE(ptr2),  1);
 
    priv1 = GET_PRIVATE(ptr1);
    priv2 = GET_PRIVATE(ptr2);
 
    return guid_compare(&priv1->guid, &priv2->guid);
}

qof_instance_init_data()

void qof_instance_init_data	(	QofInstance *	inst,
		QofIdType	type,
		QofBook *	book
	)

Initialise the settings associated with an instance.

Definition at line 260 of file qofinstance.cpp.

{
    QofInstancePrivate *priv;
    QofCollection *col;
    QofIdType col_type;
 
    g_return_if_fail(QOF_IS_INSTANCE(inst));
    priv = GET_PRIVATE(inst);
    g_return_if_fail(!priv->book);
 
    priv->book = book;
    col = qof_book_get_collection (book, type);
    g_return_if_fail(col != nullptr);
 
    /* XXX We passed redundant info to this routine ... but I think that's
     * OK, it might eliminate programming errors. */
 
    col_type = qof_collection_get_type(col);
    if (g_strcmp0(col_type, type))
    {
        PERR ("attempt to insert \"%s\" into \"%s\"", type, col_type);
        return;
    }
    priv = GET_PRIVATE(inst);
    inst->e_type = static_cast<QofIdType>(CACHE_INSERT (type));
 
    do
    {
        guid_replace(&priv->guid);
 
        if (nullptr == qof_collection_lookup_entity (col, &priv->guid))
            break;
 
        PWARN("duplicate id created, trying again");
    }
    while (1);
 
    priv->collection = col;
 
    qof_collection_insert_entity (col, inst);
}

qof_instance_print_dirty()

void qof_instance_print_dirty	(	const QofInstance *	entity,
		gpointer	dummy
	)

Definition at line 666 of file qofinstance.cpp.

{
    QofInstancePrivate *priv;
 
    priv = GET_PRIVATE(inst);
    if (priv->dirty)
    {
        gchar guidstr[GUID_ENCODING_LENGTH+1];
        guid_to_string_buff(&priv->guid, guidstr);
        printf("%s instance %s is dirty.\n", inst->e_type, guidstr);
    }
}

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 890 of file qofinstance.cpp.

{
    g_return_val_if_fail( inst != nullptr, FALSE );
    g_return_val_if_fail( ref != nullptr, FALSE );
 
    if ( QOF_INSTANCE_GET_CLASS(inst)->refers_to_object != nullptr )
    {
        return QOF_INSTANCE_GET_CLASS(inst)->refers_to_object(inst, ref);
    }
    else
    {
        /* Not implemented - default = NO */
        return FALSE;
    }
}

qof_instance_set()

void qof_instance_set	(	QofInstance *	inst,
		const gchar *	first_param,
			...
	)

Wrapper for g_object_set Group setting multiple parameters in a single begin/commit/rollback.

Definition at line 42 of file gmock-qofinstance.cpp.

{
    va_list ap;
    ASSERT_TRUE (QOF_IS_INSTANCE (inst));
 
    va_start (ap, first_prop);
    g_object_set_valist (G_OBJECT (inst), first_prop, ap);
    va_end (ap);
}

qof_instance_set_book()

void qof_instance_set_book	(	gconstpointer	inst,
		QofBook *	book
	)

Set the book pointer.

Definition at line 529 of file qofinstance.cpp.

{
    g_return_if_fail(QOF_IS_INSTANCE(inst));
    GET_PRIVATE(inst)->book = book;
}

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 616 of file qofinstance.cpp.

{
    QofInstancePrivate *lpriv, *rpriv;
 
    if (!left && !right) return 0;
    if (!left) return -1;
    if (!right) return +1;
 
    lpriv = GET_PRIVATE(left);
    rpriv = GET_PRIVATE(right);
    return lpriv->last_update < rpriv->last_update ? -1 :
        lpriv->last_update > rpriv->last_update ? 1 : 0;
}

Variable Documentation

e_type

QofIdType QofInstance::e_type

Entity type.

Definition at line 75 of file qofinstance.h.

get_display_name

gchar *(* QofInstanceClass::get_display_name) (const QofInstance *)

Definition at line 84 of file qofinstance.h.

get_typed_referring_object_list

GList *(* QofInstanceClass::get_typed_referring_object_list) (const QofInstance *inst, const QofInstance *ref)

Definition at line 90 of file qofinstance.h.

kvp_data

KvpFrame* QofInstance::kvp_data

Definition at line 76 of file qofinstance.h.

object

GObject QofInstance::object

Definition at line 74 of file qofinstance.h.

parent_class

GObjectClass QofInstanceClass::parent_class

Definition at line 81 of file qofinstance.h.

refers_to_object

gboolean(* QofInstanceClass::refers_to_object) (const QofInstance *inst, const QofInstance *ref)

Definition at line 87 of file qofinstance.h.