# dbio.h File Reference

This file provides the GWEN DB import/export framework. More...

`#include <gwenhywfar/gwenhywfarapi.h>`
`#include <gwenhywfar/path.h>`
`#include <gwenhywfar/bufferedio.h>`
`#include <gwenhywfar/types.h>`
`#include <gwenhywfar/misc.h>`
`#include <gwenhywfar/inherit.h>`
`#include <gwenhywfar/db.h>`
`#include <gwenhywfar/libloader.h>`
`#include <gwenhywfar/error.h>`
`#include <stdio.h>`

Go to the source code of this file.

## Functions To Be Used By Applications

GWENHYWFAR_API void | GWEN_DBIO_Attach (GWEN_DBIO *dbio)
GWENHYWFAR_API GWEN_DBIO_CHECKFILE_RESULT | GWEN_DBIO_CheckFile (GWEN_DBIO *dbio, const char *fname)
GWENHYWFAR_API int | GWEN_DBIO_Export (GWEN_DBIO *dbio, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 flags, GWEN_DB_NODE *db, GWEN_DB_NODE *params)
GWENHYWFAR_API GWEN_DBIO * | GWEN_DBIO_Find (const char *name)
GWENHYWFAR_API void | GWEN_DBIO_free (GWEN_DBIO *dbio)
GWENHYWFAR_API const char * | GWEN_DBIO_GetDescription (const GWEN_DBIO *dbio)
GWENHYWFAR_API const char * | GWEN_DBIO_GetName (const GWEN_DBIO *dbio)
GWENHYWFAR_API int | GWEN_DBIO_GetPluginPath (GWEN_BUFFER *pbuf)
GWENHYWFAR_API int | GWEN_DBIO_Import (GWEN_DBIO *dbio, GWEN_BUFFEREDIO *bio, GWEN_TYPE_UINT32 flags, GWEN_DB_NODE *db, GWEN_DB_NODE *params)

## Functions To Be Used By Administration Functions

Functions in this group are to be used for administration purposes only.
GWENHYWFAR_API GWEN_LIBLOADER * | GWEN_DBIO_GetLibLoader (const GWEN_DBIO *dbio)
GWENHYWFAR_API GWEN_DBIO * | GWEN_DBIO_GetPlugin (const char *modname)
GWENHYWFAR_API GWEN_DBIO * | GWEN_DBIO_LoadPlugin (const char *modname)
GWENHYWFAR_API GWEN_DBIO * | GWEN_DBIO_LoadPluginFile (const char *modname, const char *fname)
GWENHYWFAR_API int | GWEN_DBIO_Register (GWEN_DBIO *dbio)
GWENHYWFAR_API void | GWEN_DBIO_SetLibLoader (GWEN_DBIO *dbio, GWEN_LIBLOADER *ll)

## Functions To Be Used By Inheritors

GWENHYWFAR_API GWEN_DBIO * | GWEN_DBIO_new (const char *name, const char *descr)
GWENHYWFAR_API void | GWEN_DBIO_SetCheckFileFn (GWEN_DBIO *dbio, GWEN_DBIO_CHECKFILEFN f)
GWENHYWFAR_API void | GWEN_DBIO_SetExportFn (GWEN_DBIO *dbio, GWEN_DBIO_EXPORTFN f)
GWENHYWFAR_API void | GWEN_DBIO_SetImportFn (GWEN_DBIO *dbio, GWEN_DBIO_IMPORTFN f)

## Defines

#define | GWEN_DBIO_FOLDER "dbio"

## Typedefs

typedef GWEN_DBIO | GWEN_DBIO
typedef GWEN_DBIO_CHECKFILE_RESULT(* | GWEN_DBIO_CHECKFILEFN )(GWEN_DBIO *dbio, const char *fname)
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 *(* | 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)

## Enumerations

enum | GWEN_DBIO_CHECKFILE_RESULT { GWEN_DBIO_CheckFileResultOk = 0, GWEN_DBIO_CheckFileResultNotOk, GWEN_DBIO_CheckFileResultUnknown }

## Detailed Description

This file provides the GWEN DB import/export framework.

## Define Documentation

#define GWEN_DBIO_FOLDER "dbio"

