Provide access to application's path, this include configuration, data, executable and library paths.
See qi::path Developer Guide for a global overview of path related functions
. More...

Namespaces
namespace	qi::path
	Set of tools to handle SDK layouts.
Functions
QI_API std::string	qi::path::sdkPrefix ()
	Return the default SDK prefix path.It's always a complete, native path.
QI_API std::string	qi::path::findBin (const std::string &name)
	Look for a binary.This will search in all SDK prefixes for a file named 'name'. It will then add '.exe' suffix if needed.
QI_API std::string	qi::path::findLib (const std::string &name)
	Look for a library.This will search in all SDK prefixes for a file named 'name'. It will then add 'lib' prefix, and appropriated suffixes ('.dll' on windows, '.so' on linux, '.dylib' on mac).
QI_API std::string	qi::path::findConf (const std::string &applicationName, const std::string &filename)
	Look for a configuration file.The file is searched in a list of possible directories, the first match is returned.
QI_API std::string	qi::path::findData (const std::string &applicationName, const std::string &filename)
	Look for a data file.The file is search in a list of possible directories, the first match is returned. The list of paths is constructed like this:
QI_API std::vector< std::string >	qi::path::confPaths (const std::string &applicationName="")
	Get the list of directories used when searching for configuration files for the given application name.This is used by the qi::path::findConfigurationPath method.
QI_API std::vector< std::string >	qi::path::dataPaths (const std::string &applicationName="")
	Get the list of directories used when searching for data files for the given application name.This is used by the qi::path::findDataPath method.
QI_API std::vector< std::string >	qi::path::binPaths ()
	Get the list of directories used when searching for binaries.This is used by the qi::path::findBin() method.
QI_API std::vector< std::string >	qi::path::libPaths ()
	Get the list of directories used when searching for libraries.This is used by the qi::path::findLib() method.
QI_API std::string	qi::path::userWritableDataPath (const std::string &applicationName, const std::string &filename)
	Get the writable data files path for users.
QI_API std::string	qi::path::userWritableConfPath (const std::string &applicationName, const std::string &filename="")
	Get the writable configuration files path for users.

Detailed Description

Provide access to application's path, this include configuration, data, executable and library paths.
See qi::path Developer Guide for a global overview of path related functions
.

Provide access to various path including:

executables, qi::path::findBin
libraries, qi::pathfindLib
application data qi::path::findData
application configuration qi::path::findConf
writable data and configuration paths qi::path::userWritableConfPath, qi::path::userWritableDataPath

Since this library is cross-platform we need to take care of different charsets and localizations (UTF-8, UTF-16).

Apple OS X always use UTF-8 locale and path. OS X provide a Posix API that do not care about locale.
Windows (including Cygwin and MinGW) have both 8 bits functions using various charsets depending on the Windows localization setup, and 16 bits functions using UTF-16. To support internationalization we need to always use UTF-16 functions. (_wfopen, _wopen, _wsystem, ...).
Linux distributions use UTF-8 locale and path by default. Linux provide a Posix API that do not care about locale.

To support internationalization we will always consider path to be encoded in UTF-8 under Windows. We will convert them to UTF-16 to pass them to the native windows API. On Posix platform we have nothing to do.

We recommand to use boost::filesystem::path with and imbued UTF-8 locale. you could use this code in your main to initialise boost::filesystem locale once:

  // create a locale with a unicode facet to convert between char(utf-8) and wchar(utf-16/utf-32)
  std::locale loc(std::locale(), &qi::unicodeFacet());
  // Make boost.filesystem always use the unicode facet
  boost::filesystem::path::imbue(loc);

  // it's although possible to set the locale as global.
  // This will enable UTF8 supportfor iostream.
  std::locale::global(loc);

Function Documentation

QI_API std::vector<std::string> qi::path::binPaths ( )

Get the list of directories used when searching for binaries.This is used by the qi::path::findBin() method.

Returns:: A list of directories.

Warning: you should not assume those directories exist, nor that they are writeable.

QI_API std::vector<std::string> qi::path::confPaths ( const std::string & applicationName = "" )

Get the list of directories used when searching for configuration files for the given application name.This is used by the qi::path::findConfigurationPath method.

Parameters:

