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_STRINGLIST * | GWEN_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

enum 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

  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.
  rm | path relative to what? (see GWEN_PathManager_RelModeCwd)

Returns
  Zero on success, or GWEN_ERROR_NOT_FOUND if the `pathName` was not found.

References GWENHYWFAR_API.

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

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

References GWENHYWFAR_API.

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

  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 relative to the prefix of the current working directory that should be added to this registered path.
  rm | The 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.

References GWENHYWFAR_API.

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

  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.

References GWENHYWFAR_API.

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

  destLib | The name of the library that this path is supposed to belong to.
  pathName | A string identifier for this registered path.
  fileName | Name of the file (may contain partial paths, like in "dialogs/testdialog.xml"
  fbuf | buffer to receive the full path to access the file

Returns
  0 on success (in that case `fbuf` will be filled), an error code otherwise.

References GWENHYWFAR_API.

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

  destLib | The name of the library that this path is supposed to belong to.
  pathName | A string identifier for this registered path.
  subFolderName | if 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.
  sl | string 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

  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.

References GWENHYWFAR_API.

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

  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.

References GWENHYWFAR_API.

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

  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 relative to the prefix of the current working directory that should be added to this registered path.
  rm | The 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.

References GWENHYWFAR_API.

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

  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.

References GWENHYWFAR_API.

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

  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.

References GWENHYWFAR_API.

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

  callingLib | The name of the library that added path entries.

Returns
  Zero on success.

References GWENHYWFAR_API.

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

  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.

References GWENHYWFAR_API.