lib/third_party/Pluma/PluginManager.hpp

   1 ////////////////////////////////////////////////////////////\r
   2 //\r
   3 // Pluma - Plug-in Management Framework\r
   4 // Copyright (C) 2010-2012 Gil Costa (gsaurus@gmail.com)\r
   5 //\r
   6 // This software is provided 'as-is', without any express or implied warranty.\r
   7 // In no event will the authors be held liable for any damages arising from the use of this software.\r
   8 //\r
   9 // Permission is granted to anyone to use this software for any purpose,\r
  10 // including commercial applications, and to alter it and redistribute it freely,\r
  11 // subject to the following restrictions:\r
  12 //\r
  13 // 1. The origin of this software must not be misrepresented;\r
  14 //    you must not claim that you wrote the original software.\r
  15 //    If you use this software in a product, an acknowledgment\r
  16 //    in the product documentation would be appreciated but is not required.\r
  17 //\r
  18 // 2. Altered source versions must be plainly marked as such,\r
  19 //    and must not be misrepresented as being the original software.\r
  20 //\r
  21 // 3. This notice may not be removed or altered from any source distribution.\r
  22 //\r
  23 ////////////////////////////////////////////////////////////\r
  24 \r
  25 #ifndef PLUMA_PLUGIN_MANAGER_HPP\r
  26 #define PLUMA_PLUGIN_MANAGER_HPP\r
  27 \r
  28 ////////////////////////////////////////////////////////////\r
  29 // Headers\r
  30 ////////////////////////////////////////////////////////////\r
  31 #include <Pluma/Config.hpp>\r
  32 #include <Pluma/Host.hpp>\r
  33 \r
  34 #include <string>\r
  35 #include <map>\r
  36 \r
  37 namespace pluma{\r
  38 class DLibrary;\r
  39 \r
  40 ////////////////////////////////////////////////////////////\r
  41 /// \brief Manages loaded plugins.\r
  42 ///\r
  43 ////////////////////////////////////////////////////////////\r
  44 class PLUMA_API PluginManager{\r
  45 \r
  46 \r
  47 public:\r
  48 \r
  49     ////////////////////////////////////////////////////////////\r
  50     /// \brief Destructor.\r
  51     ///\r
  52     ////////////////////////////////////////////////////////////\r
  53     ~PluginManager();\r
  54 \r
  55     ////////////////////////////////////////////////////////////\r
  56     /// \brief Load a plugin given it's path\r
  57     ///\r
  58     /// \param path Path for the plugin, including plugin name. File extension\r
  59     /// may be included, but is discouraged for better cross platform code.\r
  60     /// If file extension isn't present on the path, Pluma will deduce it\r
  61     /// from the operating system.\r
  62     ///\r
  63     /// \return True if the plugin is successfully loaded.\r
  64     ///\r
  65     /// \see load(const std::string&, const std::string&)\r
  66     /// \see loadFromFolder\r
  67     /// \see unload\r
  68     /// \see unloadAll\r
  69     ///\r
  70     ////////////////////////////////////////////////////////////\r
  71     bool load(const std::string& path);\r
  72 \r
  73 \r
  74     ////////////////////////////////////////////////////////////\r
  75     /// \brief Load a plugin from a given folder\r
  76     ///\r
  77     /// \param folder The folder path.\r
  78     /// \param pluginName Name of the plugin. File extension\r
  79     /// may be included, but is discouraged for better cross platform code.\r
  80     /// If file extension is omitted, Pluma will deduce it\r
  81     /// from the operating system.\r
  82     ///\r
  83     /// \return True if the plugin is successfully loaded.\r
  84     ///\r
  85     /// \see load(const std::string&)\r
  86     /// \see loadFromFolder\r
  87     /// \see unload\r
  88     /// \see unloadAll\r
  89     ///\r
  90     ////////////////////////////////////////////////////////////\r
  91     bool load(const std::string& folder, const std::string& pluginName);\r
  92 \r
  93     ////////////////////////////////////////////////////////////\r
  94     /// \brief Load all plugins from a given folder\r
  95     ///\r
  96     /// \param folder Path for the folder where the plug-ins are.\r
  97     /// \param recursive If true it will search on sub-folders as well\r
  98     ///\r
  99     /// \return Number of successfully loaded plug-ins.\r
 100     ///\r
 101     /// \see load(const std::string&, const std::string&)\r
 102     /// \see load(const std::string&)\r
 103     /// \see unload\r
 104     /// \see unloadAll\r
 105     ///\r
 106     ////////////////////////////////////////////////////////////\r
 107     std::list< std::string > loadFromFolder(\r
 108       const std::string& folder, bool recursive = false\r
 109       );\r
 110 \r
 111     ////////////////////////////////////////////////////////////\r
 112     /// \brief Unload a plugin.\r
 113     ///\r
 114     /// \param pluginName Name or path of the plugin.\r
 115     ///\r
 116     /// \return True if the plugin is successfully unloaded,\r
 117     /// false if no such plugin exists on the manager.\r
 118     ///\r
 119     /// \see load(const std::string&, const std::string&)\r
 120     /// \see load(const std::string&)\r
 121     /// \see loadFromFolder\r
 122     /// \see unloadAll\r
 123     ///\r
 124     ////////////////////////////////////////////////////////////\r
 125     bool unload(const std::string& pluginName);\r
 126 \r
 127     ////////////////////////////////////////////////////////////\r
 128     /// \brief Unload all loaded plugins.\r
 129     ///\r
 130     /// \see load(const std::string&, const std::string&)\r
 131     /// \see load(const std::string&)\r
 132     /// \see loadFromFolder\r
 133     /// \see unload\r
 134     ///\r
 135     ////////////////////////////////////////////////////////////\r
 136     void unloadAll();\r
 137 \r
 138     ////////////////////////////////////////////////////////////\r
 139     /// \brief Directly add a new provider.\r
 140     ///\r
 141     /// \param provider Provider.\r
 142     ///\r
 143     ////////////////////////////////////////////////////////////\r
 144     bool addProvider(Provider* provider);\r
 145 \r
 146     ////////////////////////////////////////////////////////////\r
 147     /// \brief Get the name of all loaded plugins.\r
 148     ///\r
 149     /// \param pluginNames A vector to fill with the plugins names.\r
 150     ///\r
 151     ////////////////////////////////////////////////////////////\r
 152     void getLoadedPlugins(std::vector<const std::string*>& pluginNames) const;\r
 153 \r
 154     ////////////////////////////////////////////////////////////\r
 155     /// \brief Check if a plug-in is loaded.\r
 156     ///\r
 157     /// \param pluginName the plug-in tname o check.\r
 158     ///\r
 159     ////////////////////////////////////////////////////////////\r
 160     bool isLoaded(const std::string& pluginName) const;\r
 161 \r
 162 \r
 163 protected:\r
 164 \r
 165     ////////////////////////////////////////////////////////////\r
 166     /// \brief Default constructor.\r
 167     ///\r
 168     /// PluginManager cannot be publicly instantiated.\r
 169     ///\r
 170     ////////////////////////////////////////////////////////////\r
 171     PluginManager();\r
 172 \r
 173     ////////////////////////////////////////////////////////////\r
 174     /// \brief Register a provider type\r
 175     ///\r
 176     /// \param type Provider type.\r
 177     /// \param version Current version of that provider type.\r
 178     /// \param lowestVersion Lowest compatible version of that provider type.\r
 179     ///\r
 180     /// \see Host::registerType\r
 181     ///\r
 182     ////////////////////////////////////////////////////////////\r
 183     void registerType(const std::string& type, unsigned int version, unsigned int lowestVersion);\r
 184 \r
 185     ////////////////////////////////////////////////////////////\r
 186     /// \brief Get providers of a certain type.\r
 187     ///\r
 188     /// \param type Provider type.\r
 189     ///\r
 190     /// \return Pointer to the list of providers of that \a type,\r
 191     /// or NULL if \a type is not registered.\r
 192     ///\r
 193     /// \see Host::getProviders\r
 194     ///\r
 195     ////////////////////////////////////////////////////////////\r
 196     const std::list<Provider*>* getProviders(const std::string& type) const;\r
 197 \r
 198 \r
 199 private:\r
 200 \r
 201     ////////////////////////////////////////////////////////////\r
 202     /// \brief Get the plugin name (without extension) from its path\r
 203     ///\r
 204     /// \param path Plugin path.\r
 205     ///\r
 206     /// \return Name of the plugin.\r
 207     ///\r
 208     /// \see resolvePathExtension\r
 209     /// \see load(const std::string&, const std::string&)\r
 210     /// \see load(const std::string&)\r
 211     /// \see unload\r
 212     ///\r
 213     ////////////////////////////////////////////////////////////\r
 214     static std::string getPluginName(const std::string& path);\r
 215 \r
 216     ////////////////////////////////////////////////////////////\r
 217     /// \brief If the plugin path omits it's extension, this method returns\r
 218     /// the path plus the OS specific dll extension.\r
 219     /// Return a copy of the path otherwise.\r
 220     ///\r
 221     /// \param path Plugin path.\r
 222     ///\r
 223     /// \return Path with extension.\r
 224     ///\r
 225     /// \see getPluginName\r
 226     /// \see load(const std::string&, const std::string&)\r
 227     /// \see load(const std::string&)\r
 228     /// \see unload\r
 229     ///\r
 230     ////////////////////////////////////////////////////////////\r
 231     static std::string resolvePathExtension(const std::string& path);\r
 232 \r
 233 \r
 234 private:\r
 235 \r
 236     /// Signature for the plugin's registration function\r
 237     typedef bool fnRegisterPlugin(Host&);\r
 238     typedef std::map<std::string,DLibrary*> LibMap;\r
 239 \r
 240     LibMap libraries;   ///< Map containing the loaded libraries\r
 241     Host host;          ///< Host app proxy, holding all providers\r
 242 \r
 243 };\r
 244 \r
 245 }   // namespace pluma\r
 246 \r
 247 #endif // PLUMA_PLUGIN_MANAGER_HPP\r