ctkPlugin.h 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670
  1. /*=============================================================================
  2. Library: CTK
  3. Copyright (c) German Cancer Research Center,
  4. Division of Medical and Biological Informatics
  5. Licensed under the Apache License, Version 2.0 (the "License");
  6. you may not use this file except in compliance with the License.
  7. You may obtain a copy of the License at
  8. http://www.apache.org/licenses/LICENSE-2.0
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. =============================================================================*/
  15. #ifndef CTKPLUGIN_H
  16. #define CTKPLUGIN_H
  17. #include "ctkPluginContext.h"
  18. #include "ctkVersion.h"
  19. class ctkPluginArchive;
  20. class ctkPluginFrameworkContext;
  21. class ctkPluginPrivate;
  22. /**
  23. * An installed plugin in the Framework.
  24. *
  25. * <p>
  26. * A <code>%ctkPlugin</code> object is the access point to define the lifecycle of
  27. * an installed plugin. Each plugin installed in the plugin environment must have
  28. * an associated <code>%ctkPlugin</code> object.
  29. *
  30. * <p>
  31. * A plugin must have a unique identity, a <code>long</code>, chosen by the
  32. * Framework. This identity must not change during the lifecycle of a plugin,
  33. * even when the plugin is updated. Uninstalling and then reinstalling the
  34. * plugin must create a new unique identity.
  35. *
  36. * <p>
  37. * A plugin can be in one of six states:
  38. * <ul>
  39. * <li>{@link #UNINSTALLED}
  40. * <li>{@link #INSTALLED}
  41. * <li>{@link #RESOLVED}
  42. * <li>{@link #STARTING}
  43. * <li>{@link #STOPPING}
  44. * <li>{@link #ACTIVE}
  45. * </ul>
  46. * <p>
  47. * They can be ORed together using the <code>States</code> type to
  48. * determine if a plugin is in one of the valid states.
  49. *
  50. * <p>
  51. * A plugin should only execute code when its state is one of
  52. * <code>STARTING</code>, <code>ACTIVE</code>, or <code>STOPPING</code>.
  53. * An <code>UNINSTALLED</code> plugin can not be set to another state; it is a
  54. * zombie and can only be reached because references are kept somewhere.
  55. *
  56. * <p>
  57. * The Framework is the only entity that is allowed to create
  58. * <code>%ctkPlugin</code> objects, and these objects are only valid within the
  59. * Framework that created them.
  60. *
  61. * @threadsafe
  62. */
  63. class CTK_PLUGINFW_EXPORT ctkPlugin {
  64. Q_DECLARE_PRIVATE(ctkPlugin)
  65. public:
  66. enum State {
  67. /**
  68. * The plugin is uninstalled and may not be used.
  69. *
  70. * <p>
  71. * The <code>UNINSTALLED</code> state is only visible after a plugin is
  72. * uninstalled; the plugin is in an unusable state but references to the
  73. * <code>%ctkPlugin</code> object may still be available and used for
  74. * introspection.
  75. */
  76. UNINSTALLED = 0x00000001,
  77. /**
  78. * The plugin is installed but not yet resolved.
  79. *
  80. * <p>
  81. * A plugin is in the <code>INSTALLED</code> state when it has been
  82. * installed in the Framework but is not or cannot be resolved.
  83. * <p>
  84. * This state is visible if the plugin's code dependencies are not resolved.
  85. * The Framework may attempt to resolve an <code>INSTALLED</code> plugin's
  86. * code dependencies and move the plugin to the <code>RESOLVED</code>
  87. * state.
  88. */
  89. INSTALLED = 0x00000002,
  90. /**
  91. * The plugin is resolved and is able to be started.
  92. *
  93. * <p>
  94. * A plugin is in the <code>RESOLVED</code> state when the Framework has
  95. * successfully resolved the plugin's code dependencies. These dependencies
  96. * include:
  97. * <ul>
  98. * <li>The plugin's required plugin dependencies from its
  99. * {@link ctkPluginConstants::REQUIRE_PLUGIN} Manifest header.
  100. * </ul>
  101. * <p>
  102. * Note that the plugin is not active yet. A plugin must be put in the
  103. * <code>RESOLVED</code> state before it can be started. The Framework may
  104. * attempt to resolve a plugin at any time.
  105. */
  106. RESOLVED = 0x00000004,
  107. /**
  108. * The plugin is in the process of starting.
  109. *
  110. * <p>
  111. * A plugin is in the <code>STARTING</code> state when its
  112. * {@link #start(const Options&) start} method is active. A plugin must be in this
  113. * state when the plugin's {@link ctkPluginActivator::start} method is called. If the
  114. * <code>ctkPluginActivator::start</code> method completes without exception,
  115. * then the plugin has successfully started and must move to the
  116. * <code>ACTIVE</code> state.
  117. * <p>
  118. * If the plugin does not have a
  119. * {@link ctkPluginConstants#ACTIVATION_EAGER eager activation policy}, then the
  120. * plugin may remain in this state for some time until the activation is
  121. * triggered.
  122. */
  123. STARTING = 0x00000008,
  124. /**
  125. * The plugin is in the process of stopping.
  126. *
  127. * <p>
  128. * A plugin is in the <code>STOPPING</code> state when its
  129. * {@link #stop(const Option&) stop} method is active. A plugin must be in this state
  130. * when the plugin's {@link ctkPluginActivator::stop} method is called. When the
  131. * <code>ctkPluginActivator::stop</code> method completes the plugin is
  132. * stopped and must move to the <code>RESOLVED</code> state.
  133. */
  134. STOPPING = 0x00000010,
  135. /**
  136. * The plugin is now running.
  137. *
  138. * <p>
  139. * A plugin is in the <code>ACTIVE</code> state when it has been
  140. * successfully started and activated.
  141. */
  142. ACTIVE = 0x00000020
  143. };
  144. /**
  145. * Represents an ORed combination of plugin states.
  146. *
  147. * @see #State
  148. */
  149. Q_DECLARE_FLAGS(States, State)
  150. enum StartOption {
  151. /**
  152. * The plugin start operation is transient and the persistent autostart
  153. * setting of the plugin is not modified.
  154. *
  155. * <p>
  156. * This option may be set when calling {@link #start(const StartOptions&)} to notify the
  157. * framework that the autostart setting of the plugin must not be modified.
  158. * If this option is not set, then the autostart setting of the plugin is
  159. * modified.
  160. *
  161. * @see #start(const StartOptions&)
  162. */
  163. START_TRANSIENT = 0x00000001,
  164. /**
  165. * The plugin start operation must activate the plugin according to the
  166. * plugin's declared
  167. * {@link ctkPluginConstants#PLUGIN_ACTIVATIONPOLICY activation policy}.
  168. *
  169. * <p>
  170. * This bit may be set when calling {@link #start(const StartOptions&)} to notify the
  171. * framework that the plugin must be activated using the plugin's declared
  172. * activation policy.
  173. *
  174. * @see ctkPluginConstants#PLUGIN_ACTIVATIONPOLICY
  175. * @see #start(const StartOptions&)
  176. */
  177. START_ACTIVATION_POLICY = 0x00000002
  178. };
  179. /**
  180. * Represents an ORed combination of start options.
  181. *
  182. * @see #StartOption
  183. */
  184. Q_DECLARE_FLAGS(StartOptions, StartOption)
  185. enum StopOption {
  186. /**
  187. * The plugin stop is transient and the persistent autostart setting of the
  188. * plugin is not modified.
  189. *
  190. * <p>
  191. * This option may be set when calling {@link #stop(const StopOptions&)} to notify the
  192. * framework that the autostart setting of the plugin must not be modified.
  193. * If this option is not set, then the autostart setting of the plugin is
  194. * modified.
  195. *
  196. * @see #stop(const StopOptions&)
  197. */
  198. STOP_TRANSIENT = 0x00000001
  199. };
  200. /**
  201. * Represents an ORed combination of stop options.
  202. *
  203. * @see #StopOption
  204. */
  205. Q_DECLARE_FLAGS(StopOptions, StopOption)
  206. virtual ~ctkPlugin();
  207. /**
  208. * Returns this plugin's current state.
  209. *
  210. * <p>
  211. * A plugin can be in only one state at any time.
  212. *
  213. * @return An element of <code>UNINSTALLED</code>,<code>INSTALLED</code>,
  214. * <code>RESOLVED</code>,<code>STARTING</code>,
  215. * <code>STOPPING</code>,<code>ACTIVE</code>.
  216. */
  217. State getState() const;
  218. /**
  219. * Starts this plugin.
  220. *
  221. * <p>
  222. * If this plugin's state is <code>UNINSTALLED</code> then an
  223. * <code>std::logic_error</code> is thrown.
  224. * <p>
  225. * The following steps are required to start this bundle:
  226. * <ol>
  227. * <li>If this plugin is in the process of being activated or deactivated
  228. * then this method must wait for activation or deactivation to complete
  229. * before continuing. If this does not occur in a reasonable time, a
  230. * <code>ctkPluginException</code> is thrown to indicate this plugin was unable
  231. * to be started.
  232. *
  233. * <li>If this plugin's state is <code>ACTIVE</code> then this method
  234. * returns immediately.
  235. *
  236. * <li>If the {@link #START_TRANSIENT} option is not set then set this
  237. * plugin's autostart setting to <em>Started with declared activation</em>
  238. * if the {@link #START_ACTIVATION_POLICY} option is set or
  239. * <em>Started with lazy activation</em> if not set. When the Framework is
  240. * restarted and this plugin's autostart setting is not <em>Stopped</em>,
  241. * this plugin must be automatically started.
  242. *
  243. * <li>If this plugin's state is not <code>RESOLVED</code>, an attempt is
  244. * made to resolve this plugin. If the Framework cannot resolve this plugin,
  245. * a <code>ctkPluginException</code> is thrown.
  246. *
  247. * <li>If the {@link #START_ACTIVATION_POLICY} option is not set then:
  248. * <ul>
  249. * <li>If this plugin's state is <code>STARTING</code> then this method
  250. * returns immediately.
  251. * <li>This plugin's state is set to <code>STARTING</code>.
  252. * <li>A plugin event of type {@link ctkPluginEvent::LAZY_ACTIVATION} is fired.
  253. * <li>This method returns immediately and the remaining steps will be
  254. * followed when this plugin's activation is later triggered.
  255. * </ul>
  256. * If the {@link #START_ACTIVATION_POLICY} option is set and this
  257. * plugin's declared activation policy is {@link ctkPluginConstants#ACTIVATION_EAGER
  258. * eager} then:
  259. * <i></i>
  260. * <li>This plugin's state is set to <code>STARTING</code>.
  261. *
  262. * <li>A plugin event of type {@link ctkPluginEvent::STARTING} is fired.
  263. *
  264. * <li>The {@link ctkPluginActivator::start} method of this plugin's
  265. * <code>ctkPluginActivator</code>, is called. If the
  266. * <code>ctkPluginActivator</code> throws an exception then:
  267. * <ul>
  268. * <li>This plugin's state is set to <code>STOPPING</code>.
  269. * <li>A plugin event of type {@link ctkPluginEvent::STOPPING} is fired.
  270. * <li>Any services registered by this plugin must be unregistered.
  271. * <li>Any services used by this plugin must be released.
  272. * <li>Any listeners registered by this plugin must be removed.
  273. * <li>This plugin's state is set to <code>RESOLVED</code>.
  274. * <li>A plugin event of type {@link ctkPluginEvent::STOPPED} is fired.
  275. * <li>A <code>ctkPluginException</code> is then thrown.
  276. * </ul>
  277. * <i></i>
  278. * <li>If this plugin's state is <code>UNINSTALLED</code>, because this
  279. * plugin was uninstalled while the <code>ctkPluginActivator::start</code>
  280. * method was running, a <code>ctkPluginException</code> is thrown.
  281. *
  282. * <li>This plugin's state is set to <code>ACTIVE</code>.
  283. *
  284. * <li>A plugin event of type {@link ctkPluginEvent::STARTED} is fired.
  285. * </ol>
  286. *
  287. * <b>Preconditions </b>
  288. * <ul>
  289. * <li><code>getState()</code> in { <code>INSTALLED</code>,
  290. * <code>RESOLVED</code>, <code>STARTING</code> }
  291. * or { <code>INSTALLED</code>, <code>RESOLVED</code> }
  292. * if this plugin has a eager activation policy.
  293. * </ul>
  294. * <b>Postconditions, no exceptions thrown </b>
  295. * <ul>
  296. * <li>Plugin autostart setting is modified unless the
  297. * {@link #START_TRANSIENT} option was set.
  298. * <li><code>getState()</code> in { <code>ACTIVE</code> }
  299. * if the eager activation policy was used.
  300. * <li><code>ctkPluginActivator::start()</code> has been called and did not
  301. * throw an exception if the eager policy was used.
  302. * </ul>
  303. * <b>Postconditions, when an exception is thrown </b>
  304. * <ul>
  305. * <li>Depending on when the exception occurred, plugin autostart setting is
  306. * modified unless the {@link #START_TRANSIENT} option was set.
  307. * <li><code>getState()</code> not in { <code>STARTING</code>,
  308. * <code>ACTIVE</code> }.
  309. * </ul>
  310. *
  311. * @param options The options for starting this plugin. See
  312. * {@link #START_TRANSIENT} and {@link #START_ACTIVATION_POLICY}. The
  313. * Framework must ignore unrecognized options.
  314. * @throws ctkPluginException If this plugin could not be started. This could
  315. * be because a code dependency could not be resolved or the
  316. * <code>ctkPluginActivator</code> could not be loaded or
  317. * threw an exception.
  318. * @throws std::logic_error If this plugin has been uninstalled or this
  319. * plugin tries to change its own state.
  320. */
  321. virtual void start(const StartOptions& options = START_ACTIVATION_POLICY);
  322. /**
  323. * Stops this plugin.
  324. *
  325. * <p>
  326. * The following steps are required to stop a plugin:
  327. * <ol>
  328. * <li>If this plugin's state is <code>UNINSTALLED</code> then an
  329. * <code>std::logic_error</code> is thrown.
  330. *
  331. * <li>If this plugin is in the process of being activated or deactivated
  332. * then this method must wait for activation or deactivation to complete
  333. * before continuing. If this does not occur in a reasonable time, a
  334. * <code>ctkPluginException</code> is thrown to indicate this plugin was unable
  335. * to be stopped.
  336. * <li>If the {@link #STOP_TRANSIENT} option is not set then then set this
  337. * plugin's persistent autostart setting to <em>Stopped</em>. When the
  338. * Framework is restarted and this plugin's autostart setting is
  339. * <em>Stopped</em>, this bundle must not be automatically started.
  340. *
  341. * <li>If this plugin's state is not <code>STARTING</code> or
  342. * <code>ACTIVE</code> then this method returns immediately.
  343. *
  344. * <li>This plugin's state is set to <code>STOPPING</code>.
  345. *
  346. * <li>A plugin event of type {@link ctkPluginEvent::STOPPING} is fired.
  347. *
  348. * <li>If this plugin's state was <code>ACTIVE</code> prior to setting the
  349. * state to <code>STOPPING</code>, the {@link ctkPluginActivator#stop} method
  350. * of this plugin's <code>ctkPluginActivator</code> is
  351. * called. If that method throws an exception, this method must continue to
  352. * stop this plugin and a <code>ctkPluginException</code> must be thrown after
  353. * completion of the remaining steps.
  354. *
  355. * <li>Any services registered by this plugin must be unregistered.
  356. * <li>Any services used by this plugin must be released.
  357. * <li>Any listeners registered by this plugin must be removed.
  358. *
  359. * <li>If this plugin's state is <code>UNINSTALLED</code>, because this
  360. * plugin was uninstalled while the <code>ctkPluginActivator::stop</code> method
  361. * was running, a <code>ctkPluginException</code> must be thrown.
  362. *
  363. * <li>This plugin's state is set to <code>RESOLVED</code>.
  364. *
  365. * <li>A plugin event of type {@link ctkPluginEvent::STOPPED} is fired.
  366. * </ol>
  367. *
  368. * <b>Preconditions </b>
  369. * <ul>
  370. * <li><code>getState()</code> in { <code>ACTIVE</code> }.
  371. * </ul>
  372. * <b>Postconditions, no exceptions thrown </b>
  373. * <ul>
  374. * <li>Plugin autostart setting is modified unless the
  375. * {@link #STOP_TRANSIENT} option was set.
  376. * <li><code>getState()</code> not in &#x007B; <code>ACTIVE</code>,
  377. * <code>STOPPING</code> &#x007D;.
  378. * <li><code>ctkPluginActivator::stop</code> has been called and did not throw
  379. * an exception.
  380. * </ul>
  381. * <b>Postconditions, when an exception is thrown </b>
  382. * <ul>
  383. * <li>Plugin autostart setting is modified unless the
  384. * {@link #STOP_TRANSIENT} option was set.
  385. * </ul>
  386. *
  387. * @param options The options for stoping this bundle. See
  388. * {@link #STOP_TRANSIENT}.
  389. * @throws ctkPluginException If this plugin's <code>ctkPluginActivator</code>
  390. * threw an exception.
  391. * @throws std::logic_error If this plugin has been uninstalled or this
  392. * plugin tries to change its own state.
  393. */
  394. virtual void stop(const StopOptions& options = 0);
  395. /**
  396. * Uninstalls this plugin.
  397. *
  398. * <p>
  399. * This method causes the Plugin Framework to notify other plugins that this
  400. * plugin is being uninstalled, and then puts this plugin into the
  401. * <code>UNINSTALLED</code> state. The Framework must remove any resources
  402. * related to this plugin that it is able to remove.
  403. *
  404. * <p>
  405. * If this plugin is required by other plugins which are already resolved,
  406. * the Framework must keep this plugin loaded until the
  407. * Framework is relaunched.
  408. *
  409. * <p>
  410. * The following steps are required to uninstall a plugin:
  411. * <ol>
  412. * <li>If this plugin's state is <code>UNINSTALLED</code> then an
  413. * <code>std::logic_error</code> is thrown.
  414. *
  415. * <li>If this plugin's state is <code>ACTIVE</code>, <code>STARTING</code>
  416. * or <code>STOPPING</code>, this plugin is stopped as described in the
  417. * <code>ctkPlugin::stop</code> method. If <code>ctkPlugin::stop</code> throws an
  418. * exception, a Framework event of type ctkFrameworkEvent::ERROR is
  419. * fired containing the exception.
  420. *
  421. * <li>This plugin's state is set to <code>UNINSTALLED</code>.
  422. *
  423. * <li>A plugin event of type ctkPluginEvent::UNINSTALLED is fired.
  424. *
  425. * <li>This plugin and any persistent storage area provided for this plugin
  426. * by the Framework are removed.
  427. * </ol>
  428. *
  429. * <b>Preconditions </b>
  430. * <ul>
  431. * <li><code>getState()</code> not in &#x007B; <code>UNINSTALLED</code>
  432. * &#x007D;.
  433. * </ul>
  434. * <b>Postconditions, no exceptions thrown </b>
  435. * <ul>
  436. * <li><code>getState()</code> in &#x007B; <code>UNINSTALLED</code>
  437. * &#x007D;.
  438. * <li>This plugin has been uninstalled.
  439. * </ul>
  440. * <b>Postconditions, when an exception is thrown </b>
  441. * <ul>
  442. * <li><code>getState()</code> not in &#x007B; <code>UNINSTALLED</code>
  443. * &#x007D;.
  444. * <li>This plugin has not been uninstalled.
  445. * </ul>
  446. *
  447. * @throws ctkPluginException If the uninstall failed. This can occur if
  448. * another thread is attempting to change this plugin's state and
  449. * does not complete in a timely manner.
  450. * @throws std::logic_error If this plugin has been uninstalled or this
  451. * plugin tries to change its own state.
  452. * @see #stop()
  453. */
  454. void uninstall();
  455. /**
  456. * Returns this plugin's {@link ctkPluginContext}. The returned
  457. * <code>ctkPluginContext</code> can be used by the caller to act on behalf
  458. * of this plugin.
  459. *
  460. * <p>
  461. * If this plugin is not in the {@link #STARTING}, {@link #ACTIVE}, or
  462. * {@link #STOPPING} states, then this
  463. * plugin has no valid <code>ctkPluginContext</code>. This method will
  464. * return <code>0</code> if this plugin has no valid
  465. * <code>ctkPluginContext</code>.
  466. *
  467. * @return A <code>ctkPluginContext</code> for this plugin or
  468. * <code>0</code> if this plugin has no valid
  469. * <code>ctkPluginContext</code>.
  470. */
  471. ctkPluginContext* getPluginContext() const;
  472. /**
  473. * Returns this plugin's unique identifier. This plugin is assigned a unique
  474. * identifier by the Framework when it was installed in the plugin
  475. * environment.
  476. *
  477. * <p>
  478. * A plugin's unique identifier has the following attributes:
  479. * <ul>
  480. * <li>Is unique and persistent.
  481. * <li>Is a <code>long</code>.
  482. * <li>Its value is not reused for another plugin, even after a plugin is
  483. * uninstalled.
  484. * <li>Does not change while a plugin remains installed.
  485. * <li>Does not change when a plugin is updated.
  486. * </ul>
  487. *
  488. * <p>
  489. * This method must continue to return this plugin's unique identifier while
  490. * this plugin is in the <code>UNINSTALLED</code> state.
  491. *
  492. * @return The unique identifier of this plugin.
  493. */
  494. long getPluginId() const;
  495. /**
  496. * Returns this plugin's location identifier.
  497. *
  498. * <p>
  499. * The location identifier is the location passed to
  500. * <code>ctkPluginContext::installPlugin</code> when a plugin is installed.
  501. * The location identifier does not change while this plugin remains
  502. * installed, even if this plugin is updated.
  503. *
  504. * <p>
  505. * This method must continue to return this plugin's location identifier
  506. * while this plugin is in the <code>UNINSTALLED</code> state.
  507. *
  508. * @return The string representation of this plugin's location identifier.
  509. */
  510. QString getLocation() const;
  511. /**
  512. * Returns this plugin's Manifest headers and values. This method returns
  513. * all the Manifest headers and values from the main section of this
  514. * bundle's Manifest file; that is, all lines prior to the first named section.
  515. *
  516. * TODO: documentation about manifest value internationalization
  517. *
  518. * <p>
  519. * For example, the following Manifest headers and values are included if
  520. * they are present in the Manifest file:
  521. *
  522. * <pre>
  523. * Plugin-Name
  524. * Plugin-Vendor
  525. * Plugin-ctkVersion
  526. * Plugin-Description
  527. * Plugin-DocURL
  528. * Plugin-ContactAddress
  529. * </pre>
  530. *
  531. * <p>
  532. * This method must continue to return Manifest header information while
  533. * this plugin is in the <code>UNINSTALLED</code> state.
  534. *
  535. * @return A <code>QHash<Qstring, QString></code> object containing this plugin's
  536. * Manifest headers and values.
  537. */
  538. virtual QHash<QString, QString> getHeaders();
  539. /**
  540. * Returns the symbolic name of this plugin as specified by its
  541. * <code>Plugin-SymbolicName</code> manifest header. The plugin symbolic
  542. * name together with a version must identify a unique plugin. The plugin
  543. * symbolic name should be based on the reverse domain name naming
  544. * convention like that used for java packages.
  545. *
  546. * <p>
  547. * This method must continue to return this plugin's symbolic name while
  548. * this plugin is in the <code>UNINSTALLED</code> state.
  549. *
  550. * @return The symbolic name of this plugin or a null QString if this
  551. * plugin does not have a symbolic name.
  552. */
  553. QString getSymbolicName() const;
  554. /**
  555. * Returns a list of all the files and directories
  556. * within this plugin whose longest sub-path matches the
  557. * specified path.
  558. * <p>
  559. * The specified path is always relative to the root of this plugin
  560. * (the plugins symbolic name) and may begin with a &quot;/&quot;.
  561. * A path value of &quot;/&quot; indicates the root of this plugin.
  562. * <p>
  563. * Returned paths indicating subdirectory paths end with a &quot;/&quot;.
  564. * The returned paths are all relative to the root of this plugin and must
  565. * not begin with &quot;/&quot;.
  566. * <p>
  567. *
  568. * @param path The path name for which to return resource paths.
  569. * @return A list of the resource paths (<code>QString</code>
  570. * objects) or an empty list if no entry could be found.
  571. * @throws std::logic_error If this plugin has been
  572. * uninstalled.
  573. */
  574. virtual QStringList getResourceList(const QString& path) const;
  575. /**
  576. * Returns a QByteArray containing a Qt resource located at the
  577. * specified path in this plugin.
  578. * <p>
  579. * The specified path is always relative to the root of this plugin
  580. * (the plugins symbolic name) and may
  581. * begin with &quot;/&quot;. A path value of &quot;/&quot; indicates the
  582. * root of this plugin.
  583. * <p>
  584. *
  585. * @param path The path name of the resource.
  586. * @return A QString to the resource, or a null QString if no resource could be
  587. * found.
  588. * @throws std::logic_error If this plugin has been
  589. * uninstalled.
  590. */
  591. virtual QByteArray getResource(const QString& path) const;
  592. /**
  593. * Returns the version of this plugin as specified by its
  594. * <code>Plugin-Version</code> manifest header. If this plugin does not have a
  595. * specified version then {@link Version#emptyVersion} is returned.
  596. *
  597. * <p>
  598. * This method must continue to return this plugin's version while
  599. * this plugin is in the <code>UNINSTALLED</code> state.
  600. *
  601. * @return The version of this plugin.
  602. */
  603. ctkVersion getVersion() const;
  604. protected:
  605. friend class ctkPluginFramework;
  606. friend class ctkPluginFrameworkContext;
  607. friend class ctkPlugins;
  608. friend class ctkServiceReferencePrivate;
  609. ctkPluginPrivate * const d_ptr;
  610. ctkPlugin(ctkPluginFrameworkContext* fw, ctkPluginArchive* ba);
  611. ctkPlugin(ctkPluginPrivate& dd);
  612. };
  613. Q_DECLARE_METATYPE(ctkPlugin*)
  614. Q_DECLARE_OPERATORS_FOR_FLAGS(ctkPlugin::States)
  615. Q_DECLARE_OPERATORS_FOR_FLAGS(ctkPlugin::StartOptions)
  616. Q_DECLARE_OPERATORS_FOR_FLAGS(ctkPlugin::StopOptions)
  617. CTK_PLUGINFW_EXPORT QDebug operator<<(QDebug debug, ctkPlugin::State state);
  618. CTK_PLUGINFW_EXPORT QDebug operator<<(QDebug debug, const ctkPlugin& plugin);
  619. CTK_PLUGINFW_EXPORT QDebug operator<<(QDebug debug, ctkPlugin const * plugin);
  620. #endif // CTKPLUGIN_H