pathmanager.h File Reference

#include <gwenhywfar/error.h>
#include <gwenhywfar/stringlist.h>

Go to the source code of this file.

Path Management

Gwenhywfar keeps track of registered directory paths for itself and for other libraries.

The paths are registered and stored in one global object (of GWEN_DB_NODE type), so write-access to this GWEN_PathManager functions is unfortunately not thread-safe.

This technique is used internally to determine some important paths.

GWENHYWFAR_API int GWEN_PathManager_AddPath (const char *callingLib, const char *destLib, const char *pathName, const char *pathValue)
GWENHYWFAR_API int GWEN_PathManager_AddPathFromWinReg (const char *callingLib, const char *destLib, const char *pathName, const char *keypath, const char *varname)
GWENHYWFAR_API int GWEN_PathManager_DefinePath (const char *destLib, const char *pathName)
GWENHYWFAR_API GWEN_STRINGLISTGWEN_PathManager_GetPaths (const char *destLib, const char *pathName)
GWENHYWFAR_API int GWEN_PathManager_InsertPath (const char *callingLib, const char *destLib, const char *pathName, const char *pathValue)
GWENHYWFAR_API int GWEN_PathManager_PathChanged (const char *destLib, const char *pathName)
GWENHYWFAR_API int GWEN_PathManager_RemovePath (const char *callingLib, const char *destLib, const char *pathName, const char *pathValue)
GWENHYWFAR_API int GWEN_PathManager_RemovePaths (const char *callingLib)
GWENHYWFAR_API int GWEN_PathManager_UndefinePath (const char *destLib, const char *pathName)


Function Documentation

GWENHYWFAR_API int GWEN_PathManager_AddPath ( const char *  callingLib,
const char *  destLib,
const char *  pathName,
const char *  pathValue 
)

Add a directory path entry to a registered path entry in the global GWEN_PathManager.

Parameters:
callingLib The name of the library that adds this path entry.
destLib The name of the library that this path is supposed to belong to.
pathName A string identifier for this registered path.
pathValue The actual directory path that should be added to this registered path.
Returns:
Zero on success, or GWEN_ERROR_NOT_FOUND if the pathName was not found.

GWENHYWFAR_API int GWEN_PathManager_AddPathFromWinReg ( const char *  callingLib,
const char *  destLib,
const char *  pathName,
const char *  keypath,
const char *  varname 
)

Add a directory path entry to a registered path entry in the global GWEN_PathManager by looking up the directory path in the Windows registry.

On non-windows platforms, the function does nothing and returns zero, so you can safely call this in your multi-platform code.

Parameters:
callingLib The name of the library that adds this path entry.
destLib The name of the library that this path is supposed to belong to.
pathName A string identifier for this registered path.
keypath The key's path in the windows registry under HKEY_LOCAL_USER, e.g. "Software\MyProgram\Paths".
varname The variable name of the string variable with the actual directory path.
Returns:
Zero on success, or nonzero if the pathName or the registry key was not found.

GWENHYWFAR_API int GWEN_PathManager_DefinePath ( const char *  destLib,
const char *  pathName 
)

Register a path to be managed by the global GWEN_PathManager module. This must be done before calling one of the other functions of this group. The actual path is not yet set.

Parameters:
destLib The name of the library that this path is supposed to belong to.
pathName A string identifier for this registered path.
Returns:
Zero on success, or GWEN_ERROR_INVALID if the pathName already exists.

GWENHYWFAR_API GWEN_STRINGLIST* GWEN_PathManager_GetPaths ( const char *  destLib,
const char *  pathName 
)

Returns a string list of all path entries that exist under the registered pathName.

Parameters:
destLib The name of the library that this path is supposed to belong to.
pathName A string identifier for this registered path.
Returns:
A newly allocated GWEN_STRINGLIST with all added path entries, or NULL if no path entry or no registered pathName exists. Delete this list with GWEN_StringList_free() when no longer needed.

GWENHYWFAR_API int GWEN_PathManager_InsertPath ( const char *  callingLib,
const char *  destLib,
const char *  pathName,
const char *  pathValue 
)

Insert a directory path entry to a registered path entry in the global GWEN_PathManager. While GWEN_PathManager_AddPath adds a path to the end of the list for this particular pathName this function here inserts it at the beginning of the list. This can be used e.g. to ensure that plugins/files from a given path take precedence over already added paths.

Parameters:
callingLib The name of the library that adds this path entry.
destLib The name of the library that this path is supposed to belong to.
pathName A string identifier for this registered path.
pathValue The actual directory path that should be added to this registered path.

GWENHYWFAR_API int GWEN_PathManager_PathChanged ( const char *  destLib,
const char *  pathName 
)

This function checks whether the path list for pathName has changed since the last call to this function (i.e. whether paths have been added, inserted or removed).

Parameters:
destLib The name of the library that this path is supposed to belong to.
pathName A string identifier for this registered path.
Returns:
Zero on success, or GWEN_ERROR_NOT_FOUND if the pathName was not found.

GWENHYWFAR_API int GWEN_PathManager_RemovePath ( const char *  callingLib,
const char *  destLib,
const char *  pathName,
const char *  pathValue 
)

Removes a directory path entry from a registered path entry in the global GWEN_PathManager.

Parameters:
callingLib The name of the library that added this path entry.
destLib The name of the library that this path is supposed to belong to.
pathName A string identifier for this registered path.
pathValue The actual directory path that should be added to this registered path.
Returns:
Zero on success, or nonzero if the pathName was not found.

GWENHYWFAR_API int GWEN_PathManager_RemovePaths ( const char *  callingLib  ) 

Removes all directory path entries that were registered by the callingLib from the global GWEN_PathManager.

Parameters:
callingLib The name of the library that added path entries.
Returns:
Zero on success.

GWENHYWFAR_API int GWEN_PathManager_UndefinePath ( const char *  destLib,
const char *  pathName 
)

Unregister a path that was registered by GWEN_PathManager_DefinePath().

Parameters:
destLib The name of the library that this path is supposed to belong to.
pathName A string identifier for this registered path.
Returns:
Zero on success, or GWEN_ERROR_NOT_FOUND if the pathName was not found.


Generated on Sat Sep 16 11:19:16 2006 for gwenhywfar by  doxygen 1.4.7