KService

kservicetypetrader.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000 Torben Weis <[email protected]>
4  SPDX-FileCopyrightText: 2006 David Faure <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef __kservicetypetrader_h__
10 #define __kservicetypetrader_h__
11 
12 #include "kservice.h"
13 
14 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 90)
15 
16 class KServiceOffer;
18 class KServiceTypeTraderPrivate;
19 /**
20  * @class KServiceTypeTrader kservicetypetrader.h <KServiceTypeTrader>
21  *
22  * KDE's trader interface (similar to the CORBA Trader), which provides a way
23  * to query the KDE infrastructure for specific applications or components.
24  *
25  * Basically, KServiceTypeTrader provides a way for an application to query
26  * all KDE services (that is, applications, components, plugins) that match
27  * a specific set of requirements. This allows to find specific services
28  * at run-time without having to hard-code their names and/or paths.
29  *
30  * For anything relating to MIME types (type of files), ignore KServiceTypeTrader
31  * and use KMimeTypeTrader instead.
32  *
33  * \par Example
34  *
35  * If you want to find all plugins for your application,
36  * you would define a KMyApp/Plugin servicetype, and then you can query
37  * the trader for it:
38  * \code
39  * KService::List offers =
40  * KServiceTypeTrader::self()->query("KMyApp/Plugin");
41  * \endcode
42  *
43  * You can add a constraint in the "trader query language". For instance:
44  * \code
45  * KServiceTypeTrader::self()->query("KMyApp/Plugin",
46  * "[X-KMyApp-InterfaceVersion] > 15");
47  * \endcode
48  *
49  * Please note that when including property names containing arithmetic operators like - or +, then you have
50  * to put brackets around the property name, in order to correctly separate arithmetic operations from
51  * the name. So for example a constraint expression like
52  * \code
53  * X-KMyApp-InterfaceVersion > 4 // wrong!
54  * \endcode
55  * needs to be written as
56  * \code
57  * [X-KMyApp-InterfaceVersion] > 4
58  * \endcode
59  * otherwise it could also be interpreted as
60  * Subtract the numeric value of the property "KMyApp" and "InterfaceVersion" from the
61  * property "X" and make sure it is greater than 4.
62  * Instead of the other meaning, make sure that the numeric value of "X-KMyApp-InterfaceVersion" is
63  * greater than 4.
64  *
65  * @see KMimeTypeTrader, KService
66  * @deprecated Since 5.90.
67  * For querying plugins use @p KPluginMetaData::findPlugins.
68  * For querying applications use @p KApplicationTrader.
69  * For querying KParts use @p KParts::PartLoader.
70  * For querying desktop files use @p KFileUtils::findAllUniqueFiles and @p KDesktopFile.
71  */
72 class KSERVICE_EXPORT KServiceTypeTrader
73 {
74 public:
75  /**
76  * Standard destructor
77  */
79 
80  /**
81  * The main function in the KServiceTypeTrader class.
82  *
83  * It will return a list of services that match your
84  * specifications. The only required parameter is the service
85  * type. This is something like 'text/plain' or 'text/html'. The
86  * constraint parameter is used to limit the possible choices
87  * returned based on the constraints you give it.
88  *
89  * The @p constraint language is rather full. The most common
90  * keywords are AND, OR, NOT, IN, and EXIST, all used in an
91  * almost spoken-word form. An example is:
92  * \code
93  * (Type == 'Service') and (('KParts/ReadOnlyPart' in ServiceTypes) or (exist Exec))
94  * \endcode
95  *
96  * The keys used in the query (Type, ServiceType, Exec) are all
97  * fields found in the .desktop files.
98  *
99  * @param servicetype A service type like 'KMyApp/Plugin' or 'KFilePlugin'.
100  * @param constraint A constraint to limit the choices returned, QString() to
101  * get all services of the given @p servicetype
102  *
103  * @return A list of services that satisfy the query
104  * @see http://techbase.kde.org/Development/Tutorials/Services/Traders#The_KTrader_Query_Language
105  */
106  KService::List query(const QString &servicetype, const QString &constraint = QString()) const;
107 
108  /**
109  * Returns all offers associated with a given servicetype, IGNORING the
110  * user preference. The sorting will be the one coming from the InitialPreference
111  * in the .desktop files, and services disabled by the user will still be listed here.
112  * This is used for "Revert to defaults" buttons in GUIs.
113  */
114  KService::List defaultOffers(const QString &serviceType, const QString &constraint = QString()) const;
115  /**
116  * Returns the preferred service for @p serviceType.
117  *
118  * @param serviceType the service type (e.g. "KMyApp/Plugin")
119  * @return the preferred service, or @c nullptr if no service is available
120  */
121  KService::Ptr preferredService(const QString &serviceType) const;
122 
123  /**
124  * This is a static pointer to the KServiceTypeTrader singleton.
125  *
126  * You will need to use this to access the KServiceTypeTrader functionality since the
127  * constructors are protected.
128  *
129  * @return Static KServiceTypeTrader instance
130  * @deprecated Since 5.90, see class API docs
131  */
132  KSERVICE_DEPRECATED_VERSION(5, 90, "See class API docs")
133  static KServiceTypeTrader *self();
134 
135 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 86)
136 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 86)
137  /**
138  * Get a plugin from a trader query
139  *
140  * Example:
141  * \code
142  * KMyAppPlugin* plugin = KServiceTypeTrader::createInstanceFromQuery<KMyAppPlugin>( serviceType, QString(), parentObject );
143  * if ( plugin ) {
144  * ....
145  * }
146  * \endcode
147  *
148  * @param serviceType the type of service for which to find a plugin
149  * @param constraint an optional constraint to pass to the trader (see KTrader)
150  * @param parent the parent object for the part itself
151  * @param args A list of arguments passed to the service component
152  * @param error The string passed here will contain an error description.
153  * @return A pointer to the newly created object or a null pointer if the
154  * factory was unable to create an object of the given type.
155  *
156  * @see KPluginFactory::instantiatePlugin
157  * @deprecated Since 5.86, Use KPluginMetaData/KPluginFactory or QPluginloader instead
158  */
159  template<class T>
160  KSERVICE_DEPRECATED_VERSION(5, 86, "Use KPluginMetaData/KPluginFactory or QPluginloader instead")
161  static T *createInstanceFromQuery(const QString &serviceType,
162  const QString &constraint = QString(),
163  QObject *parent = nullptr,
164  const QVariantList &args = QVariantList(),
165  QString *error = nullptr)
166  {
167  return createInstanceFromQuery<T>(serviceType, nullptr, parent, constraint, args, error);
168  }
169 #endif
170 #endif
171 
172 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 86)
173 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 86)
174  /**
175  * Get a plugin from a trader query
176  *
177  * This method works like
178  * createInstanceFromQuery(const QString&, const QString&, QObject*, const QVariantList&, QString*),
179  * but you can specify an additional parent widget. This is important for
180  * a KPart, for example.
181  *
182  * @param serviceType the type of service for which to find a plugin
183  * @param parentWidget the parent widget for the plugin
184  * @param parent the parent object for the part itself
185  * @param constraint an optional constraint to pass to the trader (see KTrader)
186  * @param args A list of arguments passed to the service component
187  * @param error The string passed here will contain an error description.
188  * @return A pointer to the newly created object or a null pointer if the
189  * factory was unable to create an object of the given type.
190  *
191  * @see KPluginFactory::instantiatePlugin
192  * @deprecated Since 5.86, Use KPluginMetaData/KPluginFactory or QPluginloader instead
193  */
194  template<class T>
195  KSERVICE_DEPRECATED_VERSION(5, 86, "Use KPluginMetaData/KPluginFactory or QPluginloader instead")
196  static T *createInstanceFromQuery(const QString &serviceType,
197  QWidget *parentWidget,
198  QObject *parent,
199  const QString &constraint = QString(),
200  const QVariantList &args = QVariantList(),
201  QString *error = nullptr)
202  {
203  const KService::List offers = self()->query(serviceType, constraint);
204  if (error) {
205  error->clear();
206  }
207  for (const KService::Ptr &ptr : offers) {
208  T *component = ptr->template createInstance<T>(parentWidget, parent, args, error);
209  if (component) {
210  return component;
211  }
212  }
213  if (error && error->isEmpty()) {
214  *error = QCoreApplication::translate("", "No service matching the requirements was found");
215  }
216  return nullptr;
217  }
218 #endif
219 #endif
220 
221  /**
222  * @internal (public for KMimeTypeTrader)
223  */
224  static void applyConstraints(KService::List &lst, const QString &constraint);
225 
226 private:
227  /**
228  * @internal
229  */
231 
232  // disallow copy ctor and assignment operator
234  KServiceTypeTrader &operator=(const KServiceTypeTrader &rhs);
235 
236  static KServiceOfferList weightedOffers(const QString &serviceType);
237 
238  KServiceTypeTraderPrivate *const d;
239 
240  friend class KServiceTypeTraderSingleton;
241 };
242 
243 #endif
244 #endif
QString translate(const char *context, const char *sourceText, const char *disambiguation, int n)
Holds the user's preference of a service.
Definition: kserviceoffer.h:30
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Oct 6 2022 04:22:16 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.