File indexing completed on 2024-06-23 07:29:18

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 1998, 1999 Torben Weis <weis@kde.org>
0004     SPDX-FileCopyrightText: 1999-2006 David Faure <faure@kde.org>
0005     SPDX-FileCopyrightText: 2022 Harald Sitter <sitter@kde.org>
0006 
0007     SPDX-License-Identifier: LGPL-2.0-or-later
0008 */
0009 
0010 #ifndef KSERVICE_H
0011 #define KSERVICE_H
0012 
0013 #include "kserviceaction.h"
0014 #include <QCoreApplication>
0015 #include <QStringList>
0016 #include <QVariant>
0017 #include <kserviceconversioncheck_p.h>
0018 #include <ksycocaentry.h>
0019 
0020 #include <optional>
0021 
0022 class QDataStream;
0023 class KDesktopFile;
0024 class QWidget;
0025 
0026 class KServicePrivate;
0027 
0028 /**
0029  * @class KService kservice.h <KService>
0030  *
0031  * Represents an installed application.
0032  *
0033  * To obtain a KService instance for a specific application you typically use serviceByDesktopName(), e.g.:
0034  *
0035  * @code
0036  * KService::Ptr service = KService::serviceByDesktopName("org.kde.kate");
0037  * @endcode
0038  *
0039  * Other typical usage would be in combination with KApplicationTrader to obtain e.g. the default application for a given file type.
0040  *
0041  * @see <a href="https://specifications.freedesktop.org/desktop-entry-spec/latest/">Desktop Entry Specification</a>
0042  */
0043 class KSERVICE_EXPORT KService : public KSycocaEntry
0044 {
0045 public:
0046     /**
0047      * A shared data pointer for KService.
0048      */
0049     typedef QExplicitlySharedDataPointer<KService> Ptr;
0050     /**
0051      * A list of shared data pointers for KService.
0052      */
0053     typedef QList<Ptr> List;
0054 
0055     /**
0056      * Construct a temporary service with a given name, exec-line and icon.
0057      * @param name the name of the service
0058      * @param exec the executable
0059      * @param icon the name of the icon
0060      */
0061     KService(const QString &name, const QString &exec, const QString &icon);
0062 
0063     /**
0064      * Construct a service and take all information from a .desktop file.
0065      *
0066      * @param fullpath Full path to the .desktop file.
0067      */
0068     explicit KService(const QString &fullpath);
0069 
0070     /**
0071      * Construct a service and take all information from a desktop file.
0072      * @param config the desktop file to read
0073      * @param optional relative path to store for findByName
0074      */
0075     explicit KService(const KDesktopFile *config, const QString &entryPath = QString());
0076 
0077     KService(const KService &other);
0078 
0079     ~KService() override;
0080 
0081     /**
0082      * Whether this service is an application
0083      * @return true if this service is an application, i.e. it has Type=Application in its
0084      * .desktop file and exec() will not be empty.
0085      */
0086     bool isApplication() const;
0087 
0088     /**
0089      * Returns the executable.
0090      * @return the command that the service executes,
0091      *         or QString() if not set
0092      */
0093     QString exec() const;
0094 
0095     /**
0096      * Returns the name of the icon.
0097      * @return the icon associated with the service,
0098      *         or QString() if not set
0099      */
0100     QString icon() const;
0101     /**
0102      * Checks whether the application should be run in a terminal.
0103      *
0104      * This corresponds to `Terminal=true` in the .desktop file.
0105      *
0106      * @return @c true if the application should be run in a terminal.
0107      */
0108     bool terminal() const;
0109 
0110     /**
0111      * Returns any options associated with the terminal the application
0112      * runs in, if it requires a terminal.
0113      *
0114      * The application must be a TTY-oriented program.
0115      * @return the terminal options,
0116      *         or QString() if not set
0117      */
0118     QString terminalOptions() const;
0119 
0120     /**
0121      * Returns @c true if the application indicates that it's preferred to run
0122      * on a discrete graphics card, otherwise return @c false.
0123      *
0124      * In releases older than 5.86, this method checked for the @c X-KDE-RunOnDiscreteGpu
0125      * key in the .desktop file represented by this service; starting from 5.86 this method
0126      * now also checks for @c PrefersNonDefaultGPU key (added to the Freedesktop.org desktop
0127      * entry spec in version 1.4 of the spec).
0128      *
0129      * @since 5.30
0130      */
0131     bool runOnDiscreteGpu() const;
0132 
0133     /**
0134      * @brief Checks whether the application needs to run under a different UID.
0135      * @return @c true if the application needs to run under a different UID.
0136      * @see username()
0137      */
0138     bool substituteUid() const;
0139     /**
0140      * Returns the user name if the application runs with a
0141      * different user id.
0142      * @return the username under which the service has to be run,
0143      *         or QString() if not set
0144      * @see substituteUid()
0145      */
0146     QString username() const;
0147 
0148     /**
0149      * Returns the filename of the desktop entry without any
0150      * extension, e.g. "org.kde.kate"
0151      * @return the name of the desktop entry without path or extension,
0152      *         or QString() if not set
0153      */
0154     QString desktopEntryName() const;
0155 
0156     /**
0157      * Returns the menu ID of the application desktop entry.
0158      * The menu ID is used to add or remove the entry to a menu.
0159      * @return the menu ID
0160      */
0161     QString menuId() const;
0162 
0163     /**
0164      * Returns a normalized ID suitable for storing in configuration files.
0165      * It will be based on the menu-id when available and otherwise falls
0166      * back to entryPath()
0167      * @return the storage ID
0168      */
0169     QString storageId() const;
0170 
0171     /**
0172      * @return the working directory to run the program in,
0173      *         or QString() if not set
0174      * @since 5.63
0175      */
0176     QString workingDirectory() const;
0177 
0178     /**
0179      * Returns the descriptive comment for the application, if there is one.
0180      * @return the descriptive comment for the application, or QString()
0181      *         if not set
0182      */
0183     QString comment() const;
0184 
0185     /**
0186      * Returns the generic name for the application, if there is one
0187      * (e.g. "Mail Client").
0188      * @return the generic name,
0189      *         or QString() if not set
0190      */
0191     QString genericName() const;
0192 
0193     /**
0194      * Returns the untranslated (US English) generic name
0195      * for the application, if there is one
0196      * (e.g. "Mail Client").
0197      * @return the generic name,
0198      *         or QString() if not set
0199      */
0200     QString untranslatedGenericName() const;
0201 
0202     /**
0203      * @return untranslated name for the given service
0204      *
0205      * @since 6.0
0206      */
0207     QString untranslatedName() const;
0208     /**
0209      * Returns a list of descriptive keywords for the application, if there are any.
0210      * @return the list of keywords
0211      */
0212     QStringList keywords() const;
0213 
0214     /**
0215      * Returns a list of VFolder categories.
0216      * @return the list of VFolder categories
0217      */
0218     QStringList categories() const;
0219 
0220     /**
0221      * Returns the list of MIME types that this application supports.
0222      * Note that this doesn't include inherited MIME types,
0223      * only the MIME types listed in the .desktop file.
0224      * @since 4.8.3
0225      */
0226     QStringList mimeTypes() const;
0227 
0228     /**
0229      * Returns the list of scheme handlers this application supports.
0230      *
0231      * For example a web browser could return {"http", "https"}.
0232      *
0233      * This is taken from the x-scheme-handler MIME types
0234      * listed in the .desktop file.
0235      *
0236      * @since 6.0
0237      *
0238      */
0239     QStringList schemeHandlers() const;
0240 
0241     /**
0242      * Returns the list of protocols this application supports.
0243      *
0244      * This is taken from the x-scheme-handler MIME types
0245      * listed in the .desktop file as well as the 'X-KDE-Protocols'
0246      * entry
0247      *
0248      * For example a web browser could return {"http", "https"}.
0249      * @since 6.0
0250      */
0251     QStringList supportedProtocols() const;
0252 
0253     /**
0254      * Checks whether the application supports this MIME type
0255      * @param mimeType The name of the MIME type you are
0256      *        interested in determining whether this service supports.
0257      * @since 4.6
0258      */
0259     bool hasMimeType(const QString &mimeType) const;
0260 
0261     /**
0262      * Returns the actions defined in this desktop file
0263      */
0264     QList<KServiceAction> actions() const;
0265 
0266     /**
0267      * Checks whether this application can handle several files as
0268      * startup arguments.
0269      * @return true if multiple files may be passed to this service at
0270      * startup. False if only one file at a time may be passed.
0271      */
0272     bool allowMultipleFiles() const;
0273 
0274     /**
0275      * What preference to associate with this application initially (before
0276      * the user has had any chance to define a profile for it).
0277      * The bigger the value, the stronger the preference for the application.
0278      * @return the service preference level of the application
0279      */
0280     int initialPreference() const;
0281 
0282     /**
0283      * Whether the entry should be hidden from the menu.
0284      * @return @c true to hide this application from the menu
0285      *
0286      * Such services still appear in trader queries, i.e. in
0287      * "Open With" popup menus for instance.
0288      */
0289     bool noDisplay() const;
0290 
0291     /**
0292      * Whether the application should be shown in the current desktop
0293      * (including in context menus).
0294      * @return true if the application should be shown in the current desktop.
0295      *
0296      * KApplicationTrader honors this and removes such services
0297      * from its results.
0298      *
0299      * @since 5.0
0300      */
0301     bool showInCurrentDesktop() const;
0302 
0303     /**
0304      * Whether the application should be shown on the current
0305      * platform (e.g. on xcb or on wayland).
0306      * @return @c true if the application should be shown on the current platform.
0307      *
0308      * @since 5.0
0309      */
0310     bool showOnCurrentPlatform() const;
0311 
0312     /**
0313      * The path to the documentation for this application.
0314      * @since 4.2
0315      * @return the documentation path, or QString() if not set
0316      */
0317     QString docPath() const;
0318 
0319     /**
0320      * Returns the requested property.
0321      *
0322      * @tparam T the type of the requested property.
0323      *
0324      * @param name the name of the property.
0325      *
0326      * @since 6.0
0327      */
0328     template<typename T>
0329     T property(const QString &name) const
0330     {
0331         KServiceConversionCheck::to_QVariant<T>();
0332         return property(name, static_cast<QMetaType::Type>(qMetaTypeId<T>())).value<T>();
0333     }
0334 
0335     /**
0336      * Returns a path that can be used for saving changes to this
0337      * application
0338      * @return path that can be used for saving changes to this application
0339      */
0340     QString locateLocal() const;
0341 
0342     /**
0343      * @internal
0344      * Set the menu id
0345      */
0346     void setMenuId(const QString &menuId);
0347     /**
0348      * @internal
0349      * Sets whether to use a terminal or not
0350      */
0351     void setTerminal(bool b);
0352     /**
0353      * @internal
0354      * Sets the terminal options to use
0355      */
0356     void setTerminalOptions(const QString &options);
0357 
0358     /**
0359      * Overrides the "Exec=" line of the service.
0360      *
0361      * If @ref exec is not empty, its value will override the one
0362      * the one set when this application was created.
0363      *
0364      * Please note that @ref entryPath is also cleared so the application
0365      * will no longer be associated with a specific config file.
0366      *
0367      * @internal
0368      * @since 4.11
0369      */
0370     void setExec(const QString &exec);
0371 
0372     /**
0373      * Overrides the "Path=" line of the application.
0374      *
0375      * If @ref workingDir is not empty, its value will override
0376      * the one set when this application was created.
0377      *
0378      * Please note that @ref entryPath is also cleared so the application
0379      * will no longer be associated with a specific config file.
0380      *
0381      * @internal
0382      * @param workingDir
0383      * @since 5.79
0384      */
0385     void setWorkingDirectory(const QString &workingDir);
0386 
0387     /**
0388      * Find a application based on its path as returned by entryPath().
0389      * It's usually better to use serviceByStorageId() instead.
0390      *
0391      * @param _path the path of the configuration file
0392      * @return a pointer to the requested application or @c nullptr if the application is
0393      *         unknown.
0394      * @em Very @em important: Don't store the result in a KService* !
0395      */
0396     static Ptr serviceByDesktopPath(const QString &_path);
0397 
0398     /**
0399      * Find an application by the name of its desktop file, not depending on
0400      * its actual location (as long as it's under the applications or application
0401      * directories). For instance "konqbrowser" or "kcookiejar". Note that
0402      * the ".desktop" extension is implicit.
0403      *
0404      * This is the recommended method (safe even if the user moves stuff)
0405      * but note that it assumes that no two entries have the same filename.
0406      *
0407      * @param _name the name of the configuration file
0408      * @return a pointer to the requested application or @c nullptr if the application is
0409      *         unknown.
0410      * @em Very @em important: Don't store the result in a KService* !
0411      */
0412     static Ptr serviceByDesktopName(const QString &_name);
0413 
0414     /**
0415      * Find a application by its menu-id
0416      *
0417      * @param _menuId the menu id of the application
0418      * @return a pointer to the requested application or @c nullptr if the application is
0419      *         unknown.
0420      * @em Very @em important: Don't store the result in a KService* !
0421      */
0422     static Ptr serviceByMenuId(const QString &_menuId);
0423 
0424     /**
0425      * Find a application by its storage-id or desktop-file path. This
0426      * function will try very hard to find a matching application.
0427      *
0428      * @param _storageId the storage id or desktop-file path of the application
0429      * @return a pointer to the requested application or @c nullptr if the application is
0430      *         unknown.
0431      * @em Very @em important: Don't store the result in a KService* !
0432      */
0433     static Ptr serviceByStorageId(const QString &_storageId);
0434 
0435     /**
0436      * Returns the whole list of applications.
0437      *
0438      *  Useful for being able to
0439      * to display them in a list box, for example.
0440      * More memory consuming than the ones above, don't use unless
0441      * really necessary.
0442      * @return the list of all applications
0443      */
0444     static List allServices();
0445 
0446     /**
0447      * Returns a path that can be used to create a new KService based
0448      * on @p suggestedName.
0449      * @param showInMenu @c true, if the application should be shown in the KDE menu
0450      *        @c false, if the application should be hidden from the menu
0451      *        This argument isn't used anymore, use `NoDisplay=true` to hide the application.
0452      * @param suggestedName name to base the file on, if an application with such a
0453      *        name already exists, a suffix will be added to make it unique
0454      *        (e.g. foo.desktop, foo-1.desktop, foo-2.desktop).
0455      * @param menuId If provided, menuId will be set to the menu id to use for
0456      *        the KService
0457      * @param reservedMenuIds If provided, the path and menu id will be chosen
0458      *        in such a way that the new menu id does not conflict with any
0459      *        of the reservedMenuIds
0460      * @return The path to use for the new KService.
0461      */
0462     static QString newServicePath(bool showInMenu, const QString &suggestedName, QString *menuId = nullptr, const QStringList *reservedMenuIds = nullptr);
0463 
0464     /**
0465      * @brief A desktop file name that this application is an alias for.
0466      *
0467      * This is used when a `NoDisplay` application is used to enforce specific handling
0468      * for an application. In that case the `NoDisplay` application is an `AliasFor` another
0469      * application and be considered roughly equal to the `AliasFor` application (which should
0470      * not be `NoDisplay=true`)
0471      * For example Okular supplies a desktop file for each supported format (e.g. PDF), all
0472      * of which `NoDisplay` and it is merely there to selectively support specific file formats.
0473      * A UI may choose to display the aliased entry org.kde.okular instead of the NoDisplay entries.
0474      *
0475      * @since 5.96
0476      *
0477      * @return QString desktopName of the aliased application (excluding .desktop suffix)
0478      */
0479     QString aliasFor() const;
0480 
0481     /**
0482      * Returns the value of StartupNotify for this service.
0483      *
0484      * If the service doesn't define a value nullopt is returned.
0485      *
0486      * See StartupNotify in the <a href="https://specifications.freedesktop.org/desktop-entry-spec/latest/">Desktop Entry Specification</a>.
0487      *
0488      * @since 6.0
0489      */
0490     std::optional<bool> startupNotify() const;
0491 
0492 private:
0493     friend class KBuildServiceFactory;
0494 
0495     QVariant property(const QString &_name, QMetaType::Type t) const;
0496 
0497     /// @internal for KBuildSycoca only
0498     struct KSERVICE_NO_EXPORT ServiceTypeAndPreference {
0499         ServiceTypeAndPreference()
0500             : preference(-1)
0501             , serviceType()
0502         {
0503         }
0504         ServiceTypeAndPreference(int pref, const QString &servType)
0505             : preference(pref)
0506             , serviceType(servType)
0507         {
0508         }
0509         int preference;
0510         QString serviceType; // or MIME type
0511     };
0512     /// @internal for KBuildSycoca only
0513     QList<ServiceTypeAndPreference> _k_accessServiceTypes();
0514 
0515     void setActions(const QList<KServiceAction> &actions);
0516 
0517     friend QDataStream &operator>>(QDataStream &, ServiceTypeAndPreference &);
0518     friend QDataStream &operator<<(QDataStream &, const ServiceTypeAndPreference &);
0519 
0520     Q_DECLARE_PRIVATE(KService)
0521 
0522     friend class KServiceFactory;
0523 
0524     /**
0525      * @internal
0526      * Construct a service from a stream.
0527      * The stream must already be positioned at the correct offset.
0528      */
0529     KSERVICE_NO_EXPORT KService(QDataStream &str, int offset);
0530 };
0531 
0532 template<>
0533 KSERVICE_EXPORT QString KService::property<QString>(const QString &name) const;
0534 
0535 #endif