Data Structures
struct	QofInstance_s
struct	_QofInstanceClass
Files
file	qofinstance.h
	Object instance holds common fields that most gnucash objects use.
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 struct _QofInstanceClass	QofInstanceClass
typedef struct QofInstance_s	QofInstance
typedef struct _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 GncGUID *	qof_instance_get_guid (gconstpointer)
const GncGUID *	qof_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.
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.

Define Documentation

#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

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

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

gboolean qof_instance_books_equal	(	gconstpointer	ptr1,
		gconstpointer	ptr2
	)

See if two QofInstances share the same book.

Definition at line 568 of file qofinstance.c.

{
    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);
}

void qof_instance_copy_book	(	gpointer	ptr1,
		gconstpointer	ptr2
	)

Copy the book from one QofInstances to another.

Definition at line 559 of file qofinstance.c.

{
    g_return_if_fail(QOF_IS_INSTANCE(ptr1));
    g_return_if_fail(QOF_IS_INSTANCE(ptr2));

    GET_PRIVATE(ptr1)->book = GET_PRIVATE(ptr2)->book;
}

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

{
    g_return_if_fail(QOF_IS_INSTANCE(to));
    g_return_if_fail(QOF_IS_INSTANCE(from));

    GET_PRIVATE(to)->guid = GET_PRIVATE(from)->guid;
}

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

{
    g_return_if_fail(QOF_IS_INSTANCE(to));
    g_return_if_fail(QOF_IS_INSTANCE(from));
    GET_PRIVATE(to)->version = GET_PRIVATE(from)->version;
}

void qof_instance_copy_version_check	(	gpointer	to,
		gconstpointer	from
	)

copy the instance version_check number

Definition at line 785 of file qofinstance.c.

{
    g_return_if_fail(QOF_IS_INSTANCE(to));
    g_return_if_fail(QOF_IS_INSTANCE(from));
    GET_PRIVATE(to)->version_check = GET_PRIVATE(from)->version_check;
}

QofBook* qof_instance_get_book ( gconstpointer )

Return the book pointer

Definition at line 544 of file qofinstance.c.

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

QofCollection* qof_instance_get_collection ( gconstpointer inst )

Return the collection this instance belongs to

Definition at line 529 of file qofinstance.c.

{

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

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

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

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

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

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

{
    g_return_val_if_fail( inst != NULL, NULL );

    if ( QOF_INSTANCE_GET_CLASS(inst)->get_display_name != NULL )
    {
        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);
    }
}

const GncGUID* qof_instance_get_guid ( gconstpointer )

Return the GncGUID of this instance

Definition at line 469 of file qofinstance.c.

{
    QofInstancePrivate *priv;

    if (!inst) return NULL;
    g_return_val_if_fail(QOF_IS_INSTANCE(inst), guid_null());
    priv = GET_PRIVATE(inst);
    return &(priv->guid);
}

guint32 qof_instance_get_idata ( gconstpointer inst )

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

Definition at line 792 of file qofinstance.c.

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

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

{
    GetReferringObjectHelperData data;

    g_return_val_if_fail( inst != NULL, NULL );

    /* scan all collections */
    data.inst = inst;
    data.list = NULL;

    qof_book_foreach_collection(qof_instance_get_book(inst),
                                get_referring_object_helper,
                                &data);
    return data.list;
}

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

{
    GetReferringObjectHelperData data;

    g_return_val_if_fail( coll != NULL, NULL );
    g_return_val_if_fail( ref != NULL, NULL );

    data.inst = ref;
    data.list = NULL;

    qof_collection_foreach(coll, get_typed_referring_object_instance_helper, &data);
    return data.list;
}

KvpFrame* qof_instance_get_slots ( const QofInstance * )

Return the pointer to the kvp_data

Definition at line 582 of file qofinstance.c.

{
    if (!inst) return NULL;
    return inst->kvp_data;
}

