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     int loadFromFolder(const std::string& folder, bool recursive = false);\r
 108 \r
 109     ////////////////////////////////////////////////////////////\r
 110     /// \brief Unload a plugin.\r
 111     ///\r
 112     /// \param pluginName Name or path of the plugin.\r
 113     ///\r
 114     /// \return True if the plugin is successfully unloaded,\r
 115     /// false if no such plugin exists on the manager.\r
 116     ///\r
 117     /// \see load(const std::string&, const std::string&)\r
 118     /// \see load(const std::string&)\r
 119     /// \see loadFromFolder\r
 120     /// \see unloadAll\r
 121     ///\r
 122     ////////////////////////////////////////////////////////////\r
 123     bool unload(const std::string& pluginName);\r
 124 \r
 125     ////////////////////////////////////////////////////////////\r
 126     /// \brief Unload all loaded plugins.\r
 127     ///\r
 128     /// \see load(const std::string&, const std::string&)\r
 129     /// \see load(const std::string&)\r
 130     /// \see loadFromFolder\r
 131     /// \see unload\r
 132     ///\r
 133     ////////////////////////////////////////////////////////////\r
 134     void unloadAll();\r
 135 \r
 136     ////////////////////////////////////////////////////////////\r
 137     /// \brief Directly add a new provider.\r
 138     ///\r
 139     /// \param provider Provider.\r
 140     ///\r
 141     ////////////////////////////////////////////////////////////\r
 142     bool addProvider(Provider* provider);\r
 143 \r
 144     ////////////////////////////////////////////////////////////\r
 145     /// \brief Get the name of all loaded plugins.\r
 146     ///\r
 147     /// \param pluginNames A vector to fill with the plugins names.\r
 148     ///\r
 149     ////////////////////////////////////////////////////////////\r
 150     void getLoadedPlugins(std::vector<const std::string*>& pluginNames) const;\r
 151 \r
 152     ////////////////////////////////////////////////////////////\r
 153     /// \brief Check if a plug-in is loaded.\r
 154     ///\r
 155     /// \param pluginName the plug-in tname o check.\r
 156     ///\r
 157     ////////////////////////////////////////////////////////////\r
 158     bool isLoaded(const std::string& pluginName) const;\r
 159 \r
 160 \r
 161 protected:\r
 162 \r
 163     ////////////////////////////////////////////////////////////\r
 164     /// \brief Default constructor.\r
 165     ///\r
 166     /// PluginManager cannot be publicly instantiated.\r
 167     ///\r
 168     ////////////////////////////////////////////////////////////\r
 169     PluginManager();\r
 170 \r
 171     ////////////////////////////////////////////////////////////\r
 172     /// \brief Register a provider type\r
 173     ///\r
 174     /// \param type Provider type.\r
 175     /// \param version Current version of that provider type.\r
 176     /// \param lowestVersion Lowest compatible version of that provider type.\r
 177     ///\r
 178     /// \see Host::registerType\r
 179     ///\r
 180     ////////////////////////////////////////////////////////////\r
 181     void registerType(const std::string& type, unsigned int version, unsigned int lowestVersion);\r
 182 \r
 183     ////////////////////////////////////////////////////////////\r
 184     /// \brief Get providers of a certain type.\r
 185     ///\r
 186     /// \param type Provider type.\r
 187     ///\r
 188     /// \return Pointer to the list of providers of that \a type,\r
 189     /// or NULL if \a type is not registered.\r
 190     ///\r
 191     /// \see Host::getProviders\r
 192     ///\r
 193     ////////////////////////////////////////////////////////////\r
 194     const std::list<Provider*>* getProviders(const std::string& type) const;\r
 195 \r
 196 \r
 197 private:\r
 198 \r
 199     ////////////////////////////////////////////////////////////\r
 200     /// \brief Get the plugin name (without extension) from its path\r
 201     ///\r
 202     /// \param path Plugin path.\r
 203     ///\r
 204     /// \return Name of the plugin.\r
 205     ///\r
 206     /// \see resolvePathExtension\r
 207     /// \see load(const std::string&, const std::string&)\r
 208     /// \see load(const std::string&)\r
 209     /// \see unload\r
 210     ///\r
 211     ////////////////////////////////////////////////////////////\r
 212     static std::string getPluginName(const std::string& path);\r
 213 \r
 214     ////////////////////////////////////////////////////////////\r
 215     /// \brief If the plugin path omits it's extension, this method returns\r
 216     /// the path plus the OS specific dll extension.\r
 217     /// Return a copy of the path otherwise.\r
 218     ///\r
 219     /// \param path Plugin path.\r
 220     ///\r
 221     /// \return Path with extension.\r
 222     ///\r
 223     /// \see getPluginName\r
 224     /// \see load(const std::string&, const std::string&)\r
 225     /// \see load(const std::string&)\r
 226     /// \see unload\r
 227     ///\r
 228     ////////////////////////////////////////////////////////////\r
 229     static std::string resolvePathExtension(const std::string& path);\r
 230 \r
 231 \r
 232 private:\r
 233 \r
 234     /// Signature for the plugin's registration function\r
 235     typedef bool fnRegisterPlugin(Host&);\r
 236     typedef std::map<std::string,DLibrary*> LibMap;\r
 237 \r
 238     LibMap libraries;   ///< Map containing the loaded libraries\r
 239     Host host;          ///< Host app proxy, holding all providers\r
 240 \r
 241 };\r
 242 \r
 243 }   // namespace pluma\r
 244 \r
 245 #endif // PLUMA_PLUGIN_MANAGER_HPP\r