lib/third_party/Pluma/Provider.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_PROVIDER_HPP\r
  26 #define PLUMA_PROVIDER_HPP\r
  27 \r
  28 ////////////////////////////////////////////////////////////\r
  29 // Headers\r
  30 ////////////////////////////////////////////////////////////\r
  31 #include <Pluma/Config.hpp>\r
  32 #include <string>\r
  33 \r
  34 \r
  35 namespace pluma{\r
  36 class Host;\r
  37 \r
  38 ////////////////////////////////////////////////////////////\r
  39 /// \brief Interface to provide applications with objects from plugins.\r
  40 ///\r
  41 ////////////////////////////////////////////////////////////\r
  42 class PLUMA_API Provider{\r
  43 friend class Host;\r
  44 \r
  45 \r
  46 public:\r
  47 \r
  48     ////////////////////////////////////////////////////////////\r
  49     /// \brief Destructor.\r
  50     ///\r
  51     ////////////////////////////////////////////////////////////\r
  52     virtual ~Provider();\r
  53 \r
  54     ////////////////////////////////////////////////////////////\r
  55     /// \brief Get provider version.\r
  56     ///\r
  57     /// \return Version number.\r
  58     ///\r
  59     ////////////////////////////////////////////////////////////\r
  60     virtual unsigned int getVersion() const = 0;\r
  61 \r
  62     ////////////////////////////////////////////////////////////\r
  63     /// \brief Check compatibility with host.\r
  64     ///\r
  65     /// The same provider may be compiled with different versions\r
  66     /// on host side and on plugins side. This function checks if\r
  67     /// a plugin provider is compatible with the current version of\r
  68     /// the same provider type on the host side.\r
  69     ///\r
  70     /// \param host Host, proxy of host application.\r
  71     ///\r
  72     /// \return True if it's compatible with \a host.\r
  73     ///\r
  74     ////////////////////////////////////////////////////////////\r
  75     bool isCompatible(const Host& host) const;\r
  76 \r
  77 \r
  78 private:\r
  79 \r
  80     ////////////////////////////////////////////////////////////\r
  81     /// \brief Get provider type.\r
  82     ///\r
  83     /// Each provider defined on the host application is identified by\r
  84     /// a unique type. Those types are automatically managed internally by\r
  85     /// pluma.\r
  86     ///\r
  87     /// \return Provider type id.\r
  88     ///\r
  89     ////////////////////////////////////////////////////////////\r
  90     virtual std::string plumaGetType() const = 0;\r
  91 \r
  92 };\r
  93 \r
  94 }   // namespace pluma\r
  95 \r
  96 \r
  97 #endif // PLUMA_PROVIDER_HPP\r
  98 \r
  99 \r
 100 ////////////////////////////////////////////////////////////\r
 101 /// \class pluma::Provider\r
 102 /// The plugin specific implementations are unknown at the host side,\r
 103 /// only their shared interfaces are known. Then, host app needs a generic\r
 104 /// way of create interface objects. That's what provider classes are for.\r
 105 /// It is the factory design pattern\r
 106 /// (http://www.oodesign.com/factory-pattern.html)\r
 107 ///\r
 108 /// Shared interfaces define their provider types (by inheriting from\r
 109 /// pluma::Provider). Hosts then use those tipes to get objects from the\r
 110 /// plugins.\r
 111 /// Plugins derive the shared interface providers so that they can provide\r
 112 /// host with specific implementations of the shared interface.\r
 113 /// Those specific providers are given to the host through a connect function.\r
 114 ///\r
 115 ///\r
 116 /// Example: A host app uses objects of type Device. A certain plugin\r
 117 /// defines a Keyboard, witch is a Device.\r
 118 /// The Host will use DeviceProviders to create objects of type Device.\r
 119 /// The plugin will provide host specifically with a KeyboardProvider.\r
 120 /// Other plugins may provide host with other derived DeviceProvider types.\r
 121 ///\r
 122 /// Device hpp (shared):\r
 123 /// \code\r
 124 /// #include <Pluma/Pluma.hpp>\r
 125 /// class Device{\r
 126 /// public:\r
 127 ///     virtual std::string getDescription() const = 0;\r
 128 /// };\r
 129 /// // create DevicedProvider class\r
 130 /// PLUMA_PROVIDER_HEADER(Device);\r
 131 /// \endcode\r
 132 ///\r
 133 /// Device cpp (shared):\r
 134 /// \code\r
 135 /// #include "Device.hpp"\r
 136 /// generate DevicedProvider with version 6, and compatible with at least v.3\r
 137 /// PLUMA_PROVIDER_SOURCE(Device, 6, 3);\r
 138 /// \endcode\r
 139 ///\r
 140 ///\r
 141 /// <br>\r
 142 /// Keyboard code on the plugin side:\r
 143 /// \code\r
 144 /// #include <Pluma/Pluma.hpp>\r
 145 /// #include "Device.hpp"\r
 146 ///\r
 147 /// class Keyboard: public Device{\r
 148 /// public:\r
 149 ///     std::string getDescription() const{\r
 150 ///         return "keyboard";\r
 151 ///     }\r
 152 /// };\r
 153 ///\r
 154 /// // create KeyboardProvider, it implements DeviceProvider\r
 155 /// PLUMA_INHERIT_PROVIDER(Keyboard, Device);\r
 156 /// \endcode\r
 157 ///\r
 158 /// plugin connector:\r
 159 /// \code\r
 160 /// #include <Pluma/Connector.hpp>\r
 161 /// #include "Keyboard.hpp"\r
 162 ///\r
 163 /// PLUMA_CONNECTOR\r
 164 /// bool connect(pluma::Host& host){\r
 165 ///     // add a keyboard provider to host\r
 166 ///     host.add( new KeyboardProvider() );\r
 167 ///     return true;\r
 168 /// }\r
 169 /// \endcode\r
 170 ///\r
 171 ///\r
 172 /// Host application code:\r
 173 /// \code\r
 174 /// #include <Pluma/Pluma.hpp>\r
 175 ///\r
 176 /// #include "Device.hpp"\r
 177 /// #include <iostream>\r
 178 /// #include <vector>\r
 179 ///\r
 180 /// int main(){\r
 181 ///\r
 182 ///     pluma::Pluma plugins;\r
 183 ///     // Tell plugins manager to accept providers of the type DeviceProvider\r
 184 ///     plugins.acceptProviderType<DeviceProvider>();\r
 185 ///     // Load library "standard_devices" from folder "plugins"\r
 186 ///     plugins.load("plugins", "standard_devices");\r
 187 ///\r
 188 ///     // Get device providers into a vector\r
 189 ///     std::vector<DeviceProvider*> providers;\r
 190 ///     plugins.getProviders(providers);\r
 191 ///\r
 192 ///     // create a Device from the first provider\r
 193 ///     if (!providers.empty()){\r
 194 ///         Device* myDevice = providers.first()->create();\r
 195 ///         // do something with myDevice\r
 196 ///         std::cout << device->getDescription() << std::endl;\r
 197 ///         // and delete it in the end\r
 198 ///         delete myDevice;\r
 199 ///     }\r
 200 ///     return 0;\r
 201 /// }\r
 202 /// \endcode\r
 203 ///\r
 204 ////////////////////////////////////////////////////////////\r