GType qof_instance_get_type ( void )

Return the GType of a QofInstance

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

{
    g_return_val_if_fail( inst != NULL, NULL );
    g_return_val_if_fail( ref != NULL, NULL );

    if ( QOF_INSTANCE_GET_CLASS(inst)->get_typed_referring_object_list != NULL )
    {
        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);
    }
}

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

{
    g_return_val_if_fail(QOF_IS_INSTANCE(inst), 0);
    return GET_PRIVATE(inst)->version;
}

guint32 qof_instance_get_version_check ( gconstpointer inst )

Get the instance version_check number

Definition at line 771 of file qofinstance.c.

{
    g_return_val_if_fail(QOF_IS_INSTANCE(inst), 0);
    return GET_PRIVATE(inst)->version_check;
}

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

{
    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);
}

void qof_instance_init_data	(	QofInstance *	,
		QofIdType	,
		QofBook *
	)

Initialise the settings associated with an instance

Definition at line 282 of file qofinstance.c.

{
    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 != NULL);

    /* 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 (safe_strcmp(col_type, type))
    {
        PERR ("attempt to insert \"%s\" into \"%s\"", type, col_type);
        return;
    }
    priv = GET_PRIVATE(inst);
    inst->e_type = CACHE_INSERT (type);

    do
    {
        guid_new(&priv->guid);

        if (NULL == 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);
}

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

Does this object refer to a specific object

Definition at line 933 of file qofinstance.c.

{
    g_return_val_if_fail( inst != NULL, FALSE );
    g_return_val_if_fail( ref != NULL, FALSE );

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

void qof_instance_set_book	(	gconstpointer	inst,
		QofBook *	book
	)

Set the book pointer

Definition at line 552 of file qofinstance.c.

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

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

{
    g_return_if_fail(QOF_IS_INSTANCE(ptr));
    GET_PRIVATE(ptr)->do_free = value;
}

void qof_instance_set_dirty ( QofInstance * inst )

Set the dirty flag.

Sets this instance AND the collection as dirty.

Definition at line 727 of file qofinstance.c.

{
    QofInstancePrivate *priv;
    QofCollection *coll;

    priv = GET_PRIVATE(inst);
    priv->dirty = TRUE;
    if (!qof_get_alt_dirty_mode())
    {
        coll = priv->collection;
        qof_collection_mark_dirty(coll);
    }
}

void qof_instance_set_guid	(	gpointer	inst,
		const GncGUID *	guid
	)

Set the GncGUID of this instance

Definition at line 486 of file qofinstance.c.

{
    QofInstancePrivate *priv;
    QofInstance *inst;
    QofCollection *col;

    g_return_if_fail(QOF_IS_INSTANCE(ptr));

    inst = QOF_INSTANCE(ptr);
    priv = GET_PRIVATE(inst);
    if (guid_equal (guid, &priv->guid))
        return;

    col = priv->collection;
    qof_collection_remove_entity(inst);
    priv->guid = *guid;
    qof_collection_insert_entity(col, inst);
}

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

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

void qof_instance_set_version_check	(	gpointer	inst,
		guint32	value
	)

Set the instance version_check number

Definition at line 778 of file qofinstance.c.

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

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

{
    QofInstancePrivate *lpriv, *rpriv;

    if (!left && !right) return 0;
    if (!left) return -1;
    if (!right) return +1;

    lpriv = GET_PRIVATE(left);
    rpriv = GET_PRIVATE(right);
    if (lpriv->last_update.tv_sec  < rpriv->last_update.tv_sec) return -1;
    if (lpriv->last_update.tv_sec  > rpriv->last_update.tv_sec) return +1;
    if (lpriv->last_update.tv_nsec < rpriv->last_update.tv_nsec) return -1;
    if (lpriv->last_update.tv_nsec > rpriv->last_update.tv_nsec) return +1;
    return 0;
}

Data Structures

Files

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Function Documentation