Trial Baloon (was Re: GncBusiness v. GNCSession)

[Derek Atkins]

Ok, here is a straw-man proposal...  Note that anywhere that I use
GNCSession I could change it to GNCBook.  I chose GNCSession for no
particular reason, other than GNCSession is currently what is passed
around everywhere.

I'm posting this to try to formalize what we've been discussion and
try to refocus the discussion.  Something concrete should be able
to help (I hope).

-derek

/* The Core Object API:  Every core object must register one
 * of these with Gnucash at initialization-time.
 */
typedef struct GncCore_s {
  int		version;	/* This is the version of the GncCore API */
  const char *	name;		/* The name of the module.  Must be unique */
  const char *	desc;		/* Printable "description" of the module,
				 * used for user-interaction with this data
				 * type
				 */
  void		(*create) (GNCSession *session);
				/* A new session is being created; build any
				 * tables we need and store them in the
				 * session 
				 */
  void		(*finalize) (GNCSession *session);
				/* We're about to end the session, be
				 * sure to clean up in preparation for
				 * exiting.
				 */
  void		(*destroy) (GNCSession *session);
				/* The session is being destroyed; destroy
				 * any data we may be storing
				 */
  gpointer	(*lookup) (GNCSession *session, const GUID *guid);
				/* Lookup the GUID and return the object.
				 * Note that this "replaces" the GNCId
				 * module (or at least extends it
				 */
  const char *	(*printName) (gpointer object);
				/* Return the printable name of the object */
  void		(*begin_edit) (gpointer object);
				/* Lock this object for editing */
  void		(*commit_edit) (gpointer object);
				/* Commit edits to this object */
  /* Question: Do we need a rollback edit? */

  /* TODO:
   * 	attach to a Backend
   *	perform Querys (need some query method?)
   *
   * Note: if we assume SQL, then can we provide the following method
   * to build up a SQL query string based upon the GNCQuery?
   * Considering that we can do it in a central location, can we not
   * build it piecemeal?
   */
  char *	(*query) (GNCSession *session, GNCQuery *query,
			  char *start_query);
} GncCore;


/* Register a new core object with Gnucash. */
void gncCoreRegister (const GncCore *objectDef);

/* return the printable description for object type "name" */
const char * gncCoreTypeName (const char *name);

/* Add arbitrary data to the GNCSession */
void gncSessionAddPointer (GNCSession *session, const char * data_name,
			   gpointer object);

/* Obtain arbitrary data from the GNCSession */
gpointer gncSessionGetPointer (GNCSession *session, const char *data_name);
  

/* We also need helper functions for each method in GncCore that
 * that looks something like the following function.  Multiply this
 * by all methods.
 */
const char * gncCorePrintName (const char *name, gpointer object)
{
  const GncCore *obj = lookupByName (name);
  if (obj && obj->printName)
    return (obj->printName(object));
  return NULL;
}


-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord@MIT.EDU                        PGP key available