/*************************************************************************** $RCSfile: dbio.h,v $ ------------------- cvs : $Id: dbio.h,v 1.9 2005/02/15 02:13:06 aquamaniac Exp $ begin : Wed Mar 31 2004 copyright : (C) 2004 by Martin Preuss email : martin@libchipcard.de *************************************************************************** * * * This library is free software; you can redistribute it and/or * * modify it under the terms of the GNU Lesser General Public * * License as published by the Free Software Foundation; either * * version 2.1 of the License, or (at your option) any later version. * * * * This library is distributed in the hope that it will be useful, * * but WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * * Lesser General Public License for more details. * * * * You should have received a copy of the GNU Lesser General Public * * License along with this library; if not, write to the Free Software * * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * * MA 02111-1307 USA * * * ***************************************************************************/ /** @file dbio.h * @short This file provides the GWEN DB import/export framework. */ #ifndef GWENHYWFAR_DBIO_H #define GWENHYWFAR_DBIO_H #include #ifdef __cplusplus extern "C" { #endif typedef struct GWEN_DBIO GWEN_DBIO; #ifdef __cplusplus } #endif /** * name of the folder below Gwen's PLUGIN folder which holds DBIO plugins */ #define GWEN_DBIO_FOLDER "dbio" #include #include #include #include #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif GWEN_LIST_FUNCTION_LIB_DEFS(GWEN_DBIO, GWEN_DBIO, GWENHYWFAR_API) GWEN_INHERIT_FUNCTION_LIB_DEFS(GWEN_DBIO, GWENHYWFAR_API) /* No trailing semicolon here because this is a macro call */ typedef enum { GWEN_DBIO_CheckFileResultOk=0, GWEN_DBIO_CheckFileResultNotOk, GWEN_DBIO_CheckFileResultUnknown } GWEN_DBIO_CHECKFILE_RESULT; typedef GWEN_DBIO* (*GWEN_DBIO_FACTORYFN)(void); typedef int (*GWEN_DBIO_IMPORTFN)(GWEN_DBIO *dbio, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 flags, GWEN_DB_NODE *db, GWEN_DB_NODE *params); typedef int (*GWEN_DBIO_EXPORTFN)(GWEN_DBIO *dbio, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 flags, GWEN_DB_NODE *db, GWEN_DB_NODE *params); typedef GWEN_DBIO_CHECKFILE_RESULT (*GWEN_DBIO_CHECKFILEFN)(GWEN_DBIO *dbio, const char *fname); /** @name Functions To Be Used By Applications * */ /*@{*/ /** * Reads data from the given GWEN_BUFFEREDIO and stores the data read * into the given DB. The stream represented by the buffered io is expected * to have the format for this particular GWEN_DBIO. */ GWENHYWFAR_API int GWEN_DBIO_Import(GWEN_DBIO *dbio, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 flags, GWEN_DB_NODE *db, GWEN_DB_NODE *params); /** * Writes data to the given GWEN_BUFFEREDIO in the format of this particular * GWEN_DBIO. */ GWENHYWFAR_API int GWEN_DBIO_Export(GWEN_DBIO *dbio, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 flags, GWEN_DB_NODE *db, GWEN_DB_NODE *params); /** * Checks whether the given file is supported by the given DBIO. */ GWENHYWFAR_API GWEN_DBIO_CHECKFILE_RESULT GWEN_DBIO_CheckFile(GWEN_DBIO *dbio, const char *fname); /** * Releases the ressources associated with the given GWEN_DBIO if the usage * counter reaches zero. */ GWENHYWFAR_API void GWEN_DBIO_free(GWEN_DBIO *dbio); /** * Increments the internal usage counter. This counter is decremented * upon @ref GWEN_DBIO_free. */ GWENHYWFAR_API void GWEN_DBIO_Attach(GWEN_DBIO *dbio); /** * Returns the name of a GWEN_DBIO. */ GWENHYWFAR_API const char *GWEN_DBIO_GetName(const GWEN_DBIO *dbio); /** * Returns a descriptive text about this particular GWEN_DBIO. */ GWENHYWFAR_API const char *GWEN_DBIO_GetDescription(const GWEN_DBIO *dbio); /** * Returns the GWEN_DBIO of the given name if it has already been * registered. */ GWENHYWFAR_API GWEN_DBIO *GWEN_DBIO_Find(const char *name); /** * Returns the path to DBIO plugins. On Windows this path is looked upon * from the registry key "Software\\Gwenhywfar\\Paths" in HKEY_CURRENT_USER. * If this key does not exist or this is called on a non-win32 platform the * compile-time value is returned. * @return 0 if value found, 1 if on win32 and the key did not exist, -1 on error * @param pbuf Buffer to which the path is appended. */ GWENHYWFAR_API int GWEN_DBIO_GetPluginPath(GWEN_BUFFER *pbuf); /*@}*/ /** @name Functions To Be Used By Inheritors * */ /*@{*/ /** * Creates the base object which is to be extended by the inheritor. */ GWENHYWFAR_API GWEN_DBIO *GWEN_DBIO_new(const char *name, const char *descr); /** * Sets the import function for this kind of GWEN_DBIO. */ GWENHYWFAR_API void GWEN_DBIO_SetImportFn(GWEN_DBIO *dbio, GWEN_DBIO_IMPORTFN f); /** * Sets the export function for this kind of GWEN_DBIO. */ GWENHYWFAR_API void GWEN_DBIO_SetExportFn(GWEN_DBIO *dbio, GWEN_DBIO_EXPORTFN f); GWENHYWFAR_API void GWEN_DBIO_SetCheckFileFn(GWEN_DBIO *dbio, GWEN_DBIO_CHECKFILEFN f); /*@}*/ /** @name Functions To Be Used By Administration Functions * * Functions in this group are to be used for administration purposes * only. */ /*@{*/ /** * If the GWEN_DBIO has been dynamically loaded (as is the case with plugins) * then the GWEN_LIBLOADER used can be stored within the GWEN_DBIO. * That way as soon as the GWEN_DBIO is released the associated dynamic * library is automatically unloaded. */ GWENHYWFAR_API GWEN_LIBLOADER *GWEN_DBIO_GetLibLoader(const GWEN_DBIO *dbio); /** * If the GWEN_DBIO has been dynamically loaded (as is the case with plugins) * then the GWEN_LIBLOADER used can be stored within the GWEN_DBIO. * That way as soon as the GWEN_DBIO is released the associated dynamic * library is automatically unloaded. */ GWENHYWFAR_API void GWEN_DBIO_SetLibLoader(GWEN_DBIO *dbio, GWEN_LIBLOADER *ll); /** * Register a new GWEN_DBIO with Gwenhywfar. This always inserts the new * GWEN_DBIO at the beginning of the internal list thus replacing an * eventually existing GWEN_DBIO with the same name. */ GWENHYWFAR_API int GWEN_DBIO_Register(GWEN_DBIO *dbio); /** * This function only loads the given plugin file, it does not register it. */ GWENHYWFAR_API GWEN_DBIO *GWEN_DBIO_LoadPluginFile(const char *modname, const char *fname); /** * This functions searches for a plugin which supports the given type in * the usual place ("GWENHYWFAR_PLUGIN/dbio/"). It does not register the * plugin. */ GWENHYWFAR_API GWEN_DBIO *GWEN_DBIO_LoadPlugin(const char *modname); /** * This functions returns the DBIO of the given name. If it already is * registered, then simply the registered one is returned. Otherwise this * function tries to load the appropriate plugin and registers it before * returning it to the caller. * The caller MUST NOT free the plugin returned, this module keeps the * ownership of the plugin. */ GWENHYWFAR_API GWEN_DBIO *GWEN_DBIO_GetPlugin(const char *modname); /*@}*/ #ifdef __cplusplus } #endif #endif /* GWENHYWFAR_DBIO_H */