gwenhywfar  5.11.1beta
Enumerations
pathmanager.h File Reference
#include <gwenhywfar/error.h>
#include <gwenhywfar/stringlist.h>
#include <gwenhywfar/buffer.h>

Go to the source code of this file.

Enumerations

enum  GWEN_PATHMANAGER_RELMODE { GWEN_PathManager_RelModeCwd =0 , GWEN_PathManager_RelModeExe , GWEN_PathManager_RelModeHome }
 

Functions

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_AddRelPath (const char *callingLib, const char *destLib, const char *pathName, const char *pathValue, GWEN_PATHMANAGER_RELMODE rm)
 
GWENHYWFAR_API int GWEN_PathManager_DefinePath (const char *destLib, const char *pathName)
 
GWENHYWFAR_API int GWEN_PathManager_FindFile (const char *destLib, const char *pathName, const char *fileName, GWEN_BUFFER *fbuf)
 
GWENHYWFAR_API int GWEN_PathManager_GetMatchingFilesRecursively (const char *destLib, const char *pathName, const char *subFolderName, GWEN_STRINGLIST *sl, const char *mask)
 
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_InsertRelPath (const char *callingLib, const char *destLib, const char *pathName, const char *pathValue, GWEN_PATHMANAGER_RELMODE rm)
 
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)
 

Enumeration Type Documentation

◆ GWEN_PATHMANAGER_RELMODE

Enumerator
GWEN_PathManager_RelModeCwd 

relative to the current working directory at calling time

GWEN_PathManager_RelModeExe 

This mode is interpreted differently in Windows and non-Windows systems due to the different handling of paths.

  • Windows: Releative to the folder in which the currently running executable is located.
  • Non-Windows: Relative to the installation prefix of the currently running executable
GWEN_PathManager_RelModeHome 

relative to the user's home directory

Definition at line 38 of file pathmanager.h.

Function Documentation

◆ GWEN_PathManager_AddPath()

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
callingLibThe name of the library that adds this path entry.
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
pathValueThe actual directory path that should be added to this registered path.
rmpath relative to what? (see GWEN_PathManager_RelModeCwd)
Returns
Zero on success, or GWEN_ERROR_NOT_FOUND if the pathName was not found.

◆ GWEN_PathManager_AddPathFromWinReg()

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.

Note: Gwenhywfar-2.6.0 and older used to lookup the paths under HKEY_CURRENT_USER, but with gwen-2.6.1 this was changed to HKEY_LOCAL_MACHINE because we're talking about installation paths as opposed to per-user configuration settings.

Parameters
callingLibThe name of the library that adds this path entry.
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
keypathThe key's path in the windows registry under HKEY_LOCAL_MACHINE, e.g. "Software\MyProgram\Paths".
varnameThe 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.

◆ GWEN_PathManager_AddRelPath()

GWENHYWFAR_API int GWEN_PathManager_AddRelPath ( const char *  callingLib,
const char *  destLib,
const char *  pathName,
const char *  pathValue,
GWEN_PATHMANAGER_RELMODE  rm 
)

Same as GWEN_PathManager_AddPath but the path to add is given relative to some directory. The "relmode" argument chooses the base directory to which the given sub-directory path is appended and the result is added to this PathManager:

  • RelModeCwd appends the path to the current working directory at the time of calling. So future changes to the CWD do not affect this setting.
  • RelModeExe appends the path to the prefix of the installation location of the calling executable. This function looks up the current working directory, removes the last component (i.e. the "/bin/") to get the prefix, then adds the given relative path to it.
  • RelModeHome appends the path to the return value of GWEN_Directory_GetHomeDirectory().

All three variantes will then add the resulting path to the PathManager.

Parameters
callingLibThe name of the library that adds this path entry.
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
pathValueThe actual directory path relative to the prefix of the current working directory that should be added to this registered path.
rmThe Flag to choose the starting directory to which the path is appended.
Returns
Zero on success, or GWEN_ERROR_NOT_FOUND if the pathName was not found.

◆ GWEN_PathManager_DefinePath()

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
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
Returns
Zero on success, or GWEN_ERROR_INVALID if the pathName already exists.

◆ GWEN_PathManager_FindFile()

GWENHYWFAR_API int GWEN_PathManager_FindFile ( const char *  destLib,
const char *  pathName,
const char *  fileName,
GWEN_BUFFER fbuf 
)

This functions tries to find a given file using all path entries under the registered pathName.

Parameters
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
fileNameName of the file (may contain partial paths, like in "dialogs/testdialog.xml"
fbufbuffer to receive the full path to access the file
Returns
0 on success (in that case fbuf will be filled), an error code otherwise.

◆ GWEN_PathManager_GetMatchingFilesRecursively()

GWENHYWFAR_API int GWEN_PathManager_GetMatchingFilesRecursively ( const char *  destLib,
const char *  pathName,
const char *  subFolderName,
GWEN_STRINGLIST sl,
const char *  mask 
)

This function calls GWEN_Directory_GetMatchingFilesRecursively() on every path entry under the registered pathName.

Returns
0 if ok, error code on error
Parameters
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
subFolderNameif given then this folder name is appended to every path under the registered pathName before caling GWEN_Directory_GetMatchingFilesRecursively() on it. You can use this parameter to search only in specific sub folders of the paths.
slstring list to receive the paths of all matching files

◆ GWEN_PathManager_GetPaths()

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
destLibThe name of the library that this path is supposed to belong to.
pathNameA 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.

◆ GWEN_PathManager_InsertPath()

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
callingLibThe name of the library that adds this path entry.
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
pathValueThe actual directory path that should be added to this registered path.

◆ GWEN_PathManager_InsertRelPath()

GWENHYWFAR_API int GWEN_PathManager_InsertRelPath ( const char *  callingLib,
const char *  destLib,
const char *  pathName,
const char *  pathValue,
GWEN_PATHMANAGER_RELMODE  rm 
)

Same as GWEN_PathManager_InsertPath but the path to insert is given relative to some directory. The "relmode" argument chooses the base directory to which the given sub-directory path is appended and the result is added to this PathManager:

  • RelModeCwd appends the path to the current working directory at the time of calling. So future changes to the CWD do not affect this setting.
  • RelModeExe appends the path to the prefix of the installation location of the calling executable. This function looks up the current working directory, removes the last component (i.e. the "/bin/") to get the prefix, then adds the given relative path to it.
  • RelModeHome appends the path to the return value of GWEN_Directory_GetHomeDirectory().

All three variantes will then add the resulting path to the PathManager.

Parameters
callingLibThe name of the library that adds this path entry.
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
pathValueThe actual directory path relative to the prefix of the current working directory that should be added to this registered path.
rmThe Flag to choose the starting directory to which the path is appended.
Returns
Zero on success, or GWEN_ERROR_NOT_FOUND if the pathName was not found.

◆ GWEN_PathManager_PathChanged()

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
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
Returns
Zero on success, or GWEN_ERROR_NOT_FOUND if the pathName was not found.

◆ GWEN_PathManager_RemovePath()

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
callingLibThe name of the library that added this path entry.
destLibThe name of the library that this path is supposed to belong to.
pathNameA string identifier for this registered path.
pathValueThe actual directory path that should be added to this registered path.
Returns
Zero on success, or nonzero if the pathName was not found.

◆ GWEN_PathManager_RemovePaths()

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
callingLibThe name of the library that added path entries.
Returns
Zero on success.

◆ GWEN_PathManager_UndefinePath()

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

Unregister a path that was registered by GWEN_PathManager_DefinePath().

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