xbmc/platform/Environment.h

   1 /*
   2  *  Copyright (C) 2013-2018 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 /**
  12  * \file utils\Environment.h
  13  * \brief Declares CEnvironment class for platform-independent environment variables manipulations.
  14  *
  15  */
  16 #include <string>
  17
  18 /**
  19  * @class   CEnvironment
  20  *
  21  * @brief   Platform-independent environment variables manipulations.
  22  *
  23  *      Provide analog for POSIX functions:
  24  *      + setenv
  25  *      + unsetenv
  26  *      + putenv
  27  *      + getenv
  28  *
  29  *      You can generally use the functions as you would normally in POSIX-style.
  30  *  The differences below are just to make things more convenient through use of std::string (2,3),
  31  *  and to also allow the Win32-style of unsetting variables (4,5) if wanted.
  32  *      1. CEnvironment::setenv  parameter 'overwrite' is optional, set by default to 1 (allow overwrite).
  33  *      2. CEnvironment::putenv  uses copy of provided string (rather than string itself) to change environment,
  34  *                           so you can free parameter variable right after call of function.
  35  *      3. CEnvironment::getenv  returns a copy of environment variable value instead of pointer to value.
  36  *      4. CEnvironment::setenv  can be used to unset variables. Just pass empty string for 'value' parameter.
  37  *      5. CEnvironment::putenv  can be used to unset variables. Set parameter to 'var=' (Windows style) or
  38  *                           just 'var' (POSIX style), and 'var' will be unset.
  39  *
  40  *      All 'std::string' types are supposed to be in UTF-8 encoding.
  41  *      All functions work on all platforms. Special care is taken on Windows platform where Environment is changed for process itself,
  42  *      for process runtime library and for all runtime libraries (MSVCRT) loaded by third-party modules.
  43  *      Functions internally make all necessary UTF-8 <-> wide conversions.*
  44  */
  45
  46 class CEnvironment
  47 {
  48 public:
  49   /**
  50    * \fn static int CEnvironment::setenv(const std::string &name, const std::string &value,
  51    *     int overwrite = 1);
  52    * \brief Sets or unsets environment variable.
  53    * \param name      The environment variable name to add/modify/delete.
  54    * \param value     The environment variable new value. If set to empty string, variable will be
  55    *                                    deleted from the environment.
  56    * \param overwrite (optional) If set to non-zero, existing variable will be overwritten. If set to zero and
  57    *                                    variable is already present, then variable will be unchanged and function returns success.
  58    * \return Zero on success, non-zero on error.
  59    */
  60   static int setenv(const std::string &name, const std::string &value, int overwrite = 1);
  61   /**
  62    * \fn static int CEnvironment::unsetenv(const std::string &name);
  63    * \brief Deletes environment variable.
  64    * \param name The environment variable name to delete.
  65    * \return Zero on success, non-zero on error.
  66    */
  67   static int unsetenv(const std::string &name);
  68
  69   /**
  70    * \fn static int CEnvironment::putenv(const std::string &envstring);
  71    * \brief Adds/modifies/deletes environment variable.
  72    * \param envstring The variable-value string in form 'var=value'. If set to 'var=' or 'var', then variable
  73    *                                    will be deleted from the environment.
  74    * \return Zero on success, non-zero on error.
  75    */
  76   static int putenv(const std::string &envstring);
  77   /**
  78    * \fn static std::string CEnvironment::getenv(const std::string &name);
  79    * \brief Gets value of environment variable in UTF-8 encoding.
  80    * \param name The name of environment variable.
  81    * \return Copy of of environment variable value or empty string if variable in not present in environment.
  82    * \sa xbmc_getenvUtf8, xbmc_getenvW
  83    */
  84   static std::string getenv(const std::string &name);
  85 private:
  86 #ifdef TARGET_WINDOWS
  87   enum updateAction:int
  88   {
  89     addOrUpdateOnly = -2,
  90     deleteVariable = -1,
  91     addOnly =  0,
  92     autoDetect = 1
  93   };
  94   static int win_setenv(const std::string &name, const std::string &value = "", updateAction action = autoDetect);
  95   static std::string win_getenv(const std::string &name);
  96 #endif // TARGET_WINDOWS
  97 };
  98