IntenseFinance/gnucash
3
0
Fork 0
mirror of https://github.com/Gnucash/gnucash.git synced 2025-02-25 18:55:30 -06:00
Code Issues Packages Projects Releases Wiki Activity

update documentation structure so that doxygen generates nice output

Browse Source 
git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@9939 57a11ea4-9604-0410-9ed3-97b8803252fd
This commit is contained in:
Linas Vepstas 2004-05-06 14:42:00 +00:00
parent 31dd073300
commit d9b43bf908
27 changed files with 418 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
src/engine/gnc-date.h
View File

@ -17,19 +17,9 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
\********************************************************************/
/** @addtogroup Date
@{ */
/** @file gnc-date.h
@brief Date and Time handling routines
*
Utility functions to handle date and time (adjusting, getting
the current date, printing the date and time, etc.)
\warning HACK ALERT -- the scan and print routines should probably be moved
to somewhere else. The engine really isn't involved with things
like printing formats. This is needed mostly by the GUI and so on.
If a file-io backend needs date handling, it should do it itself,
instead of depending on the routines here.
Overall, this file is quite a mess. Note, however, that other
applications, besides just GnuCash, use this file. In particular,
GnoTime (gttr.sourcefore.net) uses this file, and this file is
@ -50,10 +40,21 @@
that is not Universal Time. Break these rules, and you will
rue the day...
\warning HACK ALERT -- the scan and print routines should probably be moved
to somewhere else. The engine really isn't involved with things
like printing formats. This is needed mostly by the GUI and so on.
If a file-io backend needs date handling, it should do it itself,
instead of depending on the routines here.
@author Copyright (C) 1997 Robin D. Clark <rclark@cs.hmc.edu>
@author Copyright (C) 1998-2001,2003 Linas Vepstas <linas@linas.org>
*/
/* @{
@file gnc-date.h
@brief Date and Time handling routines
*/
#ifndef GNC_DATE_H
#define GNC_DATE_H

4
src/engine/gnc-engine-util.h
View File

@ -19,7 +19,7 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
\********************************************************************/
/** @addtogroup Engine
/** @addtogroup Utilities
@{ */
/** @file gnc-engine-util.h
@brief GnuCash engine utility functions
@ -130,7 +130,7 @@ int qof_util_bool_to_int (const char * val);
* cached the strings are just plain C strings.
*/
/* get the gnc_string_cache. Create it if it doesn't exist already */
/** Get the gnc_string_cache. Create it if it doesn't exist already */
GCache* gnc_engine_get_string_cache(void);
void gnc_engine_string_cache_destroy (void);

16
src/engine/gnc-numeric.h
View File

@ -1,4 +1,5 @@
/********************************************************************
* gnc-numeric.h - An exact-number library for gnucash *
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
* published by the Free Software Foundation; either version 2 of *
@ -19,6 +20,19 @@
*******************************************************************/
/** @addtogroup Numeric
The 'Numeric' functions provide a way of working with rational
numbers while maintaining strict control over rounding errors
when adding rationals with different denominators. The Numeric
class is primarily used for working with monetary amounts,
where the denominator typically represents the smallest fraction
of the currency (e.g. pennies, centimes). The numeric class
can handle any fraction (e.g. twelfth's) and is not limited
to fractions that are powers of ten.
Please refer to the GnuCash texinfo documentation for details
on the numeric functions. (The texinfo will someday be
brought inline, here, into this file).
@{ */
/** @file gnc-numeric.h
@brief An exact-rational-number library for gnucash.
@ -35,7 +49,7 @@ struct _gnc_numeric {
gint64 denom;
};
/** @brief An exact-number type for gnucash.
/** @brief An exact-number type
*
* This is a rational number, defined by nominator and denominator. */
typedef struct _gnc_numeric gnc_numeric;

15
src/engine/gnc-trace.h
View File