applicationName Name of the application (in UTF-8).

Returns:: List of configuration directories.

Warning: you should not assume those directories exist, nor that they are writeable.

Examples:: qipath_example.cpp.

QI_API std::vector<std::string> qi::path::dataPaths ( const std::string & applicationName = "" )

Get the list of directories used when searching for data files for the given application name.This is used by the qi::path::findDataPath method.

Parameters:

applicationName Name of the application (in UTF-8).

Returns:: A list of directories.

Warning: you should not assume those directories exist, nor that they are writeable.

QI_API std::string qi::path::findBin ( const std::string & name )

Look for a binary.This will search in all SDK prefixes for a file named 'name'. It will then add '.exe' suffix if needed.

Parameters:

name	The full name of the binary, or just the name (without '.exe') (in UTF-8).

Returns:: The complete, native path to the file found, an empty string otherwise.

QI_API std::string qi::path::findConf	(	const std::string &	applicationName,
		const std::string &	filename
	)

Look for a configuration file.The file is searched in a list of possible directories, the first match is returned.

     * The list of paths is constructed like this:
     * - first, a standard path in the home directory (like
     *  ~/.config/<applicationName>/<filename>)
     * - then:
     *     <sdk_prefix>/etc/<applicationName>/<filename>
     *     for each known SDK prefix
     * - then a standard path in the system. (like
     *   /etc/<applicationName>/<filename>)
     *

Parameters:

applicationName	Name of the application (in UTF-8).
filename	Name of the file to look for (in UTF-8). You can specify subdirectories using "/" as directory separator.

Returns:: The complete, native path of the file if it was found, an empty string otherwise.

Exceptions:

std::invalid_argument if filename was empty

Examples:: qipath_example.cpp.

QI_API std::string qi::path::findData	(	const std::string &	applicationName,
		const std::string &	filename
	)

Look for a data file.The file is search in a list of possible directories, the first match is returned. The list of paths is constructed like this:

     * - first, a standard path in the home directory (like
     *  ~/.local/share/<applicationName>/<filename>)
     * - then
     *   <sdk_prefix>/share/<applicationName>/<filename>
     *     for each known SDK prefix
     *

Parameters:

applicationName	Name of the application (in UTF-8).
filename	Name of the file to look for (in UTF-8). You can specify subdirectories using "/" as directory separator.

Returns:: The complete, native path of the file if it was found, an empty string otherwise.

Exceptions:

std::invalid_argument if filename was empty

QI_API std::string qi::path::findLib ( const std::string & name )

Look for a library.This will search in all SDK prefixes for a file named 'name'. It will then add 'lib' prefix, and appropriated suffixes ('.dll' on windows, '.so' on linux, '.dylib' on mac).

Parameters:

name	The full name of the library, or just the name (without '.dll', '.so') (in UTF-8).

Returns:: The complete, native path to the file found, an empty string otherwise.

You can specify subdirectories using "/" as directory separator (in UTF-8).

QI_API std::vector<std::string> qi::path::libPaths ( )

Get the list of directories used when searching for libraries.This is used by the qi::path::findLib() method.

Returns:: A list of directories.

Warning: you should not assume those directories exist, nor that they are writeable.

QI_API std::string qi::path::userWritableConfPath	(	const std::string &	applicationName,
		const std::string &	filename = `""`
	)

Get the writable configuration files path for users.

Parameters:

applicationName	The name of the application.
filename	If filename is empty, return the directory in which to write. Otherwise the path is constructed like this: * <home>/.config/<applicatioName>/<filename> * You can specify subdirectories using "/" as directory separator * (in UTF-8). *

Examples:: qipath_example.cpp.

QI_API std::string qi::path::userWritableDataPath	(	const std::string &	applicationName,
		const std::string &	filename
	)

Get the writable data files path for users.

Parameters:

applicationName	The name of the application (in UTF-8).
filename	If filename is empty, return the directory in which to write. Otherwise the path is constructed like this: * <home>/.local/share/<applicatioName>/<filename> (on linux) * %AppData%\<applicatioName>\<filename> (windows) * You can specify subdirectories using "/" as directory separator * (in UTF-8). *

Namespaces

Functions

Detailed Description

Function Documentation