/************************************************************************
 * $Id: ODB.API.spec.txt,v 1.1 2000/03/16 00:23:27 jmayer Exp $
 *
 * Provides a consistent API for dealing with a persistent object storage
 * system (the ODB), insulating the user from the details of the
 * implementation of the DB (postgres, berkeleyDB, v-memory, text files,
 * XML, punched tape, etc.)
 ************************************************************************/

/*
 * odb_ret
 *
 * An enum specifying all possible return codes for all functions.
 */
typedef enum {
	ODB_RET_SUCCESS	= 0,
	ODB_RET_BAD_HANDLE = -1,
	ODB_RET_ON_FIRE = -2,
	...
} odb_ret;


/* 
 * odb_scalar
 *
 * this is how scalar data is fed to / retreived from the ODB 
 */
typedef struct {
	int length; /* length (in bytes) of data pointed to */
	void *data; 
} odb_scalar;


/* 
 * odb_handle
 * 
 * this is the magic connection.  It holds info about this transaction,
 * this connection, and anything that is global to a db session
 */
typedef struct {
	/* ...whatever... */
} odb_handle;


/*
 * odb_oid
 *
 * the abstract type for an oid
 */
typedef struct {
	uint32 oid;
} odb_oid;


/*
 * odb_oidlist
 *
 * the type for a list of oids - a linked list, ending in NULL
 */
typedef struct odb_oidlist_t {
	odb_oid oid;
	struct odb_oidlist_t *next;
} odb_oidlist;


/*
 * odb_datatype
 *
 * how we represent a datatype
 */
typedef struct {
	int domain;	  /* intern, re, extern */
	char *name;	  /* "int", "float", "regexp" */
	char *validator;  /* the regexp or extern validator */
} odb_datatype;

#define  ODB_DATATYPE_INT	1
#define  ODB_DATATYPE_EXT	2
#define  ODB_DATATYPE_RE	3


/*
 * These are the routine primitives provided by the ODB.
 * Assuming that SM and ED do their job, these should never fail.  All
 * failures (type errors, unknown property etc..) should be caught before
 * we ever get around to calling these.  Of course, we will handle errors,
 * but god help us if we get them :)
 */

odb_handle *odb_connect(...);
void odb_disconnect(odb_handle *h);


/* commands from read state */
odb_ret odb_find(odb_handle *h, char *criteria, odb_oid *root, 
		 odb_oidlist *result);
odb_ret odb_oidof(odb_handle *h, char *path, odb_oid *result);
odb_ret odb_get(odb_handle *h, odb_oid *oid, char *prop, odb_scalar *result);
odb_ret odb_type(odb_handle *h, odb_oid *oid, char *prop, 
		 odb_datatype *result);
odb_ret odb_list(odb_handle *h, odb_oid *oid, char *prop, odb_oidlist *result);
odb_ret odb_classver(odb_handle *h, char *class, char **result);
odb_ret odb_structure(odb_handle *h, char *class, char **result);
odb_ret odb_classlist(odb_handle *h, char **result);
odb_ret odb_define(odb_handle *h, char *class, char *isa, char *ver, char *key, 
		   char *descr, char *props);
odb_ret odb_undefine(odb_handle *h, char *class, int destroy);
odb_ret odb_extend(odb_handle *h, char *class, char *props, char *sig, 
		   char *ver, char **resultinfo);
odb_ret odb_classacl(odb_handle *h, char *class, int mode, odb_oid *oid);


/* commands from transaction state */
odb_ret odb_new(odb_handle *h, char *class, odb_oid *oid);
odb_ret odb_destroy(odb_handle *h, odb_oid *oid);
odb_ret odb_set(odb_handle *h, odb_oid *oid, char *prop, odb_scalar *value);
odb_ret odb_listadd(odb_handle *h, odb_oid *oid, char *prop, odb_oid *newoid);
odb_ret odb_listrm(odb_handle *h, odb_oid *oid, char *prop, odb_oid *rmoid);
odb_ret odb_lock(odb_handle *h, odb_oidlist *oids);
odb_ret odb_unlock(odb_handle *h, odb_oidlist *oids);


odb_ret odb_commit(odb_handle *h);


/************************************************************************
 * Change Log
 ************************************************************************
 * $Log: ODB.API.spec.txt,v $
 * Revision 1.1  2000/03/16 00:23:27  jmayer
 * Copying over the old project documentation.  Much of this still needs
 * to be brought up-to-date.
 *
 * Revision 1.4  1999/12/08 19:55:42  thockin
 * * Wed Dec 08 1999  Tim Hockin <thockin@cobalt.com>
 *   - Added the start of the FS ODB implementation
 *   - Some minor tweaks to various files
 *   - The odb.h and ODB.API doc are out of sync - need to be merged
 *
 * Revision 1.3  1999/12/04 20:56:11  jmayer
 * tweak: added bad state msg to CSCP
 *
 * Revision 1.2  1999/12/03 22:28:00  thockin
 * Fri Dec 03 1999  Tim Hockin <thockin@cobalt.com>
 * - Small fix to CSCP spec
 * - ODB API fleshed out. - comments?
 *
 * Revision 1.1  1999/12/02 08:57:00  jmayer
 * Beginning the ODB API spec.  This document is a work in progress (ie. 5%
 * complete).  But heck, I'll check it into CVS anyway.  whee!
 *
 * I got far less done today than I wanted to.  But hey, talking about
 * designing is sometimes as important as designing, eh?  There's always
 * tomorrow.
 *
 ************************************************************************/