@ -22,7 +22,7 @@
* Author: Linas Vepstas (linas@linas.org) *
\********************************************************************/
/** @addtogroup Engine
/** @addtogroup Trace
@{ */
/** @file gnc-trace.h
@ -133,11 +133,13 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
* handle.
*/
/** Log an fatal error */
#define FATAL(format, args...) { \
g_log (G_LOG_DOMAIN, G_LOG_LEVEL_ERROR, \
"Fatal Error: %s(): " format, FUNK , ## args); \
}
/** Log an serious error */
#define PERR(format, args...) { \
if (gnc_should_log (module, GNC_LOG_ERROR)) { \
g_log (G_LOG_DOMAIN, G_LOG_LEVEL_CRITICAL, \
@ -145,6 +147,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
} \
}
/** Log an warning */
#define PWARN(format, args...) { \
if (gnc_should_log (module, GNC_LOG_WARNING)) { \
g_log (G_LOG_DOMAIN, G_LOG_LEVEL_WARNING, \
@ -152,6 +155,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
} \
}
/** Print an informational note */
#define PINFO(format, args...) { \
if (gnc_should_log (module, GNC_LOG_INFO)) { \
g_log (G_LOG_DOMAIN, G_LOG_LEVEL_INFO, \
@ -159,6 +163,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
} \
}
/** Print an debugging message */
#define DEBUG(format, args...) { \
if (gnc_should_log (module, GNC_LOG_DEBUG)) { \
g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \
@ -166,6 +171,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
} \
}
/** Print an function entry debugging message */
#define ENTER(format, args...) { \
if (gnc_should_log (module, GNC_LOG_DEBUG)) { \
g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \
@ -173,6 +179,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
} \
}
/** Print an function exit debugging message */
#define LEAVE(format, args...) { \
if (gnc_should_log (module, GNC_LOG_DEBUG)) { \
g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \
@ -180,6 +187,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
} \
}
/** Print an function trace debugging message */
#define TRACE(format, args...) { \
if (gnc_should_log (module, GNC_LOG_TRACE)) { \
g_log (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, \
@ -190,7 +198,7 @@ gboolean gnc_should_log(gncModuleType module, gncLogLevel log_level);
#define DEBUGCMD(x) { if (gnc_should_log (module, GNC_LOG_DEBUG)) { (x); }}
/* -------------------------------------------------------- */
/* Infrastructure to make timing measurements for critical peices
/** Infrastructure to make timing measurements for critical peices
* of code. Used for only for performance tuning & debugging.
*/
@ -209,18 +217,21 @@ void gnc_report_clock_total (int clockno,
const char *function_name,
const char *format, ...);
/** start a particular timer */
#define START_CLOCK(clockno,format, args...) { \
if (gnc_should_log (module, GNC_LOG_INFO)) \
gnc_start_clock (clockno, module, GNC_LOG_INFO, \
__FUNCTION__, format , ## args); \
}
/** report elapsed time since last report on a particular timer */
#define REPORT_CLOCK(clockno,format, args...) { \
if (gnc_should_log (module, GNC_LOG_INFO)) \
gnc_report_clock (clockno, module, GNC_LOG_INFO, \
__FUNCTION__, format , ## args); \
}
/** report total elapsed time since timer started */
#define REPORT_CLOCK_TOTAL(clockno,format, args...) { \
if (gnc_should_log (module, GNC_LOG_INFO)) \
gnc_report_clock_total (clockno, module, GNC_LOG_INFO, \

16
src/engine/guid.h
View File

@ -27,7 +27,20 @@
#include <glib.h>
#include <stddef.h>
/** @addtogroup Entity
@{ */
/** @addtogroup GUID
Globally Unique ID's provide a way to uniquely identify
some thing. A GUID is a unique, cryptographically
random 128-bit value. The identifier is so random that
it is safe to assume that there is no other such item
on the planet Earth, and indeed, not even in the Galaxy
or beyond.
QOF GUID's can be used independently of any other subsystem
in QOF. In particular, they do not require the use of
other parts of the object subsystem.
@{ */
/** @file guid.h
@brief globally unique ID User API
@ -44,7 +57,7 @@ typedef union _GUID
} GUID;
/* number of characters needed to encode a guid as a string
/** number of characters needed to encode a guid as a string
* not including the null terminator. */
#define GUID_ENCODING_LENGTH 32
@ -180,5 +193,6 @@ guint guid_hash_to_guint(gconstpointer ptr);
GHashTable *guid_hash_table_new(void);
/* @} */
/* @} */
#endif

9
src/engine/kvp-util-p.h
View File

@ -28,7 +28,10 @@
#include "guid.h"
#include "kvp_frame.h"
/** @addtogroup KVP_Util
/** @addtogroup KVP
@{ */
/** @addtogroup KVP_Private
Private interfaces, not meant to be used by applications.
@{ */
/* @file kvp-util-p.h
* @brief misc odd-job kvp utils engine-private routines
@ -37,6 +40,8 @@
* -- these routines are private to the engine. The should not be used
* outside of the engine.
*/
/** @name KvpBag Bags of GUID Pointers */
/* @{ */
/** The gnc_kvp_bag_add() routine is used to maintain a collection
* of pointers in a kvp tree.
@ -102,5 +107,7 @@ KvpFrame * gnc_kvp_bag_find_by_guid (KvpFrame *root, const char * path,
void gnc_kvp_bag_remove_frame (KvpFrame *root, const char *path,
KvpFrame *fr);
/* @} */
/* @} */
/* @} */
#endif /* XACC_KVP_UTIL_P_H */

21
src/engine/kvp-util.h
View File

@ -20,19 +20,26 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
\********************************************************************/
/** @addtogroup KVP_Util
/** @addtogroup KVP
@{ */
/** @file kvp-util.h
@brief GnuCash KVP utility functions */
@brief GnuCash KVP utility functions
*/
/** @name Hash Utilities */
/* @{ */
#ifndef GNC_KVP_UTIL_H
#define GNC_KVP_UTIL_H
#include "config.h"
/***********************************************************************\
typedef struct {
gpointer key;
gpointer value;
} GHashTableKVPair;
g_hash_table_key_value_pairs(hash): Returns a GSList* of all the
/**
Returns a GSList* of all the
keys and values in a given hash table. Data elements of lists are
actual hash elements, so be careful, and deallocation of the
GHashTableKVPairs in the result list are the caller's
@ -45,15 +52,11 @@
*/
typedef struct {
gpointer key;
gpointer value;
} GHashTableKVPair;
GSList *g_hash_table_key_value_pairs(GHashTable *table);
void g_hash_table_kv_pair_free_gfunc(gpointer data, gpointer user_data);
/***********************************************************************/
/* @} */
/* @} */
#endif /* GNC_KVP_UTIL_H */

42
src/engine/kvp_frame.h
View File

@ -19,23 +19,8 @@
* *
\********************************************************************/
/** @addtogroup KVP
@{ */
/** @file kvp_frame.h
@brief A key-value frame system
@author Copyright (C) 2000 Bill Gribble
@author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
*/
#ifndef KVP_FRAME_H
#define KVP_FRAME_H
#include <glib.h>
#include "gnc-date.h"
#include "gnc-numeric.h"
#include "guid.h"
/** a KvpFrame is a set of associations between character strings
* A KvpFrame is a set of associations between character strings
* (keys) and KvpValue structures. A KvpValue is a union with
* possible types enumerated in the KvpValueType enum, and includes,
* among other things, ints, doubles, strings, guid's, lists, time
@ -61,10 +46,27 @@
* a key such as 'some/key' or 'some/./other/../key' because you
* may get unexpected results.
*
* In almost all cases, you want to be using the kvp_frame_set_gint64()
* routine or one of its brothers. Most of the other routines provide
* only low-level access.
*/
* To set a value into a frame, you will want to use one of the
* kvp_frame_set_xxx() routines. Most of the other routines provide
* only low-level access that you probably shouldn't use.
@{ */
/** @file kvp_frame.h
@brief A key-value frame system
@author Copyright (C) 2000 Bill Gribble
@author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
*/
#ifndef KVP_FRAME_H
#define KVP_FRAME_H
#include <glib.h>
#include "gnc-date.h"
#include "gnc-numeric.h"
#include "guid.h"
/** Opaque frame structure */
typedef struct _KvpFrame KvpFrame;
/** A KvpValue is a union with possible types enumerated in the

58
src/engine/qofbackend-p.h
View File

@ -21,21 +21,20 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/*
* FILE:
* qofbackend-p.h
*
* FUNCTION:
* Pseudo-object defining how the engine can interact with different
* back-ends (which may be SQL databases, or network interfaces to
* remote GnuCash servers. In theory, file-io should be a type of
* backend).
*
* The callbacks will be called at the appropriate times during
* a book session to allow the backend to store the data as needed.
*
*/
/** @addtogroup Object
@{ */
/** @addtogroup Object_Private
Private interfaces, not meant to be used by applications.
@{ */
/** @name Backend_Private
Pseudo-object defining how the engine can interact with different
back-ends (which may be SQL databases, or network interfaces to
remote GnuCash servers. In theory, file-io should be a type of
backend).
The callbacks will be called at the appropriate times during
a book session to allow the backend to store the data as needed.
@{ */
#ifndef QOF_BACKEND_P_H
#define QOF_BACKEND_P_H
@ -47,7 +46,7 @@
#include "qofquery.h"
#include "qofsession.h"
/*
/**
* The session_begin() routine gives the backend a second initialization
* opportunity. It is suggested that the backend check that
* the URL is syntactically correct, and that it is actually
@ -255,7 +254,7 @@ struct _QofBackend
QofBackendError last_err;
char * error_msg;
/* XXX price_lookup should be removed during the redesign
/** XXX price_lookup should be removed during the redesign
* of the SQL backend... prices can now be queried using
* the generic query mechanism.
*
@ -265,32 +264,39 @@ struct _QofBackend
*/
void (*price_lookup) (QofBackend *, gpointer);
/* XXX Export should really _NOT_ be here, but is left here for now.
/** XXX Export should really _NOT_ be here, but is left here for now.
* I'm not sure where this should be going to. It should be
* removed ASAP.
*/
void (*export) (QofBackend *, QofBook *);
};
/*
/**
* The qof_backend_set_error() routine pushes an error code onto the error
* stack. (FIXME: the stack is 1 deep in current implementation).
*
*/
void qof_backend_set_error (QofBackend *be, QofBackendError err);
/**
* The qof_backend_get_error() routine pops an error code off the error
* stack.
*
*/
QofBackendError qof_backend_get_error (QofBackend *be);
/**
* The qof_backend_set_message() assigns a string to the backend error
* message.
*
*/
void qof_backend_set_message(QofBackend *be, const char *format, ...);
/**
* The qof_backend_get_message() pops the error message string from
* the Backend. This string should be freed with g_free().
*/
void qof_backend_set_error (QofBackend *be, QofBackendError err);
QofBackendError qof_backend_get_error (QofBackend *be);
void qof_backend_set_message(QofBackend *be, const char *format, ...);
char * qof_backend_get_message(QofBackend *be);
void qof_backend_init(QofBackend *be);
/* @} */
/* @} */
/* @} */
#endif /* QOF_BACKEND_P_H */

20
src/engine/qofbackend.h
View File

@ -18,17 +18,22 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/** @addtogroup Backend
/** @addtogroup Object
@{ */
/** @file qofbackend.h
@brief api for data storage Backend
*
The 'backend' is a pseudo-object providing an interface between the
/** @addtogroup Backend
The QOF Backend is a pseudo-object providing an interface between the
engine and a persistant data store (e.g. a server, a database, or
a file). There are no backend functions that are 'public' to
a file). Backends are not meant to be used directly by an
application; instead the Session should be used to make a
connection with some particular backend.
There are no backend functions that are 'public' to
users of the engine. The backend can, however, report errors to
the GUI & other front-end users. This file defines these errors.
*
Backends are used to save and restore Entities in a Book.
@{ */
/** @file qofbackend.h
@brief API for data storage Backend
@author Copyright (C) 2000-2001 Linas Vepstas <linas@linas.org>
*/
@ -106,3 +111,4 @@ typedef void (*QofBePercentageFunc) (const char *message, double percent);
#endif /* QOF_BACKEND_H */
/**@}*/
/**@}*/

40
src/engine/qofbook-p.h
View File

@ -19,7 +19,13 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/** @addtogroup Object
@{ */
/** @addtogroup Object_Private
Private interfaces, not meant to be used by applications.
@{ */
/** @name Book_Private
@{ */
/*
* HISTORY:
* Created 2001 by Rob Browning
@ -36,50 +42,51 @@
#include "qofid.h"
#include "qofid-p.h"
/** Book structure */
struct _QofBook
{
QofEntity entity; /* Unique guid for this book. */
QofEntity entity; /**< Unique guid for this book. */
/* The KvpFrame provides a place for top-level data associated
/** The KvpFrame provides a place for top-level data associated
* with this book. */
KvpFrame *kvp_data;
/* The entity table associates the GUIDs of all the objects
/** The entity table associates the GUIDs of all the objects
* belonging to this book, with their pointers to the respective
* objects. This allows a lookup of objects based on thier guid.
*/
GHashTable * hash_of_collections;
/* In order to store arbitrary data, for extensibility, add a table
/** In order to store arbitrary data, for extensibility, add a table
* that will be used to hold arbitrary pointers.
*/
GHashTable *data_tables;
/* state flag: 'y' means 'open for editing',
/** state flag: 'y' means 'open for editing',
* 'n' means 'book is closed'
*/
char book_open;
/* dirty/clean flag. If dirty, then this book has been modified,
/** dirty/clean flag. If dirty, then this book has been modified,
* but has not yet been written out to storage (file/database)
*/
gboolean dirty;
/* version number, used for tracking multiuser updates */
/** version number, used for tracking multiuser updates */
gint32 version;
/* To be technically correct, backends belong to sessions and
/** To be technically correct, backends belong to sessions and
* not books. So the pointer below "really shouldn't be here",
* except that it provides a nice convenience, avoiding a lookup
* from the session. Better solutions welcome ... */
QofBackend *backend;
/* -------------------------------------------------------------- */
/* Backend private expansion data */
guint32 idata; /* used by the sql backend for kvp management */
/** Backend private expansion data */
guint32 idata; /**< used by the sql backend for kvp management */
};
/*
/**
* These qof_book_set_*() routines are used by backends to
* initialize the pointers in the book structure to
* something that contains actual data. These routines
@ -91,17 +98,20 @@ void qof_book_set_schedxactions( QofBook *book, GList *newList );
void qof_book_set_backend (QofBook *book, QofBackend *be);
/* The qof_book_mark_saved() routine marks the book as having been
/** The qof_book_mark_saved() routine marks the book as having been
* saved (to a file, to a database). Used by backends to mark the
* notsaved flag as FALSE just after loading. Do not use otherwise!
*/
void qof_book_mark_saved(QofBook *book);
/* Register books with the engine */
/** Register books with the engine */
gboolean qof_book_register (void);
/* deprecated */
/** @deprecated */
#define qof_book_set_guid(book,guid) \
qof_entity_set_guid(QOF_ENTITY(book), guid)
/* @} */
/* @} */
/* @} */
#endif /* QOF_BOOK_P_H */

18
src/engine/qofbook.h
View File

@ -1,4 +1,5 @@
/********************************************************************\
* qofbook.h -- Encapsulate all the information about a dataset. *
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
* published by the Free Software Foundation; either version 2 of *
@ -17,15 +18,21 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/** @addtogroup Object
@{ */
/** @addtogroup Book
A QOF Book is a dataset. It provides a single handle
through which all the various collections of entities
can be found. In particular, given only the type of
the entity, the collection can be found.
Books also provide the 'natural' place to working with
a storage backend, as a book can encapsulate everything
held in storage.
@{ */
/** @file qofbook.h
* @brief dataset access (an "accounting book")
* Encapsulate all the information about a dataset.
* See src/docs/books.txt for implementation overview.
* @brief Encapsulate all the information about a dataset.
*
* HISTORY:
* Created by Linas Vepstas December 1998
* @author Copyright (c) 1998, 1999, 2001, 2003 Linas Vepstas <linas@linas.org>
* @author Copyright (c) 2000 Dave Peticolas
*/
@ -140,3 +147,4 @@ gint64 qof_book_get_counter (QofBook *book, const char *counter_name);
#endif /* QOF_BOOK_H */
/** @} */
/** @} */

10
src/engine/qofclass-p.h
View File

@ -20,6 +20,13 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/** @addtogroup Object
@{ */
/** @addtogroup Object_Private
Private interfaces, not meant to be used by applications.
@{ */
/** @name Class_Private
@{ */
#ifndef QOF_CLASSP_H
#define QOF_CLASSP_H
@ -31,4 +38,7 @@ void qof_class_shutdown (void);
QofSortFunc qof_class_get_default_sort (QofIdTypeConst obj_name);
/* @} */
/* @} */
/* @} */
#endif /* QOF_CLASSP_H */

37
src/engine/qofclass.h
View File

@ -20,20 +20,44 @@
* *
\********************************************************************/
/** @addtogroup Entity
/** @addtogroup Object
@{ */
/** @file qofclass.h
@brief API for registering paramters on objects
@author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
@author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
/** @addtogroup Class
This file defines a class messaging system reminiscent of
traditional OO-style setter and getter interfaces to object
properties. A C-language object can declare a collection
of setters and getters on itself that can then be used
to perform run-time (as opposed to compile-time) bindings
to the object.
To put it differently, a QOF class is a set of parameter
getters and setters that are associated with an object type.
Given a pointer to some thing, the setters and getters can
be used to get and set values out of that thing. Note
that the pointer to "some thing" need not be a pointer
to a QOF Entity or Instance (although QOF classes are
more interesting when used with Entities/Instances).
What "some thing" is defined entirely by the programmer
declaring a new QOF Class.
Because a QOF Class associates getters and setters with
a type, one can then ask, at run time, what paramters
are associated with a given type, even if those paramters
were not known at compile time. Thus, a QOF Class is
sort-of like a DynAny implementation. QOF classes can
be used to provide "object introspection", i.e. asking
object to describe itself.
The QOF Query subsystem depends on QOF classes having been
declared; the Query uses the getters to get values associated
with particular instances.
@{ */
/** @file qofclass.h
@brief API for registering paramters on objects
@author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
@author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
*/
#ifndef QOF_CLASS_H
@ -172,3 +196,4 @@ QofSetterFunc qof_class_get_parameter_setter (QofIdTypeConst obj_name,
#endif /* QOF_CLASS_H */
/* @} */
/* @} */

21
src/engine/qofgobj.h
View File

@ -23,20 +23,24 @@
#ifndef QOF_GOBJ_H
#define QOF_GOBJ_H
/** @addtogroup GObject
/** @addtogroup Object
@{ */
/** @addtogroup GObject GLib GObjects
The API defined in this file allows a user to register any
GLib GObject (and any object derived from one, e.g. GTK/Gnome)
with the QOF system, as a QOF Object Class. This allows
the QOF Query routines to be used to search over collections
of GObjects.
XXX Only GObject properties are searchable, data and other
hanging off the GObject is not. Fix this. This needs fixing.
@{ */
/** @file qofgobj.h
@brief QOF to GLib GObject mapping
@author Copyright (C) 2004 Linas Vepstas <linas@linas.org>
*/
/** The API defined in this file allows a user to register any
* GLib GObject (and any object derived from one, e.g. GTK/Gnome)
* with the QOF system so that it becomes searchable.
*
* XXX Only GObject properties are searchable, data and other
* hanging off the GObject is not. Fix this.
*/
#include <glib-object.h>
#include <qof/qofbook.h>
@ -79,4 +83,5 @@ void qof_gobject_register_instance (QofBook *book, QofType, GObject *);
#endif /* QOF_GOBJ_H */
/** @} */
/** @} */

12
src/engine/qofid-p.h
View File

@ -20,6 +20,13 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/** @addtogroup Object
@{ */
/** @addtogroup Object_Private
Private interfaces, not meant to be used by applications.
@{ */
/** @name Entity_Private
@{ */
#ifndef QOF_ID_P_H
#define QOF_ID_P_H
@ -42,8 +49,11 @@ void qof_entity_set_guid (QofEntity *ent, const GUID *guid);
*/
void qof_collection_insert_entity (QofCollection *, QofEntity *);
/* reset value of dirty flag */
/** reset value of dirty flag */
void qof_collection_mark_clean (QofCollection *);
void qof_collection_mark_dirty (QofCollection *);
/* @} */
/* @} */
/* @} */
#endif /* QOF_ID_P_H */

64
src/engine/qofid.h
View File

@ -23,34 +23,48 @@
#ifndef QOF_ID_H
#define QOF_ID_H
/** @addtogroup Entity
/** @addtogroup Entity
@{ */
/** @addtogroup Entities
This file defines an API that adds types to the GUID's.
GUID's with types can be used to identify and reference
typed entities.
The idea here is that a GUID can be used to uniquely identify
some thing. By adding a type, one can then talk about the
type of thing identified. By adding a collection, one can
then work with a handle to a collection of things of a given
type, each uniquely identified by a given ID. QOF Entities
can be used independently of any other part of the system.
In particular, Entities can be useful even if one is not using
the Query ond Object parts of the QOF system.
Identifiers are globally-unique and permanent, i.e., once
an entity has been assigned an identifier, it retains that same
identifier for its lifetime.
Identifiers can be encoded as hex strings.
GUID Identifiers are 'typed' with strings. The native ids used
by QOF are defined below. An id with type QOF_ID_NONE does not
refer to any entity, although that may change (???). An id with
type QOF_ID_NULL does not refer to any entity, and will never refer
to any entity. An identifier with any other type may refer to an
actual entity, but that is not guaranteed (??? Huh?). If an id
does refer to an entity, the type of the entity will match the
type of the identifier.
If you have a type name, and you want to have a way of finding
a collection that is associated with that type, then you must use
Books.
@{ */
/** @file qofid.h
@brief QOF entity type identification system
@author Copyright (C) 2000 Dave Peticolas <peticola@cs.ucdavis.edu>
@author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
*/
/** This file defines an API that adds types to the GUID's.
* GUID's with types can be used to identify and reference
* typed entities.
*
* GUID Identifiers can be used to reference QOF Objects.
* Identifiers are globally-unique and permanent, i.e., once
* an entity has been assigned an identifier, it retains that same
* identifier for its lifetime.
*
* Identifiers can be encoded as hex strings.
*
* GUID Identifiers are 'typed' with strings. The native ids used
* by QOF are defined below. An id with type QOF_ID_NONE does not
* refer to any entity, although that may change (???). An id with
* type QOF_ID_NULL does not refer to any entity, and will never refer
* to any entity. An identifier with any other type may refer to an
* actual entity, but that is not guaranteed (??? Huh?). If an id
* does refer to an entity, the type of the entity will match the
* type of the identifier.
*/
#include <string.h>
#include "guid.h"
@ -107,17 +121,21 @@ struct QofEntity_s
QofCollection * collection;
};
/** @name QOF Entity Initialization & Shutdown
@{ */
/** Initialise the memory associated with an entity */
void qof_entity_init (QofEntity *, QofIdType, QofCollection *);
/** Release the data associated with this entity. Dont actually free
* the memory associated with the instance. */
void qof_entity_release (QofEntity *);
/* @} */
/* Return the GUID of this entity */
const GUID * qof_entity_get_guid (QofEntity *);
/** collections of entities */
/** @name Collections of Entities
@{ */
QofCollection * qof_collection_new (QofIdType type);
void qof_collection_destroy (QofCollection *col);
@ -145,8 +163,10 @@ void qof_collection_set_data (QofCollection *col, gpointer user_data);
/* Return value of 'dirty' flag on collection */
gboolean qof_collection_is_dirty (QofCollection *col);
/** @} */
#endif /* QOF_ID_H */
/** @} */
/** @} */

30
src/engine/qofinstance-p.h
View File

@ -26,38 +26,46 @@
* Copyright (C) 2003 Linas Vepstas <linas@linas.org>
*/
/** @addtogroup Object
@{ */
/** @addtogroup Object_Private
Private interfaces, not meant to be used by applications.
@{ */
/** @name Instance_Private
@{ */
#ifndef QOF_INSTANCE_P_H
#define QOF_INSTANCE_P_H
#include "qofinstance.h"
struct QofInstance_s
{
/*
/**
* UNDER CONSTRUCTION!
* This is mostly scaffolding for now,
* eventually, it may hold more fields, such as refrence counting...
*
*/
/* Globally unique id identifying this instance */
struct QofInstance_s
{
/** Globally unique id identifying this instance */
QofEntity entity;
/* The entity_table in which this instance is stored */
/** The entity_table in which this instance is stored */
QofBook * book;
/* kvp_data is a key-value pair database for storing arbirtary
/** kvp_data is a key-value pair database for storing arbirtary
* information associated with this instance.
* See src/engine/kvp_doc.txt for a list and description of the
* important keys. */
KvpFrame *kvp_data;
/* Keep track of nesting level of begin/end edit calls */
/** Keep track of nesting level of begin/end edit calls */
int editlevel;
/* In process of being destroyed */
/** In process of being destroyed */
gboolean do_free;
/* This instance has not been saved yet */
/** This instance has not been saved yet */
gboolean dirty;
};
@ -66,4 +74,8 @@ void qof_instance_mark_clean (QofInstance *);
void qof_instance_set_slots (QofInstance *, KvpFrame *);
/* @} */
/* @} */
/* @} */
#endif /* QOF_INSTANCE_P_H */

7
src/engine/qofinstance.h
View File

@ -20,6 +20,12 @@
* *
\********************************************************************/
/** @addtogroup Entity
@{ */
/** @addtogroup Instance
Qof Instances are a derived type of QofEntity. The Instance
adds some common features and functions that most objects
will want to use.
@{ */
/** @file qofinstance.h
* @brief Object instance holds common fields that most gnucash objects use.
@ -88,5 +94,6 @@ void qof_instance_gemini (QofInstance *to, QofInstance *from);
*/
QofInstance * qof_instance_lookup_twin (QofInstance *src, QofBook *book);
/* @} */
/* @} */
#endif /* QOF_INSTANCE_H */

12
src/engine/qofobject-p.h
View File

@ -18,11 +18,15 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/** @addtogroup Entity
/** @addtogroup Object
@{ */
/** @addtogroup Object_Private
Private interfaces, not meant to be used by applications.
@{ */
/** @name Objects_Private
@{ */
/** @file qofobject-p.h
* @brief the Core Object Registration/Lookup Private Interface
*
* @author Copyright (c) 2001,2002, Derek Atkins <warlord@MIT.EDU>
*/
@ -32,7 +36,7 @@
#include "qofbook.h"
#include "qofobject.h"
/* To be called from within the book */
/** To be called from within the book */
void qof_object_book_begin (QofBook *book);
void qof_object_book_end (QofBook *book);
@ -41,3 +45,5 @@ void qof_object_mark_clean (QofBook *book);
#endif /* QOF_OBJECT_P_H_ */
/** @} */
/** @} */
/** @} */

27
src/engine/qofobject.h
View File

@ -19,11 +19,24 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/** @addtogroup Entity
/** @addtogroup Object
@{ */
/** @addtogroup Objects
QOF Objects provide the means for associating
a storage backend to a set of QOF Entities. While an entity
can be though of as an identified instance of some thing, the
QOF Object provides for a way to associate instances with
a storage backend. Storage might be file or SQL storage.
QOF Objects are also used by the query system ....
XXX todo, we should split out the storage aspects of this
thing from the 'foreach' that query depends on. These are
kinad unrelated concepts.
@{ */
/** @file qofobject.h
* @brief the Core Object Registration/Lookup Interface
*
* @author Copyright (c) 2001,2002, Derek Atkins <warlord@MIT.EDU>
*/
@ -33,7 +46,7 @@
#include "qofbook.h"
#include "qofid.h"
/* Defines the version of the core object object registration
/** Defines the version of the core object object registration
* interface. Only object modules compiled against this version
* of the interface will load properly
*/
@ -84,9 +97,11 @@ struct _QofObject
/* -------------------------------------------------------------- */
/** Initialize the object registration subsystem */
/** @name Initialize the object registration subsystem */
/** @{ */
void qof_object_initialize (void);
void qof_object_shutdown (void);
/** @} */
/** Invoke the callback 'cb' on every object class definition.
* The user_data pointer is passed back to the callback.
@ -101,11 +116,10 @@ void qof_object_foreach_type (QofForeachTypeCB cb, gpointer user_data);
void qof_object_foreach (QofIdTypeConst type_name, QofBook *book,
QofEntityForeachCB cb, gpointer user_data);
/** @return a Human-readable string name for on object */
const char * qof_object_printable (QofIdTypeConst type_name, gpointer obj);
/* REGISTRATION AND REG-LOOKUP FUNCTIONS */
/** Register new types of object objects */
gboolean qof_object_register (const QofObject *object);
@ -132,3 +146,4 @@ void qof_object_foreach_backend (const char *backend_name,
#endif /* QOF_OBJECT_H_ */
/** @} */
/** @} */

14
src/engine/qofquery-deserial.h
View File

@ -20,15 +20,10 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/** @addtogroup Query_XML
/** @addtogroup Query
@{ */
/** @file qofquery-deserial.h
@brief Convert Qof-Query XML to QofQuery
Qof Queries can be convrted to and from XML so that they
can be sent from here to there. This file implements the
routine needed to convert the XML back into a C struct.
@author Copyright (C) 2004 Linas Vepstas <linas@linas.org>
*/
@ -38,8 +33,15 @@
#include <qof/qofquery.h>
#include <libxml/tree.h>
/** @addtogroup XML
Qof Queries can be converted to and from XML so that they
can be sent from here to there. This file implements the
routine needed to convert the XML back into a C struct.
@{ */
/** Given an XML tree, reconstruct and return the equivalent query. */
QofQuery *qof_query_from_xml (xmlNodePtr);
/* @} */
#endif /* QOF_QUERY_DESERIAL_H */
/* @} */

5
src/engine/qofquery-serialize.h
View File

@ -20,7 +20,7 @@
* Boston, MA 02111-1307, USA gnu@gnu.org *
* *
\********************************************************************/
/* @addtogroup Query_XML
/** @addtogroup Query
@{ */
/** @file qofquery-serialize.h
@brief Convert QofQuery to XML
@ -33,11 +33,14 @@
#include <qof/qofquery.h>
#include <libxml/tree.h>
/** @addtogroup XML Serialize Queries to/from XML */
/* @{ */
/** Take the query passed as input, and serialize it into XML.
* The DTD used will be a very qofquery specific DTD
* This is NOT the XQuery XML.
*/
xmlNodePtr qof_query_to_xml (QofQuery *q);
/* @} */
#endif /* QOF_QUERY_SERIALIZE_H */
/* @} */

29
src/engine/qofquery.h
View File

@ -20,13 +20,7 @@
* *
\********************************************************************/
/** @addtogroup Query_Core_API
@{ */
/** @file qofquery.h
@brief find objects that match a certain expression.
@author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
@author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
/** @addtogroup Query
BASIC QUERY API:
With this API you can create arbitrary logical
@ -39,6 +33,12 @@ will handle freeing it. To make compound queries, make multiple
simple queries and combine them using qof_query_merge() and the logical
operations of your choice.
SQL QUERY API:
As an alternative to building queries one predicate at a time,
you can use the SQL query interface. This interface will accept
a string containing an SQL query, parse it, convert it into the
core representation, and execute it.
STRUCTURE OF A QUERY: A Query is a logical function of any number of
QueryTerms. A QueryTerm consists of a C function pointer (the
Predicate) and a PredicateData structure containing data passed to the
@ -70,6 +70,12 @@ first to allow the evaluator to completely eliminate accounts from the
search if there's no chance of them having splits that match.
(XXX above no longer applies)
@{ */
/** @file qofquery.h
@brief find objects that match a certain expression.
@author Copyright (C) 2002 Derek Atkins <warlord@MIT.EDU>
@author Copyright (C) 2003 Linas Vepstas <linas@linas.org>
*/
@ -106,6 +112,8 @@ typedef enum {
#define QOF_QUERY_PARAM_ACTIVE "active"
/* --------------------------------------------------------- */
/** @name Query Subsystem Initialization and Shudown */
/* @{ */
/** Subsystem initialization and shutdown. Call init() once
* to initalize the query subsytem; call shutdown() to free
* up any resources associated with the query subsystem.
@ -114,9 +122,11 @@ typedef enum {
void qof_query_init (void);
void qof_query_shutdown (void);
/* @} */
/* --------------------------------------------------------- */
/** Basic API Functions */
/** @name Low-Level API Functions */
/* @{ */
GSList * qof_query_build_param_list (char const *param, ...);
@ -352,5 +362,6 @@ QofIdType qof_query_get_search_for (QofQuery *q);
/** Return the list of books we're using */
GList * qof_query_get_books (QofQuery *q);
/* @} */
#endif /* QOF_QUERYNEW_H */
/* @} */
/* @} */

6
src/engine/qofquerycore.h
View File

@ -21,7 +21,7 @@
* *
\********************************************************************/
/** @addtogroup Query_Core_Predicates
/** @addtogroup Query
@{ */
/** @file qofquerycore.h
@ -138,7 +138,8 @@ struct _QofQueryPredData {
};
/** Core Data Type Predicates */
/** @name Core Data Type Predicates
@{ */
QofQueryPredData *qof_query_string_predicate (QofQueryCompare how,
const char *str,
QofStringMatch options,
@ -187,3 +188,4 @@ char * qof_query_core_to_string (QofType, gpointer object, QofParam *getter);
#endif /* QOF_QUERYCORE_H */
/* @} */
/* @} */

51
src/engine/qofsession.h
View File

@ -21,14 +21,9 @@
\********************************************************************/
/** @addtogroup Backend
* @{ */
/** @file qofsession.h
* @brief Encapsulates a connection to a backednd (persistent store)
* @author Copyright (c) 1998, 1999, 2001, 2002 Linas Vepstas <linas@linas.org>
* @author Copyright (c) 2000 Dave Peticolas
*
* FUNCTION:
* Encapsulates a connection to a storage backend. That is, it
* The QOF Session
* encapsulates a connection to a storage backend. That is, it
* manages the connection to a persistant data store; whereas
* the backend is the thing that performs the actual datastore
* access.
@ -63,7 +58,7 @@
* level: i.e. does this user even have the authority to connect
* to and open this datastore?
*
* A breif note about books & sessions:
* A brief note about books & sessions:
* A book encapsulates the datasets manipulated by GnuCash. A book
* holds the actual data. By contrast, the session mediates the
* connection between a book (the thing that lives in virtual memory
@ -80,6 +75,13 @@
* make that assumption, in order to store the different accounting
* periods in a clump so that one can be found, given another.
*
* @{
*/
/** @file qofsession.h
* @brief Encapsulates a connection to a backend (persistent store)
* @author Copyright (c) 1998, 1999, 2001, 2002 Linas Vepstas <linas@linas.org>
* @author Copyright (c) 2000 Dave Peticolas
*/
#ifndef QOF_SESSION_H
@ -154,14 +156,20 @@ typedef void (*QofPercentageFunc) (const char *message, double percent);
void qof_session_load (QofSession *session,
QofPercentageFunc percentage_func);
/* XXX session_export really doesn't belong here */
/** XXX session_export really doesn't belong here */
gboolean qof_session_export (QofSession *tmp_session,
QofSession *real_session,
QofPercentageFunc percentage_func);
/** @name Session Errors
@{ */
/** The qof_session_get_error() routine can be used to obtain the reason
* for any failure. Calling this routine returns the current error.
*
*/
QofBackendError qof_session_get_error (QofSession *session);
const char * qof_session_get_error_message(QofSession *session);
/**
* The qof_session_pop_error() routine can be used to obtain the reason
* for any failure. Calling this routine resets the error value.
*
@ -171,9 +179,8 @@ gboolean qof_session_export (QofSession *tmp_session,
*
* See qofbackend.h for a listing of returned errors.
*/
QofBackendError qof_session_get_error (QofSession *session);
const char * qof_session_get_error_message(QofSession *session);
QofBackendError qof_session_pop_error (QofSession *session);
/* @} */
/** The qof_session_add_book() allows additional books to be added to
* a session.
@ -216,7 +223,10 @@ gboolean qof_session_save_may_clobber_data (QofSession *session);
* more than a write to the file of the current AccountGroup & etc.
* For the SQL backend, this is typically a no-op (since all data
* has already been written out to the database.
*
*/
void qof_session_save (QofSession *session,
QofPercentageFunc percentage_func);
/**
* The qof_session_end() method will release the session lock. For the
* file backend, it will *not* save the account group to a file. Thus,
* this method acts as an "abort" or "rollback" primitive. However,
@ -224,20 +234,22 @@ gboolean qof_session_save_may_clobber_data (QofSession *session);
* been written out before this, and so this routines wouldn't
* roll-back anything; it would just shut the connection.
*/
void qof_session_save (QofSession *session,
QofPercentageFunc percentage_func);
void qof_session_end (QofSession *session);
/** @name Event Handling
@{ */
/** The qof_session_events_pending() method will return TRUE if the backend
* has pending events which must be processed to bring the engine
* up to date with the backend.
*
* The qof_session_process_events() method will process any events indicated
*/
gboolean qof_session_events_pending (QofSession *session);
/** The qof_session_process_events() method will process any events indicated
* by the qof_session_events_pending() method. It returns TRUE if the
* engine was modified while engine events were suspended.
*/
gboolean qof_session_events_pending (QofSession *session);
gboolean qof_session_process_events (QofSession *session);
/* @} */
/** The xaccResolveFilePath() routine is a utility that will accept
* a fragmentary filename as input, and resolve it into a fully
@ -252,7 +264,8 @@ gboolean qof_session_process_events (QofSession *session);
char * xaccResolveFilePath (const char * filefrag);
char * xaccResolveURL (const char * pathfrag);
/** Run the RPC Server */
/** Run the RPC Server
* @deprecated will go away */
void gnc_run_rpc_server (void);
#endif /* QOF_SESSION_H */

5
src/engine/qofsql.h
View File

@ -20,7 +20,7 @@
* *
\********************************************************************/
/** @addtogroup Query_SQL
/** @addtogroup Query
@{ */
/**
@file qofsql.h
@ -36,6 +36,8 @@
#include <qof/qofbook.h>
#include <qof/qofquery.h>
/** @addtogroup SQL SQL Interface to Query
@{ */
typedef struct _QofSqlQuery QofSqlQuery;
/** Create a new SQL-syntax query machine.
@ -139,5 +141,6 @@ GList * qof_sql_query_rerun (QofSqlQuery *query);
*/
void qof_sql_query_set_kvp (QofSqlQuery *, KvpFrame *);
/** @} */
#endif /* QOF_SQL_QUERY_H */
/** @} */