QofBackend / QofSession changes in next commit.

[Neil Williams]

I'm considering adding a check_data_type prototype to QofBackendProvider which 
will need to return TRUE if any backend is to be loaded for a particular 
path.

The function will ONLY be called when the access_method matches your backend 
provider setting. 

Initially, this would be wrapped in a #ifndef GNUCASH_MAJOR_VERSION so it will 
not be active. Eventually, each backend will need a check_data_type function 
that returns TRUE to be passed any data.

Having already checked the access_method, the session (via qof_session_begin) 
will call QofBackendProvider->check_data_type to check that the incoming path 
contains data that the backend provider can open. The backend provider could 
also check if it can contact it's storage media (disk, network, server, etc.) 
and return FALSE if it can't.  Malformed file URL's would be handled the same 
way.

If the file is empty but usable, (e.g. a new session), the check_data_type 
routine should return TRUE - QOF will determine which backend to use out of 
those using the same access_method when it comes to time to save the data.

/** \brief Distinguish two providers with same access method.
  
  More than 1 backend can be registered under the same access_method,
  so each one is passed the path to the data (e.g. a file) and
  should return TRUE only:
-# if the backend recognises the type as one that it can load and write or 
-#if the path contains no data but can be used (e.g. a new session).
  
  \note If the backend can cope with more than one type, the backend
  should not try to store or cache the sub-type for this data.
  It is sufficient only to return TRUE if any ONE of the supported
  types match the incoming data. The backend should not assume that
  returning TRUE will mean that the data will naturally follow.
  */
  gboolean (*check_data_type) (const char*);

Note the comment about not assuming data will follow - it is already possible 
for the backend to be changed before the data is saved, no matter which of 
the initial backends were chosen for the access_method. This was implemented 
for partial books used by QSF.
 
The GnuCash file backend will use something like:
static gboolean
gnc_determine_file_type (const char *path)
{
	struct stat sbuf;

	if (stat(path, &sbuf) <0) { return FALSE; }
	if (sbuf.st_size == 0) { return TRUE; }
	if(gnc_is_xml_data_file_v2(path))   { return TRUE; } 
	else if(gnc_is_xml_data_file(path)) { return TRUE; } 
	else if(is_gzipped_file(path))      { return TRUE; }
	else if(gnc_is_bin_file(path))      { return TRUE; }
	return FALSE;
}	

and in the QofBackendProvider declaration:
	prov->check_data_type = gnc_determine_file_type;

The QSF backend will use a very similar routine.

The reasons are:
1. Splitting the gnc-backend-file into a separate library for CashUtil means 
that the current file type check cannot work - the gnc and QSF code in the 
current function will be in different libraries.
2. There is no inherent reason why a QofBackend should have an entire 
access_method all to itself.
3. Loading QofBackend's dynamically using dlopen makes it possible that 
additional backend libraries could be available once QOF is an external 
library itself. e.g. a new backend could be compiled into a future release of 
QOF, independent of any backends used by applications linked against QOF.

-- 

Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20050830/b8224b2d/attachment.bin