1 ////////////////////////////////////////////////////////////
\r
3 // Pluma - Plug-in Management Framework
\r
4 // Copyright (C) 2010-2012 Gil Costa (gsaurus@gmail.com)
\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
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
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
18 // 2. Altered source versions must be plainly marked as such,
\r
19 // and must not be misrepresented as being the original software.
\r
21 // 3. This notice may not be removed or altered from any source distribution.
\r
23 ////////////////////////////////////////////////////////////
\r
25 #ifndef PLUMA_PROVIDER_HPP
\r
26 #define PLUMA_PROVIDER_HPP
\r
28 ////////////////////////////////////////////////////////////
\r
30 ////////////////////////////////////////////////////////////
\r
31 #include <Pluma/Config.hpp>
\r
38 ////////////////////////////////////////////////////////////
\r
39 /// \brief Interface to provide applications with objects from plugins.
\r
41 ////////////////////////////////////////////////////////////
\r
42 class PLUMA_API Provider{
\r
48 ////////////////////////////////////////////////////////////
\r
49 /// \brief Destructor.
\r
51 ////////////////////////////////////////////////////////////
\r
52 virtual ~Provider();
\r
54 ////////////////////////////////////////////////////////////
\r
55 /// \brief Get provider version.
\r
57 /// \return Version number.
\r
59 ////////////////////////////////////////////////////////////
\r
60 virtual unsigned int getVersion() const = 0;
\r
62 ////////////////////////////////////////////////////////////
\r
63 /// \brief Check compatibility with host.
\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
70 /// \param host Host, proxy of host application.
\r
72 /// \return True if it's compatible with \a host.
\r
74 ////////////////////////////////////////////////////////////
\r
75 bool isCompatible(const Host& host) const;
\r
80 ////////////////////////////////////////////////////////////
\r
81 /// \brief Get provider type.
\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
87 /// \return Provider type id.
\r
89 ////////////////////////////////////////////////////////////
\r
90 virtual std::string plumaGetType() const = 0;
\r
94 } // namespace pluma
\r
97 #endif // PLUMA_PROVIDER_HPP
\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
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
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
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
122 /// Device hpp (shared):
\r
124 /// #include <Pluma/Pluma.hpp>
\r
127 /// virtual std::string getDescription() const = 0;
\r
129 /// // create DevicedProvider class
\r
130 /// PLUMA_PROVIDER_HEADER(Device);
\r
133 /// Device cpp (shared):
\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
142 /// Keyboard code on the plugin side:
\r
144 /// #include <Pluma/Pluma.hpp>
\r
145 /// #include "Device.hpp"
\r
147 /// class Keyboard: public Device{
\r
149 /// std::string getDescription() const{
\r
150 /// return "keyboard";
\r
154 /// // create KeyboardProvider, it implements DeviceProvider
\r
155 /// PLUMA_INHERIT_PROVIDER(Keyboard, Device);
\r
158 /// plugin connector:
\r
160 /// #include <Pluma/Connector.hpp>
\r
161 /// #include "Keyboard.hpp"
\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
172 /// Host application code:
\r
174 /// #include <Pluma/Pluma.hpp>
\r
176 /// #include "Device.hpp"
\r
177 /// #include <iostream>
\r
178 /// #include <vector>
\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
188 /// // Get device providers into a vector
\r
189 /// std::vector<DeviceProvider*> providers;
\r
190 /// plugins.getProviders(providers);
\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
204 ////////////////////////////////////////////////////////////
\r