doc/third_party/Pluma/html/classpluma_1_1Provider.htm

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3     <head>
   4         <title>Pluma - Plug-in Management Framework</title>
   5         <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
   6         <link href="doxygen.css" rel="stylesheet" type="text/css" />
   7         <link href="tabs.css" rel="stylesheet" type="text/css" />
   8     </head>
   9     <body>
  10         <div id="logo">
  11             <img src="./logo.png" title="Pluma home" alt="Pluma logo" />
  12         </div>
  13 <!-- Generated by Doxygen 1.8.6 -->
  14   <div id="navrow1" class="tabs">
  15     <ul class="tablist">
  16       <li><a href="index.htm"><span>Main&#160;Page</span></a></li>
  17       <li class="current"><a href="annotated.htm"><span>Classes</span></a></li>
  18       <li><a href="files.htm"><span>Files</span></a></li>
  19     </ul>
  20   </div>
  21   <div id="navrow2" class="tabs2">
  22     <ul class="tablist">
  23       <li><a href="annotated.htm"><span>Class&#160;List</span></a></li>
  24       <li><a href="classes.htm"><span>Class&#160;Index</span></a></li>
  25       <li><a href="hierarchy.htm"><span>Class&#160;Hierarchy</span></a></li>
  26       <li><a href="functions.htm"><span>Class&#160;Members</span></a></li>
  27     </ul>
  28   </div>
  29 <div id="nav-path" class="navpath">
  30   <ul>
  31 <li class="navelem"><b>pluma</b></li><li class="navelem"><a class="el" href="classpluma_1_1Provider.htm">Provider</a></li>  </ul>
  32 </div>
  33 </div><!-- top -->
  34 <div class="header">
  35   <div class="summary">
  36 <a href="#pub-methods">Public Member Functions</a> &#124;
  37 <a href="#friends">Friends</a> &#124;
  38 <a href="classpluma_1_1Provider-members.htm">List of all members</a>  </div>
  39   <div class="headertitle">
  40 <div class="title">pluma::Provider Class Reference<span class="mlabels"><span class="mlabel">abstract</span></span></div>  </div>
  41 </div><!--header-->
  42 <div class="contents">
  43
  44 <p>Interface to provide applications with objects from plugins.
  45  <a href="classpluma_1_1Provider.htm#details">More...</a></p>
  46
  47 <p><code>#include &lt;<a class="el" href="Provider_8hpp_source.htm">Provider.hpp</a>&gt;</code></p>
  48 <table class="memberdecls">
  49 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-methods"></a>
  50 Public Member Functions</h2></td></tr>
  51 <tr class="memitem:a111a1db902d6372282f8407c9d845c21"><td class="memItemLeft" align="right" valign="top">virtual&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpluma_1_1Provider.htm#a111a1db902d6372282f8407c9d845c21">~Provider</a> ()</td></tr>
  52 <tr class="memdesc:a111a1db902d6372282f8407c9d845c21"><td class="mdescLeft">&#160;</td><td class="mdescRight">Destructor.  <a href="#a111a1db902d6372282f8407c9d845c21">More...</a><br/></td></tr>
  53 <tr class="separator:a111a1db902d6372282f8407c9d845c21"><td class="memSeparator" colspan="2">&#160;</td></tr>
  54 <tr class="memitem:af8643b65e111e010edff6e7a489265e6"><td class="memItemLeft" align="right" valign="top">virtual unsigned int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpluma_1_1Provider.htm#af8643b65e111e010edff6e7a489265e6">getVersion</a> () const =0</td></tr>
  55 <tr class="memdesc:af8643b65e111e010edff6e7a489265e6"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get provider version.  <a href="#af8643b65e111e010edff6e7a489265e6">More...</a><br/></td></tr>
  56 <tr class="separator:af8643b65e111e010edff6e7a489265e6"><td class="memSeparator" colspan="2">&#160;</td></tr>
  57 <tr class="memitem:a192ea5a17a8fe9de1f3ba6572f44f266"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpluma_1_1Provider.htm#a192ea5a17a8fe9de1f3ba6572f44f266">isCompatible</a> (const <a class="el" href="classpluma_1_1Host.htm">Host</a> &amp;host) const </td></tr>
  58 <tr class="memdesc:a192ea5a17a8fe9de1f3ba6572f44f266"><td class="mdescLeft">&#160;</td><td class="mdescRight">Check compatibility with host.  <a href="#a192ea5a17a8fe9de1f3ba6572f44f266">More...</a><br/></td></tr>
  59 <tr class="separator:a192ea5a17a8fe9de1f3ba6572f44f266"><td class="memSeparator" colspan="2">&#160;</td></tr>
  60 </table><table class="memberdecls">
  61 <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="friends"></a>
  62 Friends</h2></td></tr>
  63 <tr class="memitem:a912b690126957a1ad90d0c373a4ad4d0"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a912b690126957a1ad90d0c373a4ad4d0"></a>
  64 class&#160;</td><td class="memItemRight" valign="bottom"><b>Host</b></td></tr>
  65 <tr class="separator:a912b690126957a1ad90d0c373a4ad4d0"><td class="memSeparator" colspan="2">&#160;</td></tr>
  66 </table>
  67 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
  68 <div class="textblock"><p>Interface to provide applications with objects from plugins. </p>
  69 <p>The plugin specific implementations are unknown at the host side, only their shared interfaces are known. Then, host app needs a generic way of create interface objects. That's what provider classes are for. It is the factory design pattern (<a href="http://www.oodesign.com/factory-pattern.html">http://www.oodesign.com/factory-pattern.html</a>)</p>
  70 <p>Shared interfaces define their provider types (by inheriting from <a class="el" href="classpluma_1_1Provider.htm" title="Interface to provide applications with objects from plugins. ">pluma::Provider</a>). Hosts then use those tipes to get objects from the plugins. Plugins derive the shared interface providers so that they can provide host with specific implementations of the shared interface. Those specific providers are given to the host through a connect function.</p>
  71 <p>Example: A host app uses objects of type Device. A certain plugin defines a Keyboard, witch is a Device. The <a class="el" href="classpluma_1_1Host.htm" title="Manages providers. ">Host</a> will use DeviceProviders to create objects of type Device. The plugin will provide host specifically with a KeyboardProvider. Other plugins may provide host with other derived DeviceProvider types.</p>
  72 <p>Device hpp (shared): </p>
  73 <div class="fragment"><div class="line"><span class="preprocessor">#include &lt;Pluma/Pluma.hpp&gt;</span></div>
  74 <div class="line"><span class="keyword">class </span>Device{</div>
  75 <div class="line"><span class="keyword">public</span>:</div>
  76 <div class="line">    <span class="keyword">virtual</span> std::string getDescription() <span class="keyword">const</span> = 0;</div>
  77 <div class="line">};</div>
  78 <div class="line"><span class="comment">// create DevicedProvider class</span></div>
  79 <div class="line">PLUMA_PROVIDER_HEADER(Device);</div>
  80 </div><!-- fragment --><p>Device cpp (shared): </p>
  81 <div class="fragment"><div class="line"><span class="preprocessor">#include &quot;Device.hpp&quot;</span></div>
  82 <div class="line">generate DevicedProvider with version 6, and compatible with at least v.3</div>
  83 <div class="line">PLUMA_PROVIDER_SOURCE(Device, 6, 3);</div>
  84 </div><!-- fragment --><p><br/>
  85  Keyboard code on the plugin side: </p>
  86 <div class="fragment"><div class="line"><span class="preprocessor">#include &lt;Pluma/Pluma.hpp&gt;</span></div>
  87 <div class="line"><span class="preprocessor">#include &quot;Device.hpp&quot;</span></div>
  88 <div class="line"></div>
  89 <div class="line"><span class="keyword">class </span>Keyboard: <span class="keyword">public</span> Device{</div>
  90 <div class="line"><span class="keyword">public</span>:</div>
  91 <div class="line">    std::string getDescription()<span class="keyword"> const</span>{</div>
  92 <div class="line">        <span class="keywordflow">return</span> <span class="stringliteral">&quot;keyboard&quot;</span>;</div>
  93 <div class="line">    }</div>
  94 <div class="line">};</div>
  95 <div class="line"></div>
  96 <div class="line"><span class="comment">// create KeyboardProvider, it implements DeviceProvider</span></div>
  97 <div class="line">PLUMA_INHERIT_PROVIDER(Keyboard, Device);</div>
  98 </div><!-- fragment --><p>plugin connector: </p>
  99 <div class="fragment"><div class="line"><span class="preprocessor">#include &lt;Pluma/Connector.hpp&gt;</span></div>
 100 <div class="line"><span class="preprocessor">#include &quot;Keyboard.hpp&quot;</span></div>
 101 <div class="line"></div>
 102 <div class="line">PLUMA_CONNECTOR</div>
 103 <div class="line"><span class="keywordtype">bool</span> connect(<a class="code" href="classpluma_1_1Host.htm">pluma::Host</a>&amp; host){</div>
 104 <div class="line">    <span class="comment">// add a keyboard provider to host</span></div>
 105 <div class="line">    host.<a class="code" href="classpluma_1_1Host.htm#ab673ba94ff56a12cdf2a7a25ebb8cc36">add</a>( <span class="keyword">new</span> KeyboardProvider() );</div>
 106 <div class="line">    <span class="keywordflow">return</span> <span class="keyword">true</span>;</div>
 107 <div class="line">}</div>
 108 </div><!-- fragment --><p><a class="el" href="classpluma_1_1Host.htm" title="Manages providers. ">Host</a> application code: </p>
 109 <div class="fragment"><div class="line"><span class="preprocessor">#include &lt;Pluma/Pluma.hpp&gt;</span></div>
 110 <div class="line"></div>
 111 <div class="line"><span class="preprocessor">#include &quot;Device.hpp&quot;</span></div>
 112 <div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div>
 113 <div class="line"><span class="preprocessor">#include &lt;vector&gt;</span></div>
 114 <div class="line"></div>
 115 <div class="line"><span class="keywordtype">int</span> main(){</div>
 116 <div class="line"></div>
 117 <div class="line">    <a class="code" href="classpluma_1_1Pluma.htm">pluma::Pluma</a> plugins;</div>
 118 <div class="line">    <span class="comment">// Tell plugins manager to accept providers of the type DeviceProvider</span></div>
 119 <div class="line">    plugins.<a class="code" href="classpluma_1_1Pluma.htm#a200c59b0983c7ca53d11b03cf8220bc7">acceptProviderType</a>&lt;DeviceProvider&gt;();</div>
 120 <div class="line">    <span class="comment">// Load library &quot;standard_devices&quot; from folder &quot;plugins&quot;</span></div>
 121 <div class="line">    plugins.<a class="code" href="classpluma_1_1PluginManager.htm#aa00400d23efa8a8f94e44dd1c5bf54e6">load</a>(<span class="stringliteral">&quot;plugins&quot;</span>, <span class="stringliteral">&quot;standard_devices&quot;</span>);</div>
 122 <div class="line"></div>
 123 <div class="line">    <span class="comment">// Get device providers into a vector</span></div>
 124 <div class="line">    std::vector&lt;DeviceProvider*&gt; providers;</div>
 125 <div class="line">    plugins.<a class="code" href="classpluma_1_1Pluma.htm#a49fa0b2b4497885c4e978259be0a7abe">getProviders</a>(providers);</div>
 126 <div class="line"></div>
 127 <div class="line">    <span class="comment">// create a Device from the first provider</span></div>
 128 <div class="line">    <span class="keywordflow">if</span> (!providers.empty()){</div>
 129 <div class="line">        Device* myDevice = providers.first()-&gt;create();</div>
 130 <div class="line">        <span class="comment">// do something with myDevice</span></div>
 131 <div class="line">        std::cout &lt;&lt; device-&gt;getDescription() &lt;&lt; std::endl;</div>
 132 <div class="line">        <span class="comment">// and delete it in the end</span></div>
 133 <div class="line">        <span class="keyword">delete</span> myDevice;</div>
 134 <div class="line">    }</div>
 135 <div class="line">    <span class="keywordflow">return</span> 0;</div>
 136 <div class="line">}</div>
 137 </div><!-- fragment -->
 138 <p>Definition at line <a class="el" href="Provider_8hpp_source.htm#l00042">42</a> of file <a class="el" href="Provider_8hpp_source.htm">Provider.hpp</a>.</p>
 139 </div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
 140 <a class="anchor" id="a111a1db902d6372282f8407c9d845c21"></a>
 141 <div class="memitem">
 142 <div class="memproto">
 143 <table class="mlabels">
 144   <tr>
 145   <td class="mlabels-left">
 146       <table class="memname">
 147         <tr>
 148           <td class="memname">pluma::Provider::~Provider </td>
 149           <td>(</td>
 150           <td class="paramname"></td><td>)</td>
 151           <td></td>
 152         </tr>
 153       </table>
 154   </td>
 155   <td class="mlabels-right">
 156 <span class="mlabels"><span class="mlabel">virtual</span></span>  </td>
 157   </tr>
 158 </table>
 159 </div><div class="memdoc">
 160
 161 <p>Destructor. </p>
 162
 163 <p>Definition at line <a class="el" href="Provider_8cpp_source.htm#l00036">36</a> of file <a class="el" href="Provider_8cpp_source.htm">Provider.cpp</a>.</p>
 164
 165 </div>
 166 </div>
 167 <h2 class="groupheader">Member Function Documentation</h2>
 168 <a class="anchor" id="af8643b65e111e010edff6e7a489265e6"></a>
 169 <div class="memitem">
 170 <div class="memproto">
 171 <table class="mlabels">
 172   <tr>
 173   <td class="mlabels-left">
 174       <table class="memname">
 175         <tr>
 176           <td class="memname">virtual unsigned int pluma::Provider::getVersion </td>
 177           <td>(</td>
 178           <td class="paramname"></td><td>)</td>
 179           <td> const</td>
 180         </tr>
 181       </table>
 182   </td>
 183   <td class="mlabels-right">
 184 <span class="mlabels"><span class="mlabel">pure virtual</span></span>  </td>
 185   </tr>
 186 </table>
 187 </div><div class="memdoc">
 188
 189 <p>Get provider version. </p>
 190 <dl class="section return"><dt>Returns</dt><dd>Version number. </dd></dl>
 191
 192 </div>
 193 </div>
 194 <a class="anchor" id="a192ea5a17a8fe9de1f3ba6572f44f266"></a>
 195 <div class="memitem">
 196 <div class="memproto">
 197       <table class="memname">
 198         <tr>
 199           <td class="memname">bool pluma::Provider::isCompatible </td>
 200           <td>(</td>
 201           <td class="paramtype">const <a class="el" href="classpluma_1_1Host.htm">Host</a> &amp;&#160;</td>
 202           <td class="paramname"><em>host</em></td><td>)</td>
 203           <td> const</td>
 204         </tr>
 205       </table>
 206 </div><div class="memdoc">
 207
 208 <p>Check compatibility with host. </p>
 209 <p>The same provider may be compiled with different versions on host side and on plugins side. This function checks if a plugin provider is compatible with the current version of the same provider type on the host side.</p>
 210 <dl class="params"><dt>Parameters</dt><dd>
 211   <table class="params">
 212     <tr><td class="paramname">host</td><td><a class="el" href="classpluma_1_1Host.htm" title="Manages providers. ">Host</a>, proxy of host application.</td></tr>
 213   </table>
 214   </dd>
 215 </dl>
 216 <dl class="section return"><dt>Returns</dt><dd>True if it's compatible with <em>host</em>. </dd></dl>
 217
 218 <p>Definition at line <a class="el" href="Provider_8cpp_source.htm#l00042">42</a> of file <a class="el" href="Provider_8cpp_source.htm">Provider.cpp</a>.</p>
 219
 220 </div>
 221 </div>
 222 <hr/>The documentation for this class was generated from the following files:<ul>
 223 <li><a class="el" href="Provider_8hpp_source.htm">Provider.hpp</a></li>
 224 <li><a class="el" href="Provider_8cpp_source.htm">Provider.cpp</a></li>
 225 </ul>
 226 </div><!-- contents -->
 227
 228         <p id="footer">
 229             &nbsp;::&nbsp; Copyright &copy; 2011 Gil Costa, all rights reserved &nbsp;::&nbsp;
 230             Documentation generated by <a href="http://www.doxygen.org/" title="doxygen website">doxygen 1.7.4</a> &nbsp;::&nbsp;
 231         </p>
 232     </body>
 233 </html>