Warning: That file was not part of the compilation database. It may have many parsing errors.

1/* This file is part of the KDE project
2 Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>
3 Copyright 1999-2006 David Faure <faure@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KSERVICE_H
22#define KSERVICE_H
23
24#include "kserviceaction.h"
25#include <QtCore/QStringList>
26#include <QtCore/QVariant>
27#ifndef KDE_NO_DEPRECATED
28#include <klibloader.h>
29#endif
30#include <kpluginfactory.h>
31#include <kpluginloader.h>
32#include <ksycocaentry.h>
33#include <klocale.h>
34
35class KServiceType;
36class QDataStream;
37class KDesktopFile;
38class QWidget;
39
40class KServicePrivate;
41
42/**
43 * Represent a service, like an application or plugin
44 * bound to one or several mimetypes (or servicetypes) as written
45 * in its desktop entry file.
46 *
47 * The starting point you need is often the static methods, like createInstance().
48 * The types of service a plugin provides is taken from the accompanying desktop file
49 * where the 'ServiceTypes=' field is used.
50 *
51 * For a tutorial on how to build a plugin-loading mechanism and how to write plugins
52 * in general, see http://techbase.kde.org/Development/Tutorials#Services:_Applications_and_Plugins
53 *
54 * @see KServiceType
55 * @see KServiceGroup
56 * @author Torben Weis
57 */
58class KDECORE_EXPORT KService : public KSycocaEntry // TODO KDE5: inherit kshared, but move KSycocaEntry to Private
59{
60public:
61 typedef KSharedPtr<KService> Ptr;
62 typedef QList<Ptr> List;
63
64 /**
65 * Construct a temporary service with a given name, exec-line and icon.
66 * @param name the name of the service
67 * @param exec the executable
68 * @param icon the name of the icon
69 */
70 KService(const QString & name, const QString &exec, const QString &icon);
71
72 /**
73 * Construct a service and take all information from a config file.
74 *
75 * @param fullpath Full path to the config file.
76 */
77 explicit KService( const QString & fullpath );
78
79 /**
80 * Construct a service and take all information from a desktop file.
81 * @param config the desktop file to read
82 */
83 explicit KService( const KDesktopFile *config );
84
85 /**
86 * @internal
87 * Construct a service from a stream.
88 * The stream must already be positionned at the correct offset.
89 */
90 KService( QDataStream& str, int offset );
91
92 virtual ~KService();
93
94 /**
95 * Services are either applications (executables) or dlopened libraries (plugins).
96 * @return true if this service is an application, i.e. it has Type=Application in its
97 * .desktop file and exec() will not be empty.
98 */
99 bool isApplication() const;
100
101 /**
102 * Returns the type of the service.
103 * @return the type of the service ("Application" or "Service")
104 * @deprecated use isApplication()
105 */
106#ifndef KDE_NO_DEPRECATED
107 KDE_DEPRECATED QString type() const;
108#endif
109
110 /**
111 * Returns the executable.
112 * @return the command that the service executes,
113 * or QString() if not set
114 */
115 QString exec() const;
116 /**
117 * Returns the name of the service's library.
118 * @return the name of the library that contains the service's
119 * implementation, or QString() if not set
120 */
121 QString library() const;
122
123 /**
124 * Returns the name of the icon.
125 * @return the icon associated with the service,
126 * or QString() if not set
127 */
128 QString icon() const;
129 /**
130 * Checks whethe the service should be run in a terminal.
131 * @return true if the service is to be run in a terminal.
132 */
133 bool terminal() const;
134
135 /**
136 * Returns any options associated with the terminal the service
137 * runs in, if it requires a terminal.
138 *
139 * The service must be a tty-oriented program.
140 * @return the terminal options,
141 * or QString() if not set
142 */
143 QString terminalOptions() const;
144 /**
145 * Checks whether the service runs with a different user id.
146 * @return true if the service has to be run under a different uid.
147 * @see username()
148 */
149 bool substituteUid() const;
150 /**
151 * Returns the user name, if the service runs with a
152 * different user id.
153 * @return the username under which the service has to be run,
154 * or QString() if not set
155 * @see substituteUid()
156 */
157 QString username() const;
158
159 /**
160 * Returns the path to the location where the service desktop entry
161 * is stored.
162 *
163 * This is a relative path if the desktop entry was found in any
164 * of the locations pointed to by $KDEDIRS (e.g. "Internet/kppp.desktop")
165 * It is a full path if the desktop entry originates from another
166 * location.
167 *
168 * @deprecated use entryPath() instead
169 *
170 * @return the path of the service's desktop file,
171 * or QString() if not set
172 */
173#ifndef KDE_NO_DEPRECATED
174 KDE_DEPRECATED QString desktopEntryPath() const;
175#endif
176
177 /**
178 * Returns the filename of the service desktop entry without any
179 * extension. E.g. "kppp"
180 * @return the name of the desktop entry without path or extension,
181 * or QString() if not set
182 */
183 QString desktopEntryName() const;
184
185 /**
186 * Returns the menu ID of the service desktop entry.
187 * The menu ID is used to add or remove the entry to a menu.
188 * @return the menu ID
189 */
190 QString menuId() const;
191
192 /**
193 * Returns a normalized ID suitable for storing in configuration files.
194 * It will be based on the menu-id when available and otherwise falls
195 * back to entryPath()
196 * @return the storage ID
197 */
198 QString storageId() const;
199
200 /**
201 * Describes the DBUS Startup type of the service.
202 * @li None - This service has no DBUS support
203 * @li Unique - This service provides a unique DBUS service.
204 * The service name is equal to the desktopEntryName.
205 * @li Multi - This service provides a DBUS service which can be run
206 * with multiple instances in parallel. The service name of
207 * an instance is equal to the desktopEntryName + "-" +
208 * the PID of the process.
209 * @li Wait - This service has no DBUS support, the launcher will wait
210 * till it is finished.
211 */
212 enum DBusStartupType { DBusNone = 0, DBusUnique, DBusMulti, DBusWait };
213
214 /**
215 * Returns the DBUSStartupType supported by this service.
216 * @return the DBUSStartupType supported by this service
217 */
218 DBusStartupType dbusStartupType() const;
219
220 /**
221 * Returns the working directory to run the program in.
222 * @return the working directory to run the program in,
223 * or QString() if not set
224 */
225 QString path() const;
226
227 /**
228 * Returns the descriptive comment for the service, if there is one.
229 * @return the descriptive comment for the service, or QString()
230 * if not set
231 */
232 QString comment() const;
233
234 /**
235 * Returns the generic name for the service, if there is one
236 * (e.g. "Mail Client").
237 * @return the generic name,
238 * or QString() if not set
239 */
240 QString genericName() const;
241
242 /**
243 * Returns the untranslated (US English) generic name
244 * for the service, if there is one
245 * (e.g. "Mail Client").
246 * @return the generic name,
247 * or QString() if not set
248 */
249 QString untranslatedGenericName() const;
250
251 /**
252 * Returns a list of descriptive keywords the service, if there are any.
253 * @return the list of keywords
254 */
255 QStringList keywords() const;
256
257 /**
258 * Returns a list of VFolder categories.
259 * @return the list of VFolder categories
260 */
261 QStringList categories() const;
262
263 /**
264 * Returns the list of mime types that this service supports.
265 * Note that this doesn't include inherited mimetypes,
266 * only the mimetypes types listed in the .desktop file.
267 * @since 4.8.3
268 */
269 QStringList mimeTypes() const;
270
271 /**
272 * Returns the service types that this service supports.
273 * @return the list of service types that are supported
274 * Note that this doesn't include inherited servicetypes or mimetypes,
275 * only the service types listed in the .desktop file.
276 */
277 QStringList serviceTypes() const;
278
279 /**
280 * Checks whether the service supports this service type
281 * @param serviceTypePtr The name of the service type you are
282 * interested in determining whether this service supports.
283 *
284 * @return true if the service type you specified is supported, otherwise false.
285 */
286 bool hasServiceType( const QString& serviceTypePtr ) const;
287
288 /**
289 * Checks whether the service supports this mime type
290 * @param mimeTypePtr The name of the mime type you are
291 * interested in determining whether this service supports.
292 *
293 * Note that if you only have the name of the mime type, you have to look it up
294 * with KMimeType::mimeType( mimetype ) and use .data() on the result (this is
295 * because KService doesn't know KMimeType for dependency reasons)
296 *
297 * Warning this method will fail to return true if this KService isn't from ksycoca
298 * (i.e. it was created with a full path or a KDesktopFile) *and* the mimetype
299 * isn't explicited listed in the .desktop file but a parent mimetype is.
300 * For this reason you should generally get KServices with KMimeTypeTrader
301 * or one of the KService::serviceBy methods.
302 *
303 * @return true if the mime type you specified is supported, otherwise false.
304 * @deprecated, use hasMimeType(QString)
305 */
306#ifndef KDE_NO_DEPRECATED
307 KDE_DEPRECATED bool hasMimeType( const KServiceType* mimeTypePtr ) const;
308#endif
309
310 /**
311 * Checks whether the service supports this mime type
312 * @param mimeType The name of the mime type you are
313 * interested in determining whether this service supports.
314 * @since 4.6
315 */
316 bool hasMimeType( const QString& mimeType ) const;
317
318 /**
319 * Set to true if it is allowed to use this service as the default (main)
320 * action for the files it supports (e.g. Left Click in a file manager, or KRun in general).
321 *
322 * If not, then this service is only available in RMB popups, so it must
323 * be selected explicitly by the user in order to be used.
324 * Note that servicemenus supersede this functionality though, at least in konqueror.
325 *
326 * @return true if the service may be used as the default (main) handler
327 */
328 bool allowAsDefault() const;
329
330 /**
331 * Returns the actions defined in this desktop file
332 */
333 QList<KServiceAction> actions() const;
334
335 /**
336 * Checks whether this service can handle several files as
337 * startup arguments.
338 * @return true if multiple files may be passed to this service at
339 * startup. False if only one file at a time may be passed.
340 */
341 bool allowMultipleFiles() const;
342
343 /**
344 * What preference to associate with this service initially (before
345 * the user has had any chance to define a profile for it).
346 * The bigger the value, the most preferred the service is.
347 * @return the service preference level of the service
348 */
349 int initialPreference() const;
350
351 /**
352 * Whether the entry should be suppressed in the K menu.
353 * @return true to suppress this service
354 *
355 * Such services still appear in trader queries, i.e. in
356 * "Open With" popup menus for instance.
357 */
358 bool noDisplay() const;
359
360 /**
361 * Whether the service should be shown in KDE at all
362 * (including in context menus).
363 * @return true if the service should be shown.
364 *
365 * KMimeTypeTrader honors this and removes such services
366 * from its results.
367 *
368 * @since 4.5
369 */
370 bool showInKDE() const;
371
372 /**
373 * Name of the application this service belongs to.
374 * (Useful for e.g. plugins)
375 * @return the parent application, or QString() if not set
376 */
377 QString parentApp() const;
378
379 /**
380 * The keyword to be used when constructing the plugin using KPluginFactory. The keyword is
381 * defined with X-KDE-PluginKeyword in the .desktop file and with K_REGISTER_PLUGIN_WITH_KEYWORD
382 * when implementing the plugin.
383 */
384 QString pluginKeyword() const;
385
386 /**
387 * The path to the documentation for this service.
388 * @since 4.2
389 * @return the documentation path, or QString() if not set
390 */
391 QString docPath() const;
392
393 /**
394 * Returns the requested property.
395 *
396 * @param _name the name of the property
397 * @param t the assumed type of the property
398 * @return the property, or invalid if not found
399 * @see KServiceType
400 */
401 QVariant property( const QString& _name, QVariant::Type t ) const;
402
403 using KSycocaEntry::property;
404
405 /**
406 * Returns a path that can be used for saving changes to this
407 * service
408 * @return path that can be used for saving changes to this service
409 */
410 QString locateLocal() const;
411
412 /**
413 * @internal
414 * Set the menu id
415 */
416 void setMenuId(const QString &menuId);
417 /**
418 * @internal
419 * Sets whether to use a terminal or not
420 */
421 void setTerminal(bool b);
422 /**
423 * @internal
424 * Sets the terminal options to use
425 */
426 void setTerminalOptions(const QString &options);
427
428 /**
429 * Overrides the "Exec=" line of the service.
430 *
431 * If @ref exec is not empty, its value will override the one
432 * the one set when this service was created.
433 *
434 * Please note that @ref entryPath is also cleared so the service
435 * will no longer be associated with a specific config file.
436 *
437 * @internal
438 * @since 4.11
439 */
440 void setExec(const QString& exec);
441
442 /**
443 * Find a service by name, i.e. the translated Name field. Don't use this.
444 * Use serviceByDesktopPath or serviceByStorageId instead.
445 *
446 * @param _name the name to search
447 * @return a pointer to the requested service or 0 if the service is
448 * unknown.
449 * @em Very @em important: Don't store the result in a KService* !
450 * @deprecated there is never a good reason to use this method.
451 */
452#ifndef KDE_NO_DEPRECATED
453 static Ptr serviceByName( const QString& _name ); // KDE5: remove
454#endif
455
456 /**
457 * Find a service based on its path as returned by entryPath().
458 * It's usually better to use serviceByStorageId() instead.
459 *
460 * @param _path the path of the configuration file
461 * @return a pointer to the requested service or 0 if the service is
462 * unknown.
463 * @em Very @em important: Don't store the result in a KService* !
464 */
465 static Ptr serviceByDesktopPath( const QString& _path );
466
467 /**
468 * Find a service by the name of its desktop file, not depending on
469 * its actual location (as long as it's under the applnk or service
470 * directories). For instance "konqbrowser" or "kcookiejar". Note that
471 * the ".desktop" extension is implicit.
472 *
473 * This is the recommended method (safe even if the user moves stuff)
474 * but note that it assumes that no two entries have the same filename.
475 *
476 * @param _name the name of the configuration file
477 * @return a pointer to the requested service or 0 if the service is
478 * unknown.
479 * @em Very @em important: Don't store the result in a KService* !
480 */
481 static Ptr serviceByDesktopName( const QString& _name );
482
483 /**
484 * Find a service by its menu-id
485 *
486 * @param _menuId the menu id of the service
487 * @return a pointer to the requested service or 0 if the service is
488 * unknown.
489 * @em Very @em important: Don't store the result in a KService* !
490 */
491 static Ptr serviceByMenuId( const QString& _menuId );
492
493 /**
494 * Find a service by its storage-id or desktop-file path. This
495 * function will try very hard to find a matching service.
496 *
497 * @param _storageId the storage id or desktop-file path of the service
498 * @return a pointer to the requested service or 0 if the service is
499 * unknown.
500 * @em Very @em important: Don't store the result in a KService* !
501 */
502 static Ptr serviceByStorageId( const QString& _storageId );
503
504 /**
505 * Returns the whole list of services.
506 *
507 * Useful for being able to
508 * to display them in a list box, for example.
509 * More memory consuming than the ones above, don't use unless
510 * really necessary.
511 * @return the list of all services
512 */
513 static List allServices();
514
515 /**
516 * Returns a path that can be used to create a new KService based
517 * on @p suggestedName.
518 * @param showInMenu true, if the service should be shown in the KDE menu
519 * false, if the service should be hidden from the menu
520 * This argument isn't used anymore, use NoDisplay=true to hide the service.
521 * @param suggestedName name to base the file on, if a service with such
522 * name already exists, a prefix will be added to make it unique.
523 * @param menuId If provided, menuId will be set to the menu id to use for
524 * the KService
525 * @param reservedMenuIds If provided, the path and menu id will be chosen
526 * in such a way that the new menu id does not conflict with any
527 * of the reservedMenuIds
528 * @return The path to use for the new KService.
529 */
530 static QString newServicePath(bool showInMenu, const QString &suggestedName,
531 QString *menuId = 0,
532 const QStringList *reservedMenuIds = 0);
533
534 /**
535 * This template allows to load the library for the specified service and ask the
536 * factory to create an instance of the given template type.
537 *
538 * @param parent The parent object (see QObject constructor)
539 * @param args A list of arguments, passed to the factory and possibly
540 * to the component (see KPluginFactory)
541 * @param error A pointer to QString which should receive the error description or 0
542 *
543 * @return A pointer to the newly created object or a null pointer if the
544 * factory was unable to create an object of the given type.
545 */
546 template <class T>
547 T *createInstance(QObject *parent = 0,
548 const QVariantList &args = QVariantList(), QString *error = 0) const
549 {
550 return createInstance<T>(0, parent, args, error);
551 }
552
553 /**
554 * This template allows to load the library for the specified service and ask the
555 * factory to create an instance of the given template type.
556 *
557 * @param parentWidget A parent widget for the service. This is used e. g. for parts
558 * @param parent The parent object (see QObject constructor)
559 * @param args A list of arguments, passed to the factory and possibly
560 * to the component (see KPluginFactory)
561 * @param error A pointer to QString which should receive the error description or 0
562 *
563 * @return A pointer to the newly created object or a null pointer if the
564 * factory was unable to create an object of the given type.
565 */
566 template <class T>
567 T *createInstance(QWidget *parentWidget, QObject *parent,
568 const QVariantList &args = QVariantList(), QString *error = 0) const
569 {
570 KPluginLoader pluginLoader(*this);
571 KPluginFactory *factory = pluginLoader.factory();
572 if (factory) {
573 T *o = factory->template create<T>(parentWidget, parent, pluginKeyword(), args);
574 if (!o && error)
575 *error = i18n("The service '%1' does not provide an interface '%2' with keyword '%3'",
576 name(), QString::fromLatin1(T::staticMetaObject.className()), pluginKeyword());
577 return o;
578 }
579 else if (error) {
580 *error = pluginLoader.errorString();
581 pluginLoader.unload();
582 }
583 return 0;
584 }
585
586 /**
587 * @deprecated Use the non-static service->createInstance<T>(parent, args, &error)
588 */
589#ifndef KDE_NO_DEPRECATED
590 template <class T>
591 static KDE_DEPRECATED T *createInstance(const KService::Ptr &service, QObject *parent = 0,
592 const QVariantList &args = QVariantList(), QString *error = 0)
593 {
594 return service->createInstance<T>(parent, args, error);
595 }
596#endif
597
598 /**
599 * @deprecated Use the non-static service->createInstance<T>(parent, args, &error)
600 * where args is a QVariantList rather than a QStringList
601 */
602#ifndef KDE_NO_DEPRECATED
603 template <class T>
604 static KDE_DEPRECATED T *createInstance( const KService::Ptr &service,
605 QObject *parent,
606 const QStringList &args,
607 int *error = 0 )
608 {
609 const QString library = service->library();
610 if ( library.isEmpty() ) {
611 if ( error )
612 *error = KLibLoader::ErrServiceProvidesNoLibrary;
613 return 0;
614 }
615
616 return KLibLoader::createInstance<T>( library, parent, args, error );
617 }
618#endif
619
620 /**
621 * This template allows to create a component from a list of services,
622 * usually coming from a trader query. You probably want to use KServiceTypeTrader instead.
623 *
624 * @deprecated Use KServiceTypeTrader::createInstanceFromQuery instead
625 *
626 * @param begin The start iterator to the service describing the library to open
627 * @param end The end iterator to the service describing the library to open
628 * @param parent The parent object (see QObject constructor)
629 * @param args A list of string arguments, passed to the factory and possibly
630 * to the component (see KLibFactory)
631 * @param error see KLibLoader
632 * @return A pointer to the newly created object or a null pointer if the
633 * factory was unable to create an object of the given type.
634 */
635#ifndef KDE_NO_DEPRECATED
636 template <class T, class ServiceIterator>
637 static KDE_DEPRECATED T *createInstance(ServiceIterator begin, ServiceIterator end, QObject *parent = 0,
638 const QVariantList &args = QVariantList(), QString *error = 0)
639 {
640 for (; begin != end; ++begin) {
641 KService::Ptr service = *begin;
642 if (error) {
643 error->clear();
644 }
645
646 T *component = createInstance<T>(service, parent, args, error);
647 if (component) {
648 return component;
649 }
650 }
651 if (error) {
652 *error = KLibLoader::errorString(KLibLoader::ErrNoServiceFound);
653 }
654 return 0;
655 }
656#endif
657
658#ifndef KDE_NO_DEPRECATED
659 template <class T, class ServiceIterator>
660 static KDE_DEPRECATED T *createInstance( ServiceIterator begin, ServiceIterator end,
661 QObject *parent,
662 const QStringList &args,
663 int *error = 0 )
664 {
665 for (; begin != end; ++begin ) {
666 KService::Ptr service = *begin;
667 if ( error )
668 *error = 0;
669
670 T *component = createInstance<T>( service, parent, args, error );
671 if ( component )
672 return component;
673 }
674 if ( error )
675 *error = KLibLoader::ErrNoServiceFound;
676 return 0;
677 }
678#endif
679
680protected:
681 friend class KMimeAssociations;
682 friend class KBuildServiceFactory;
683
684 /// @internal for KBuildSycoca only
685 struct ServiceTypeAndPreference
686 {
687 ServiceTypeAndPreference()
688 : preference(-1), serviceType() {}
689 ServiceTypeAndPreference(int pref, const QString& servType)
690 : preference(pref), serviceType(servType) {}
691 int preference;
692 QString serviceType; // or mimetype
693 };
694 /// @internal for KBuildSycoca only
695 QVector<ServiceTypeAndPreference>& _k_accessServiceTypes();
696
697 friend QDataStream& operator>>( QDataStream&, ServiceTypeAndPreference& );
698 friend QDataStream& operator<<( QDataStream&, const ServiceTypeAndPreference& );
699private:
700 Q_DECLARE_PRIVATE(KService)
701};
702#endif
703

Warning: That file was not part of the compilation database. It may have many parsing errors.