src/pluginmanager.h

   1 /***************************************************************************
   2 begin                : 2004/03/12
   3 copyright            : (C) Mark Kretschmann
   4 email                : markey@web.de
   5 ***************************************************************************/
   6
   7 /***************************************************************************
   8  *                                                                         *
   9  *   This program is free software; you can redistribute it and/or modify  *
  10  *   it under the terms of the GNU General Public License as published by  *
  11  *   the Free Software Foundation; either version 2 of the License, or     *
  12  *   (at your option) any later version.                                   *
  13  *                                                                         *
  14  ***************************************************************************/
  15
  16 #ifndef AMAROK_PLUGINMANAGER_H
  17 #define AMAROK_PLUGINMANAGER_H
  18
  19 #include <KService>
  20 #include <KServiceTypeTrader>
  21
  22 #include <vector>
  23
  24 namespace Amarok { class Plugin; }
  25 class KLibrary;
  26
  27 class PluginManager
  28 {
  29     public:
  30         /** Bump this number whenever the plugin framework gets incompatible with older versions */
  31         static const int FrameworkVersion = 30;
  32
  33         /**
  34          * It will return a list of services that match your
  35          * specifications.  The only required parameter is the service
  36          * type.  This is something like 'text/plain' or 'text/html'.  The
  37          * constraint parameter is used to limit the possible choices
  38          * returned based on the constraints you give it.
  39          *
  40          * The @p constraint language is rather full.  The most common
  41          * keywords are AND, OR, NOT, IN, and EXIST, all used in an
  42          * almost spoken-word form.  An example is:
  43          * \code
  44          * (Type == 'Service') and (('KParts/ReadOnlyPart' in ServiceTypes) or (exist Exec))
  45          * \endcode
  46          *
  47          * The keys used in the query (Type, ServiceType, Exec) are all
  48          * fields found in the .desktop files.
  49          *
  50          * @param constraint  A constraint to limit the choices returned, QString::null to
  51          *                    get all services of the given @p servicetype
  52          *
  53          * @return            A list of services that satisfy the query
  54          * @see               http://developer.kde.org/documentation/library/kdeqt/tradersyntax.html
  55          */
  56         static KService::List query( const QString& constraint = QString() );
  57
  58         /**
  59          * Load and instantiate plugin from query
  60          * @param constraint  A constraint to limit the choices returned, QString::null to
  61          *                    get all services of the given @p servicetype
  62          * @return            Pointer to Plugin, or NULL if error
  63          * @see               http://developer.kde.org/documentation/library/kdeqt/tradersyntax.html
  64          */
  65         static Amarok::Plugin* createFromQuery( const QString& constraint = QString() );
  66
  67         /**
  68          * Load and instantiate plugin from service
  69          * @param service     Pointer to KService
  70          * @return            Pointer to Plugin, or NULL if error
  71          */
  72         static Amarok::Plugin* createFromService( const KService::Ptr service );
  73
  74         /**
  75          * Remove library and delete plugin
  76          * @param plugin      Pointer to plugin
  77          */
  78         static void unload( Amarok::Plugin* plugin );
  79
  80         /**
  81          * Look up service for loaded plugin from store
  82          * @param pointer     Pointer to plugin
  83          * @return            KService, or 0 if not found
  84          */
  85         static KService::Ptr getService( const Amarok::Plugin* plugin );
  86
  87         /**
  88          * Dump properties from a service to stdout for debugging
  89          * @param service     Pointer to KService
  90          */
  91         static void dump( const KService::Ptr service );
  92
  93        /**
  94          * Show modal info dialog about plugin
  95          * @param constraint  A constraint to limit the choices returned
  96          */
  97         static void showAbout( const QString& constraint );
  98
  99     private:
 100         struct StoreItem {
 101             Amarok::Plugin* plugin;
 102             KLibrary* library;
 103             KService::Ptr service;
 104         };
 105
 106         static std::vector<StoreItem>::iterator lookupPlugin( const Amarok::Plugin* plugin );
 107
 108     //attributes:
 109         static std::vector<StoreItem> m_store;
 110 };
 111
 112
 113 #endif /* AMAROK_PLUGINMANAGER_H */
 114