/* Network-Integrated Multimedia Middleware (NMM)
 * http://www.motama.com/nmm.html
 *  
 * Copyright (C) 2006-2007
 * Motama GmbH, Saarbruecken, Germany
 * http://www.motama.com
 *  
 * This file is part of NMM. 
 * 
 * NMM is free software; you can redistribute it and/or modify it    
 * under the terms of the GNU General Public License as published by 
 * the Free Software Foundation; only version 2 of the License.      
 * 
 * NMM is distributed in the hope that it will be useful, but WITHOUT 
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public 
 * License for more details.  
 * 
 * You should have received a copy of the GNU General Public License 
 * along with NMM; if not, write to the Free Software Foundation,    
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 */

#ifndef NMM_DIRECTORY_HPP
#define NMM_DIRECTORY_HPP

#include "nmm/nmm_prefix.hpp"


#include "nmm/Exception.hpp"
   
#include <string>
#include <list>

#include "visibility.hpp"
 
namespace NMM {

  /** Get name of an arbitrary environment variable
   *
   * \param envvarname The name of an arbitrary environment variable
   * \returns The value of envvarnme if it is set, empty string otherwise
   */
  DLLEXPORT std::string getNMMEnvVar(std::string envvarname);


  /** Return path where NMM is installed or source dir where NMM is
   *
   * \returns path where NMM is installed or source dir where NMM is
   * build if NMM_DEV_DIR evironment variable is set
   */
  DLLEXPORT std::string getNMMDir();

  /** Get path where NMM resources are found
   *
   * \returns path where NMM resources are found
   */
  DLLEXPORT std::string getNMMResourceDir();

  /** Get complete path where NMM resource res is found
   *
   * \param res Resource to search
   * \returns complete path where NMM resource res is found
   */
  DLLEXPORT std::string getNMMResource(const std::string res);

  /** Get path where NMM plugins are found
   *
   * \returns path where NMM plugins are found
   */
  DLLEXPORT std::string getNMMPluginDir();

  /**  Get path where NMM Project plugins are found 
   *
   * \returns path where NMM Project plugins are found or
   * getNMMPluginDir() if environment variable NMM_PROJECT_DIR not
   * set.
   */
  DLLEXPORT std::string getNMMProjectPluginDir();

  /** Get path where NMM plugins are found
   *
   * \returns path where NMM plugins are found
   */
  DLLEXPORT std::string getNMMLocaleDir();

  /** Get the filename of the NMM configuration file.
   *
   * This method returns the filename (without directory) of the NMM configuration file.
   * The NMM configuration file was formerly known as .nmmrc, which should still be its
   * name on Linux platforms.
   *
   * @return Filename of NMM configuration file
   */
  DLLEXPORT std::string getNMMConfigFilename();

  /** Check if filename is in a specific directory
   *
   * \returns true when given filename (may include full path) is within the set of given directories; also true when set is empty
   * \param dir_plus_filename the filename to check
   * \param directories the directories separated with ':' 
   */
  DLLEXPORT bool isFilenameWithinDirectories(const std::string& dir_plus_filename, const std::string& directories);
  
  /** Get the home directory of the current user.
   *
   * This is the value of the HOME environment variable on Linux and
   * the user's profile directory on windows.
   *
   * @return home directory of the current user.
   */
  DLLEXPORT std::string getUserHomeDirectory();
  
  /** Get all files in a directory.
   *
   * @return list of files within a directory
   */
  DLLEXPORT std::list<std::string> getAllFilesInDirectory(const std::string& folder)
    throw(const Exception&);

  /** Get the current working directory.
   *
   * This method returns the current working directory.
   *
   * @return The current working directory
   * @see getAbsolutePath getAbsolutePathNative
   */
  DLLEXPORT std::string getCurrentWorkingDirectory() throw();

  /** Convert a relative path to an absolute path.
   *
   * This method returns the absolute path to a file which is given by a relative or absolute path.
   * If the given path is absolute, it is returned unmodified. Otherwise, the path is assmed to refer
   * to a file in the current working directory (i.e. the current working directory is prenended to
   * the given path).
   *
   * Note that relative paths are always interpreted as native paths. This method detects absolute
   * Windows and Linux paths. To interpret native paths only, use @c getAbsoluteNativePath.
   *
   * Examples (Linux):
   *
   * Media/test.wav --> /home/bob/Media/test.wav (if c:/home/bob is the current working directory)
   * /home/bob/Media/test.wav --> /home/bob/Media/test.wav
   *
   * Examples (Windows):
   *
   * Media/test.wav --> c:/home/bob/Media/test.wav (if c:/home/bob is the current working directory)
   * /Media/test.wav --> c:/Media/test.wav (if c:/home/bob is the current working directory)
   * c:/Media/test.wav --> c:/Media/test.wav
   * (In Windows, both forward and backward slashes are accepted. An absolute path always starts
   * with a drive letter followed by ':')
   *
   * @param path A relative or absolute path
   * @return The absolute path which refers to the same file
   * @see getCurrentWorkingDirectory getAbsolutePathNative
   */
  DLLEXPORT std::string getAbsolutePath(std::string path) throw();

  /** Convert a native relative path to a native  absolute path.
   *
   * This method returns the absolute path to a file which is given by a relative or absolute path.
   * If the given path is absolute, it is returned unmodified. Otherwise, the path is assmed to refer
   * to a file in the current working directory (i.e. the current working directory is prenended to
   * the given path).
   *
   * Unlike @c getAbsolutePath, this method interprets the path as a native path. This means that, for
   * example, on a Linux system, only Linux paths are accepted, and on a Windows system, only Windows
   * paths are accepted.
   *
   * @param path A relative or absolute path
   * @return The absolute path which refers to the same file
   * @see getCurrentWorkingDirectory getAbsolutePath
   */
  DLLEXPORT std::string getAbsoluteNativePath(std::string path) throw();

  /** Creates a directory. 
   *
   * @param path directory including path that should be created
   */
  DLLEXPORT void createDirectory(const std::string& path) throw(const Exception&);

  /** Get a normalized file name.
   *
   * This method returns a normalized form of the given file name.
   * It can be used for comparing file names in a platform-independent way.
   *
   * @param filename A file name
   * @return The normalized form of @a filename
   */
  DLLEXPORT std::string getNormalizedFileName(const std::string& filename);

  /** Get a normalized directory name.
   *
   * This method returns a normalized form of the given directory name.
   * It can be used for comparing directory names in a platform-independent way.
   *
   * The difference of this function to getNormalizedFilename() is that this method
   * also adds a trailing path separator to the normalized form.
   *
   * @param dirname A directory name
   * @return The normalized form of @a dirname
   */
  DLLEXPORT std::string getNormalizedDirectoryName(const std::string& dirname);

  /** Get the directory part of a file name.
   *
   * This method returns the directory part of a file name.
   * This is the part of the file name up to the last path separator.
   * If the file name contains no path separators, the result is the empty string.
   *
   * @param filename A file name
   * @return The directory part of @a filename
   */
  DLLEXPORT std::string getDirectoryPart(const std::string& filename);

}


#include "nmm/nmm_suffix.hpp"

#endif
