lib/third_party/Pluma/Pluma.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_PLUMA_HPP\r
  26 #define PLUMA_PLUMA_HPP\r
  27 \r
  28 ////////////////////////////////////////////////////////////\r
  29 // Headers\r
  30 ////////////////////////////////////////////////////////////\r
  31 #include <Pluma/Config.hpp>\r
  32 #include <Pluma/Provider.hpp>\r
  33 #include <Pluma/PluginManager.hpp>\r
  34 \r
  35 ////////////////////////////////////////////////////////////\r
  36 // Andy macro to convert parameter to string\r
  37 ////////////////////////////////////////////////////////////\r
  38 #define PLUMA_2STRING(X) #X\r
  39 \r
  40 ////////////////////////////////////////////////////////////\r
  41 // Macro that helps host applications defining\r
  42 // their provider classes\r
  43 ////////////////////////////////////////////////////////////\r
  44 #define PLUMA_PROVIDER_HEADER(TYPE)\\r
  45 PLUMA_PROVIDER_HEADER_BEGIN(TYPE)\\r
  46 virtual TYPE* create() const = 0;\\r
  47 PLUMA_PROVIDER_HEADER_END\r
  48 \r
  49 ////////////////////////////////////////////////////////////\r
  50 // Macro that generate first part of the provider definition\r
  51 ////////////////////////////////////////////////////////////\r
  52 #define PLUMA_PROVIDER_HEADER_BEGIN(TYPE)\\r
  53 class TYPE##Provider: public pluma::Provider{\\r
  54 private:\\r
  55     friend class pluma::Pluma;\\r
  56     static const unsigned int PLUMA_INTERFACE_VERSION;\\r
  57     static const unsigned int PLUMA_INTERFACE_LOWEST_VERSION;\\r
  58     static const std::string PLUMA_PROVIDER_TYPE;\\r
  59     std::string plumaGetType() const{ return PLUMA_PROVIDER_TYPE; }\\r
  60 public:\\r
  61     unsigned int getVersion() const{ return PLUMA_INTERFACE_VERSION; }\r
  62 \r
  63 ////////////////////////////////////////////////////////////\r
  64 // Macro that generate last part of the provider definition\r
  65 ////////////////////////////////////////////////////////////\r
  66 #define PLUMA_PROVIDER_HEADER_END };\r
  67 \r
  68 ////////////////////////////////////////////////////////////\r
  69 // Macro that generate the provider declaration\r
  70 ////////////////////////////////////////////////////////////\r
  71 #define PLUMA_PROVIDER_SOURCE(TYPE, Version, LowestVersion)\\r
  72 const std::string TYPE##Provider::PLUMA_PROVIDER_TYPE = PLUMA_2STRING( TYPE );\\r
  73 const unsigned int TYPE##Provider::PLUMA_INTERFACE_VERSION = Version;\\r
  74 const unsigned int TYPE##Provider::PLUMA_INTERFACE_LOWEST_VERSION = LowestVersion;\r
  75 \r
  76 \r
  77 ////////////////////////////////////////////////////////////\r
  78 // Macro that helps plugins generating their provider implementations\r
  79 // PRE: SPECIALIZED_TYPE must inherit from BASE_TYPE\r
  80 ////////////////////////////////////////////////////////////\r
  81 #define PLUMA_INHERIT_PROVIDER(SPECIALIZED_TYPE, BASE_TYPE)\\r
  82 class SPECIALIZED_TYPE##Provider: public BASE_TYPE##Provider{\\r
  83 public:\\r
  84     BASE_TYPE * create() const{ return new SPECIALIZED_TYPE (); }\\r
  85 };\r
  86 \r
  87 \r
  88 namespace pluma{\r
  89 \r
  90 ////////////////////////////////////////////////////////////\r
  91 /// \brief Pluma plugins management\r
  92 ///\r
  93 ////////////////////////////////////////////////////////////\r
  94 class Pluma: public PluginManager{\r
  95 \r
  96 public:\r
  97     ////////////////////////////////////////////////////////////\r
  98     /// \brief Default Constructor\r
  99     ///\r
 100     ////////////////////////////////////////////////////////////\r
 101     Pluma();\r
 102 \r
 103     ////////////////////////////////////////////////////////////\r
 104     /// \brief Tell Pluma to accept a certain type of providers\r
 105     ///\r
 106     /// A Pluma object is able to accept multiple types of providers.\r
 107     /// When a plugin is loaded, it tries to register it's providers\r
 108     /// implementations. Those are only accepted by the host\r
 109     /// application if it's accepting providers of that kind.\r
 110     ///\r
 111     /// \tparam ProviderType type of provider.\r
 112     ///\r
 113     ////////////////////////////////////////////////////////////\r
 114     template<typename ProviderType>\r
 115     void acceptProviderType();\r
 116 \r
 117     ////////////////////////////////////////////////////////////\r
 118     /// \brief Get the stored providers of a certain type.\r
 119     ///\r
 120     /// Providers are added at the end of the \a providers vector.\r
 121     ///\r
 122     /// \tparam ProviderType type of provider to be returned.\r
 123     /// \param[out] providers Vector to fill with the existing\r
 124     /// providers.\r
 125     ///\r
 126     ////////////////////////////////////////////////////////////\r
 127     template<typename ProviderType>\r
 128     void getProviders(std::vector<ProviderType*>& providers);\r
 129 };\r
 130 \r
 131 #include <Pluma/Pluma.inl>\r
 132 \r
 133 }\r
 134 \r
 135 \r
 136 #endif // PLUMA_PLUMA_HPP\r
 137 \r
 138 \r
 139 ////////////////////////////////////////////////////////////\r
 140 /// \class pluma::Pluma\r
 141 ///\r
 142 /// Pluma is the main class of Pluma library. Allows hosting\r
 143 /// applications to load/unload dlls in runtime (plugins), and\r
 144 /// to get providers of shared interface objects.\r
 145 ///\r
 146 /// Example:\r
 147 /// \code\r
 148 /// pluma::Pluma pluma;\r
 149 /// // Tell it to accept providers of the type DeviceProvider\r
 150 /// pluma.acceptProviderType<DeviceProvider>();\r
 151 /// // Load some dll\r
 152 /// pluma.load("plugins/standard_devices");\r
 153 /// // Get device providers into a vector\r
 154 /// std::vector<DeviceProvider*> providers;\r
 155 /// pluma.getProviders(providers);\r
 156 /// // create a Device from the first provider\r
 157 /// if (!providers.empty()){\r
 158 ///     Device* myDevice = providers.first()->create();\r
 159 ///     // do something with myDevice\r
 160 ///     std::cout << device->getDescription() << std::endl;\r
 161 ///     // (...)\r
 162 ///     delete myDevice;\r
 163 /// }\r
 164 /// \endcode\r
 165 ///\r
 166 /// It is also possible to add local providers, providers that\r
 167 /// are defined directly on the host application. That can\r
 168 /// be useful to provide and use default implementations of certain\r
 169 /// interfaces, along with plugin implementations.\r
 170 ///\r
 171 ////////////////////////////////////////////////////////////\r