| name of the folder below Gwen's PLUGIN folder which holds DBIO plugins

## Typedef Documentation

typedef struct GWEN_DBIO GWEN_DBIO

typedef GWEN_DBIO_CHECKFILE_RESULT(* GWEN_DBIO_CHECKFILEFN)(GWEN_DBIO *dbio, const char *fname)

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*(* 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)

## Enumeration Type Documentation

enum GWEN_DBIO_CHECKFILE_RESULT

Enumerator:

  GWEN_DBIO_CheckFileResultOk |
  GWEN_DBIO_CheckFileResultNotOk |
  GWEN_DBIO_CheckFileResultUnknown |

## Function Documentation

GWENHYWFAR_API void GWEN_DBIO_Attach | ( | GWEN_DBIO * | dbio | ) |

| Increments the internal usage counter. This counter is decremented upon GWEN_DBIO_free.

GWENHYWFAR_API GWEN_DBIO_CHECKFILE_RESULT GWEN_DBIO_CheckFile | ( | GWEN_DBIO * | dbio,
|  | const char * | fname
| ) |

| Checks whether the given file is supported by the given 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
| ) |

| Writes data to the given GWEN_BUFFEREDIO in the format of this particular GWEN_DBIO.

GWENHYWFAR_API GWEN_DBIO* GWEN_DBIO_Find | ( | const char * | name | ) |

| Returns the GWEN_DBIO of the given name if it has already been registered.

GWENHYWFAR_API void GWEN_DBIO_free | ( | GWEN_DBIO * | dbio | ) |

| Releases the ressources associated with the given GWEN_DBIO if the usage counter reaches zero.

GWENHYWFAR_API const char* GWEN_DBIO_GetDescription | ( | const GWEN_DBIO * | dbio | ) |

| Returns a descriptive text about this particular GWEN_DBIO.

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 const char* GWEN_DBIO_GetName | ( | const GWEN_DBIO * | dbio | ) |

| Returns the name of a GWEN_DBIO.

GWENHYWFAR_API GWEN_DBIO* GWEN_DBIO_GetPlugin | ( | 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 int GWEN_DBIO_GetPluginPath | ( | GWEN_BUFFER * | pbuf | ) |

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.

Returns:
  0 if value found, 1 if on win32 and the key did not exist, -1 on error

Parameters:

  | pbuf | Buffer to which the path is appended.

GWENHYWFAR_API int GWEN_DBIO_Import | ( | GWEN_DBIO * | dbio,
|  | GWEN_BUFFEREDIO * | bio,
|  | GWEN_TYPE_UINT32 | flags,
|  | GWEN_DB_NODE * | db,
|  | GWEN_DB_NODE * | params
| ) |

| 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 GWEN_DBIO* GWEN_DBIO_LoadPlugin | ( | const char * | modname | ) |

| 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_LoadPluginFile | ( | const char * | modname,
|  | const char * | fname
| ) |

| This function only loads the given plugin file, it does not register it.

GWENHYWFAR_API GWEN_DBIO* GWEN_DBIO_new | ( | const char * | name,
|  | const char * | descr
| ) |

| Creates the base object which is to be extended by the inheritor.

GWENHYWFAR_API int GWEN_DBIO_Register | ( | GWEN_DBIO * | dbio | ) |

| 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 void GWEN_DBIO_SetCheckFileFn | ( | GWEN_DBIO * | dbio,
|  | GWEN_DBIO_CHECKFILEFN | f
| ) |

GWENHYWFAR_API void GWEN_DBIO_SetExportFn | ( | GWEN_DBIO * | dbio,
|  | GWEN_DBIO_EXPORTFN | f
| ) |

| Sets the export function for this kind of GWEN_DBIO.

GWENHYWFAR_API void GWEN_DBIO_SetImportFn | ( | GWEN_DBIO * | dbio,
|  | GWEN_DBIO_IMPORTFN | f
| ) |

| Sets the import function for this kind of GWEN_DBIO.

GWENHYWFAR_API void GWEN_DBIO_SetLibLoader | ( | GWEN_DBIO * | dbio,
|  | GWEN_LIBLOADER * | ll
| ) |

| 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.