File indexing completed on 2024-07-21 12:13:32

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000 Torben Weis <weis@kde.org>
0004     SPDX-FileCopyrightText: 2006 David Faure <faure@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-only
0007 */
0008 
0009 #ifndef __kservicetypetrader_h__
0010 #define __kservicetypetrader_h__
0011 
0012 #include "kservice.h"
0013 
0014 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 90)
0015 
0016 class KServiceOffer;
0017 typedef QList<KServiceOffer> KServiceOfferList;
0018 class KServiceTypeTraderPrivate;
0019 /**
0020  * @class KServiceTypeTrader kservicetypetrader.h <KServiceTypeTrader>
0021  *
0022  * KDE's trader interface (similar to the CORBA Trader), which provides a way
0023  * to query the KDE infrastructure for specific applications or components.
0024  *
0025  * Basically, KServiceTypeTrader provides a way for an application to query
0026  * all KDE services (that is, applications, components, plugins) that match
0027  * a specific set of requirements. This allows to find specific services
0028  * at run-time without having to hard-code their names and/or paths.
0029  *
0030  * For anything relating to MIME types (type of files), ignore KServiceTypeTrader
0031  * and use KMimeTypeTrader instead.
0032  *
0033  * \par Example
0034  *
0035  * If you want to find all plugins for your application,
0036  * you would define a KMyApp/Plugin servicetype, and then you can query
0037  * the trader for it:
0038  * \code
0039  * KService::List offers =
0040  *     KServiceTypeTrader::self()->query("KMyApp/Plugin");
0041  * \endcode
0042  *
0043  * You can add a constraint in the "trader query language". For instance:
0044  * \code
0045  * KServiceTypeTrader::self()->query("KMyApp/Plugin",
0046  *                                   "[X-KMyApp-InterfaceVersion] > 15");
0047  * \endcode
0048  *
0049  * Please note that when including property names containing arithmetic operators like - or +, then you have
0050  * to put brackets around the property name, in order to correctly separate arithmetic operations from
0051  * the name. So for example a constraint expression like
0052  * \code
0053  * X-KMyApp-InterfaceVersion > 4 // wrong!
0054  * \endcode
0055  * needs to be written as
0056  * \code
0057  * [X-KMyApp-InterfaceVersion] > 4
0058  * \endcode
0059  * otherwise it could also be interpreted as
0060  * Subtract the numeric value of the property "KMyApp" and "InterfaceVersion" from the
0061  * property "X" and make sure it is greater than 4.
0062  * Instead of the other meaning, make sure that the numeric value of "X-KMyApp-InterfaceVersion" is
0063  * greater than 4.
0064  *
0065  * @see KMimeTypeTrader, KService
0066  * @deprecated Since 5.90.
0067  * For querying plugins use @p KPluginMetaData::findPlugins.
0068  * For querying applications use @p KApplicationTrader.
0069  * For querying KParts use @p KParts::PartLoader.
0070  * For querying desktop files use @p KFileUtils::findAllUniqueFiles and @p KDesktopFile.
0071  */
0072 class KSERVICE_EXPORT KServiceTypeTrader
0073 {
0074 public:
0075     /**
0076      * Standard destructor
0077      */
0078     ~KServiceTypeTrader();
0079 
0080     /**
0081      * The main function in the KServiceTypeTrader class.
0082      *
0083      * It will return a list of services that match your
0084      * specifications.  The only required parameter is the service
0085      * type.  This is something like 'text/plain' or 'text/html'.  The
0086      * constraint parameter is used to limit the possible choices
0087      * returned based on the constraints you give it.
0088      *
0089      * The @p constraint language is rather full.  The most common
0090      * keywords are AND, OR, NOT, IN, and EXIST, all used in an
0091      * almost spoken-word form.  An example is:
0092      * \code
0093      * (Type == 'Service') and (('KParts/ReadOnlyPart' in ServiceTypes) or (exist Exec))
0094      * \endcode
0095      *
0096      * The keys used in the query (Type, ServiceType, Exec) are all
0097      * fields found in the .desktop files.
0098      *
0099      * @param servicetype A service type like 'KMyApp/Plugin' or 'KFilePlugin'.
0100      * @param constraint  A constraint to limit the choices returned, QString() to
0101      *                    get all services of the given @p servicetype
0102      *
0103      * @return A list of services that satisfy the query
0104      * @see http://techbase.kde.org/Development/Tutorials/Services/Traders#The_KTrader_Query_Language
0105      */
0106     KService::List query(const QString &servicetype, const QString &constraint = QString()) const;
0107 
0108     /**
0109      * Returns all offers associated with a given servicetype, IGNORING the
0110      * user preference. The sorting will be the one coming from the InitialPreference
0111      * in the .desktop files, and services disabled by the user will still be listed here.
0112      * This is used for "Revert to defaults" buttons in GUIs.
0113      */
0114     KService::List defaultOffers(const QString &serviceType, const QString &constraint = QString()) const;
0115     /**
0116      * Returns the preferred service for @p serviceType.
0117      *
0118      * @param serviceType the service type (e.g. "KMyApp/Plugin")
0119      * @return the preferred service, or @c nullptr if no service is available
0120      */
0121     KService::Ptr preferredService(const QString &serviceType) const;
0122 
0123     /**
0124      * This is a static pointer to the KServiceTypeTrader singleton.
0125      *
0126      * You will need to use this to access the KServiceTypeTrader functionality since the
0127      * constructors are protected.
0128      *
0129      * @return Static KServiceTypeTrader instance
0130      * @deprecated Since 5.90, see class API docs
0131      */
0132     KSERVICE_DEPRECATED_VERSION(5, 90, "See class API docs")
0133     static KServiceTypeTrader *self();
0134 
0135 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 86)
0136 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 86)
0137     /**
0138      * Get a plugin from a trader query
0139      *
0140      * Example:
0141      * \code
0142      * KMyAppPlugin* plugin = KServiceTypeTrader::createInstanceFromQuery<KMyAppPlugin>( serviceType, QString(), parentObject );
0143      * if ( plugin ) {
0144      *     ....
0145      * }
0146      * \endcode
0147      *
0148      * @param serviceType the type of service for which to find a plugin
0149      * @param constraint an optional constraint to pass to the trader (see KTrader)
0150      * @param parent the parent object for the part itself
0151      * @param args A list of arguments passed to the service component
0152      * @param error The string passed here will contain an error description.
0153      * @return A pointer to the newly created object or a null pointer if the
0154      *         factory was unable to create an object of the given type.
0155      *
0156      * @see KPluginFactory::instantiatePlugin
0157      * @deprecated Since 5.86, Use KPluginMetaData/KPluginFactory or QPluginloader instead
0158      */
0159     template<class T>
0160     KSERVICE_DEPRECATED_VERSION(5, 86, "Use KPluginMetaData/KPluginFactory or QPluginloader instead")
0161     static T *createInstanceFromQuery(const QString &serviceType,
0162                                       const QString &constraint = QString(),
0163                                       QObject *parent = nullptr,
0164                                       const QVariantList &args = QVariantList(),
0165                                       QString *error = nullptr)
0166     {
0167         return createInstanceFromQuery<T>(serviceType, nullptr, parent, constraint, args, error);
0168     }
0169 #endif
0170 #endif
0171 
0172 #if KSERVICE_ENABLE_DEPRECATED_SINCE(5, 86)
0173 #if KCOREADDONS_ENABLE_DEPRECATED_SINCE(5, 86)
0174     /**
0175      * Get a plugin from a trader query
0176      *
0177      * This method works like
0178      * createInstanceFromQuery(const QString&, const QString&, QObject*, const QVariantList&, QString*),
0179      * but you can specify an additional parent widget.  This is important for
0180      * a KPart, for example.
0181      *
0182      * @param serviceType the type of service for which to find a plugin
0183      * @param parentWidget the parent widget for the plugin
0184      * @param parent the parent object for the part itself
0185      * @param constraint an optional constraint to pass to the trader (see KTrader)
0186      * @param args A list of arguments passed to the service component
0187      * @param error The string passed here will contain an error description.
0188      * @return A pointer to the newly created object or a null pointer if the
0189      *         factory was unable to create an object of the given type.
0190      *
0191      * @see KPluginFactory::instantiatePlugin
0192      * @deprecated Since 5.86, Use KPluginMetaData/KPluginFactory or QPluginloader instead
0193      */
0194     template<class T>
0195     KSERVICE_DEPRECATED_VERSION(5, 86, "Use KPluginMetaData/KPluginFactory or QPluginloader instead")
0196     static T *createInstanceFromQuery(const QString &serviceType,
0197                                       QWidget *parentWidget,
0198                                       QObject *parent,
0199                                       const QString &constraint = QString(),
0200                                       const QVariantList &args = QVariantList(),
0201                                       QString *error = nullptr)
0202     {
0203         const KService::List offers = self()->query(serviceType, constraint);
0204         if (error) {
0205             error->clear();
0206         }
0207         for (const KService::Ptr &ptr : offers) {
0208             T *component = ptr->template createInstance<T>(parentWidget, parent, args, error);
0209             if (component) {
0210                 return component;
0211             }
0212         }
0213         if (error && error->isEmpty()) {
0214             *error = QCoreApplication::translate("", "No service matching the requirements was found");
0215         }
0216         return nullptr;
0217     }
0218 #endif
0219 #endif
0220 
0221     /**
0222      * @internal  (public for KMimeTypeTrader)
0223      */
0224     static void applyConstraints(KService::List &lst, const QString &constraint);
0225 
0226 private:
0227     /**
0228      * @internal
0229      */
0230     KServiceTypeTrader();
0231 
0232     // disallow copy ctor and assignment operator
0233     KServiceTypeTrader(const KServiceTypeTrader &other);
0234     KServiceTypeTrader &operator=(const KServiceTypeTrader &rhs);
0235 
0236     static KServiceOfferList weightedOffers(const QString &serviceType);
0237 
0238     KServiceTypeTraderPrivate *const d;
0239 
0240     friend class KServiceTypeTraderSingleton;
0241 };
0242 
0243 #endif
0244 #endif