home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kservice.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-10-01  |  17.5 KB  |  559 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License as published by the Free Software Foundation; either
  7.    version 2 of the License, or (at your option) any later version.
  8.  
  9.    This library is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this library; see the file COPYING.LIB.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.    Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef __kservices_h__
  21. #define __kservices_h__
  22.  
  23. #include <qstringlist.h>
  24. #include <qmap.h>
  25. #include <qvariant.h>
  26. #include <kicontheme.h>
  27.  
  28. #include "ksycocaentry.h"
  29.  
  30. class QDataStream;
  31. class KDesktopFile;
  32. class KService;
  33. class KBuildSycoca;
  34. class QWidget;
  35.  
  36. /**
  37.  * Represent a service, i.e. an application bound to one or several mimetypes
  38.  * (or servicetypes) as written in its desktop entry file.
  39.  *
  40.  * A service may be a library, too.
  41.  * The starting point you need is often the static methods.
  42.  * Service types are stored as desktop files in the "service" resource..
  43.  *
  44.  * @see KServiceType
  45.  * @see KServiceGroup
  46.  * @author Torben Weis <weis@kde.org>
  47.  */
  48. class KIO_EXPORT KService : public KSycocaEntry
  49. {
  50.   K_SYCOCATYPE( KST_KService, KSycocaEntry )
  51.  
  52.   friend class KBuildSycoca;
  53.  
  54. public:
  55.   typedef KSharedPtr<KService> Ptr;
  56.   typedef QValueList<Ptr> List;
  57. public:
  58.   /**
  59.    * Construct a temporary service with a given name, exec-line and icon.
  60.    * @param _name the name of the service
  61.    * @param _exec the executable
  62.    * @param _icon the name of the icon
  63.    */
  64.   KService( const QString & _name, const QString &_exec, const QString &_icon);
  65.  
  66.   /**
  67.    * Construct a service and take all information from a config file.
  68.    *
  69.    * @param _fullpath Full path to the config file.
  70.    */
  71.   explicit KService( const QString & _fullpath );
  72.  
  73.   /**
  74.    * Construct a service and take all information from a desktop file.
  75.    * @param config the desktop file to read
  76.    */
  77.   KService( KDesktopFile *config ); // KDE-4.0: make explicit
  78.  
  79.   /**
  80.    * @internal
  81.    * Construct a service from a stream.
  82.    * The stream must already be positionned at the correct offset.
  83.    */
  84.   KService( QDataStream& _str, int offset );
  85.  
  86.   virtual ~KService();
  87.  
  88.   /**
  89.    * Returns the type of the service.
  90.    * @return the type of the service ("Application" or "Service")
  91.    */
  92.   virtual QString type() const { return m_strType; }
  93.   /**
  94.    * Returns the name of the service.
  95.    * @return the name of the service,
  96.    *         or QString::null if not set
  97.    */
  98.   virtual QString name() const { return m_strName; }
  99.   /**
  100.    * Returns the executable.
  101.    * @return the command that the service executes,
  102.    *         or QString::null if not set
  103.    */
  104.   QString exec() const { return m_strExec; }
  105.   /**
  106.    * Returns the name of the service's library.
  107.    * @return the name of the library that contains the services
  108.    *         implementation,
  109.    *         or QString::null if not set
  110.    */
  111.   QString library() const { return m_strLibrary; }
  112.   /**
  113.    * Returns the name of the init function to call (KControl modules).
  114.    * @return the name of the init function to call in this service
  115.    *         during startup of KDE. (KControl modules only),
  116.    *         or QString::null if not set
  117.    */
  118.   QString init() const { return m_strInit; }
  119.  
  120.   /**
  121.    * Returns the name of the icon.
  122.    * @return the icon associated with the service,
  123.    *         or "unknown" if not set
  124.    */
  125.   QString icon() const { return m_strIcon; }
  126.   /**
  127.    * Returns the pixmap that represents the icon.
  128.    * @return a pixmap for this service (finds and loads icon()),
  129.    *         null if not set
  130.    * @see icon()
  131.    */
  132.   QPixmap pixmap( KIcon::Group _group, int _force_size = 0, int _state = 0,
  133.                   QString * _path = 0L ) const;
  134.   /**
  135.    * Checks whethe the service should be run in a terminal.
  136.    * @return true if the service is to be run in a terminal.
  137.    */
  138.   bool terminal() const { return m_bTerminal; }
  139.   /**
  140.    * Returns any options associated with the terminal the service
  141.    * runs in, if it requires a terminal.
  142.    *
  143.    * The service must be a tty-oriented program.
  144.    * @return the terminal options,
  145.    *         or QString::null if not set
  146.    */
  147.   QString terminalOptions() const { return m_strTerminalOptions; }
  148.   /**
  149.    * Checks whether the service runs with a different user id.
  150.    * @return true if the service has to be run under a different uid.
  151.    * @see username()
  152.    */
  153.   bool substituteUid() const;
  154.   /**
  155.    * Returns the user name, if the service runs with a
  156.    * different user id.
  157.    * @return the username under which the service has to be run,
  158.    *         or QString::null if not set
  159.    * @see substututeUid()a
  160.    */
  161.   QString username() const;
  162.  
  163.   /**
  164.    * Returns the path to the location where the service desktop entry
  165.    * is stored.
  166.    *
  167.    * This is a relative path if the desktop entry was found in any
  168.    * of the locations pointed to by $KDEDIRS (e.g. "Internet/kppp.desktop")
  169.    * It is a full path if the desktop entry originates from another
  170.    * location.
  171.    * @return the path of the service's desktop file,
  172.    *         or QString::null if not set
  173.    */
  174.   QString desktopEntryPath() const { return entryPath(); }
  175.  
  176.   /**
  177.    * Returns the filename of the service desktop entry without any
  178.    * extension. E.g. "kppp"
  179.    * @return the name of the desktop entry without path or extension,
  180.    *         or QString::null if not set
  181.    */
  182.   QString desktopEntryName() const { return m_strDesktopEntryName; }
  183.  
  184.   /**
  185.    * Returns the menu ID of the service desktop entry.
  186.    * The menu ID is used to add or remove the entry to a menu.
  187.    * @return the menu ID
  188.    * @since 3.2
  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 desktopEntryPath()
  196.    * @return the storage ID
  197.    * @since 3.2
  198.    */
  199.   QString storageId() const;
  200.  
  201.   /**
  202.    * Describes the DCOP type of the service.
  203.    * @li None - This service has no DCOP support
  204.    * @li Unique - This service provides a unique DCOP service.
  205.    *              The service name is equal to the desktopEntryName.
  206.    * @li Multi - This service provides a DCOP service which can be run
  207.    *             with multiple instances in parallel. The service name of
  208.    *             an instance is equal to the desktopEntryName + "-" +
  209.    *             the PID of the process.
  210.    * @li Wait - This service has no DCOP support, the launcher will wait
  211.    *            till it is finished.
  212.    */
  213.   enum DCOPServiceType_t { DCOP_None = 0, DCOP_Unique, DCOP_Multi, DCOP_Wait };
  214.  
  215.   /**
  216.    * Returns the DCOPServiceType supported by this service.
  217.    * @return the DCOPServiceType supported by this service
  218.    */
  219.   DCOPServiceType_t DCOPServiceType() const { return m_DCOPServiceType; }
  220.  
  221.   /**
  222.    * Returns the working directory to run the program in.
  223.    * @return the working directory to run the program in,
  224.    *         or QString::null if not set
  225.    */
  226.   QString path() const { return m_strPath; }
  227.  
  228.   /**
  229.    * Returns the descriptive comment for the service, if there is one.
  230.    * @return the descriptive comment for the service, or QString::null
  231.    *         if not set
  232.    */
  233.   QString comment() const { return m_strComment; }
  234.  
  235.   /**
  236.    * Returns the generic name for the service, if there is one
  237.    * (e.g. "Mail Client").
  238.    * @return the generic name,
  239.    *         or QString::null if not set
  240.    */
  241.   QString genericName() const { return m_strGenName; }
  242.  
  243.   /**
  244.    * Returns the untranslated (US English) generic name
  245.    * for the service, if there is one
  246.    * (e.g. "Mail Client").
  247.    * @return the generic name,
  248.    *         or QString::null if not set
  249.    * @since 3.2
  250.    */
  251.   QString untranslatedGenericName() const;
  252.  
  253.   /**
  254.    * Returns a list of descriptive keywords the service, if there are any.
  255.    * @return the list of keywords
  256.    */
  257.   QStringList keywords() const { return m_lstKeywords; }
  258.  
  259.   /**
  260.    * Returns a list of VFolder categories.
  261.    * @return the list of VFolder categories
  262.    * @since 3.1
  263.    */
  264.   QStringList categories() const;
  265.  
  266.   /**
  267.    * Returns the service types that this service supports.
  268.    * @return the list of service types that are supported
  269.    */
  270.   QStringList serviceTypes() const { return m_lstServiceTypes; }
  271.  
  272.   /**
  273.    * Checks whether the service supports this service type
  274.    * @param _service The name of the service type you are
  275.    *        interested in determining whether this services supports.
  276.    *
  277.    * @return true if the service you specified is supported,
  278.    *        otherwise false.
  279.    */
  280.   bool hasServiceType( const QString& _service ) const;
  281.  
  282.   /**
  283.    * Set to true if it is allowed to use this service as the default (main)
  284.    * action for the files it supports (e.g. Left Click in a file manager, or KRun in general).
  285.    *
  286.    * If not, then this service is only available in RMB popups, so it must
  287.    * be selected explicitely by the user in order to be used.
  288.    * Note that servicemenus supersede this functionality though, at least in konqueror.
  289.    *
  290.    * @return true if the service may be used as the default (main) handler
  291.    */
  292.   bool allowAsDefault() const { return m_bAllowAsDefault; }
  293.  
  294.   /**
  295.    * Checks whether this service can handle several files as
  296.    * startup arguments.
  297.    * @return true if multiple files may be passed to this service at
  298.    * startup. False if only one file at a time may be passed.
  299.    */
  300.   bool allowMultipleFiles() const;
  301.  
  302.   /**
  303.    * What preference to associate with this service initially (before
  304.    * the user has had any chance to define a profile for it).
  305.    * The bigger the value, the most preferred the service is.
  306.    * @return the service preference level of the service
  307.    */
  308.   int initialPreference() const { return m_initialPreference; }
  309.  
  310.   /**
  311.    * What preference to associate with this service initially
  312.    * for handling the specified mimetype. (before the user has
  313.    * had any chance to define a profile for it).
  314.    * The bigger the value, the most preferred the service is.
  315.    * @return the service preference level of the service for
  316.    * this mimetype
  317.    */
  318.   int initialPreferenceForMimeType( const QString& mimeType ) const;
  319.  
  320.   /**
  321.    * @internal. Allows KServiceType::offers to tweak the initial preference.
  322.    */
  323.   void setInitialPreference( int i ) { m_initialPreference = i; }
  324.  
  325.   /**
  326.    * Whether the entry should be suppressed in menus.
  327.    * @return true to suppress this service
  328.    */
  329.   bool noDisplay() const;
  330.  
  331.   /**
  332.    * Name of the application this service belongs to.
  333.    * (Useful for e.g. plugins)
  334.    * @return the parent application, or QString::null if not set
  335.    * @since 3.1
  336.    */
  337.   QString parentApp() const;
  338.  
  339.   /**
  340.    * Returns the requested property. Some often used properties
  341.    * have convenience access functions like exec(),
  342.    * serviceTypes etc.
  343.    *
  344.    * It depends upon the serviceTypes() of this service which
  345.    * properties a service can have.
  346.    *
  347.    * @param _name the name of the property
  348.    * @return the property, or invalid if not found
  349.    * @see KServiceType
  350.    */
  351.   virtual QVariant property( const QString& _name ) const;
  352.  
  353.   /**
  354.    * Returns the requested property.
  355.    *
  356.    * @param _name the name of the property
  357.    * @param t the assumed type of the property
  358.    * @return the property, or invalid if not found
  359.    * @see KServiceType
  360.    * @since 3.2
  361.    */
  362.   QVariant property( const QString& _name, QVariant::Type t ) const;
  363.  
  364.   /**
  365.    * Returns the list of all properties that this service can have.
  366.    * That means, that some of these properties may be empty.
  367.    * @return the list of supported properties
  368.    */
  369.   virtual QStringList propertyNames() const;
  370.  
  371.   /**
  372.    * Checks whether the service is valid.
  373.    * @return true if the service is valid (e.g. name is not empty)
  374.    */
  375.   bool isValid() const { return m_bValid; }
  376.  
  377.   /**
  378.    * Returns a path that can be used for saving changes to this
  379.    * service
  380.    * @return path that can be used for saving changes to this service
  381.    * @since 3.2
  382.    */
  383.   QString locateLocal();
  384.  
  385.   /**
  386.    * @internal
  387.    * Load the service from a stream.
  388.    */
  389.   virtual void load( QDataStream& );
  390.   /**
  391.    * @internal
  392.    * Save the service to a stream.
  393.    */
  394.   virtual void save( QDataStream& );
  395.   /**
  396.    * @internal
  397.    * Set the menu id
  398.    */
  399.   void setMenuId(const QString &menuId);
  400.   /**
  401.    * @internal
  402.    * Sets whether to use a terminal or not
  403.    */
  404.   void setTerminal(bool b) { m_bTerminal = b; }
  405.   /**
  406.    * @internal
  407.    * Sets the terminal options to use
  408.    */
  409.   void setTerminalOptions(const QString &options) { m_strTerminalOptions = options; }
  410.  
  411.   /**
  412.    * Find a service by name, i.e. the translated Name field. You should
  413.    * really not use this method, since the name is translated.
  414.    *
  415.    * @param _name the name to search
  416.    * @return a pointer to the requested service or 0 if the service is
  417.    *         unknown.
  418.    * @em Very @em important: Don't store the result in a KService* !
  419.    */
  420.   static Ptr serviceByName( const QString& _name );
  421.  
  422.   /**
  423.    * Find a service based on its path as returned by desktopEntryPath().
  424.    * It's usually better to use serviceByStorageId() instead.
  425.    *
  426.    * @param _path the path of the configuration file
  427.    * @return a pointer to the requested service or 0 if the service is
  428.    *         unknown.
  429.    * @em Very @em important: Don't store the result in a KService* !
  430.    */
  431.   static Ptr serviceByDesktopPath( const QString& _path );
  432.  
  433.   /**
  434.    * Find a service by the name of its desktop file, not depending on
  435.    * its actual location (as long as it's under the applnk or service
  436.    * directories). For instance "konqbrowser" or "kcookiejar". Note that
  437.    * the ".desktop" extension is implicit.
  438.    *
  439.    * This is the recommended method (safe even if the user moves stuff)
  440.    * but note that it assumes that no two entries have the same filename.
  441.    *
  442.    * @param _name the name of the configuration file
  443.    * @return a pointer to the requested service or 0 if the service is
  444.    *         unknown.
  445.    * @em Very @em important: Don't store the result in a KService* !
  446.    */
  447.   static Ptr serviceByDesktopName( const QString& _name );
  448.  
  449.   /**
  450.    * Find a service by its menu-id
  451.    *
  452.    * @param _menuId the menu id of the service
  453.    * @return a pointer to the requested service or 0 if the service is
  454.    *         unknown.
  455.    * @em Very @em important: Don't store the result in a KService* !
  456.    * @since 3.2
  457.    */
  458.   static Ptr serviceByMenuId( const QString& _menuId );
  459.  
  460.   /**
  461.    * Find a service by its storage-id or desktop-file path. This
  462.    * function will try very hard to find a matching service.
  463.    *
  464.    * @param _storageId the storage id or desktop-file path of the service
  465.    * @return a pointer to the requested service or 0 if the service is
  466.    *         unknown.
  467.    * @em Very @em important: Don't store the result in a KService* !
  468.    * @since 3.2
  469.    */
  470.   static Ptr serviceByStorageId( const QString& _storageId );
  471.  
  472.   /**
  473.    * Returns the whole list of services.
  474.    *
  475.    *  Useful for being able to
  476.    * to display them in a list box, for example.
  477.    * More memory consuming than the ones above, don't use unless
  478.    * really necessary.
  479.    * @return the list of all services
  480.    */
  481.   static List allServices();
  482.  
  483.   /**
  484.    * Returns all services that require initialisation.
  485.    *
  486.    * Only needed by "kcminit"
  487.    * @return the list of all services that need to be initialized
  488.    */
  489.   static List allInitServices();
  490.  
  491.   /**
  492.    * Returns a path that can be used to create a new KService based
  493.    * on @p suggestedName.
  494.    * @param showInMenu true, if the service should be shown in the KDE menu
  495.    *        false, if the service should be hidden from the menu
  496.    * @param suggestedName name to base the file on, if a service with such
  497.    *        name already exists, a prefix will be added to make it unique.
  498.    * @param menuId If provided, menuId will be set to the menu id to use for
  499.    *        the KService
  500.    * @param reservedMenuIds If provided, the path and menu id will be chosen
  501.    *        in such a way that the new menu id does not conflict with any
  502.    *        of the reservedMenuIds
  503.    * @return The path to use for the new KService.
  504.    * @since 3.2
  505.    */
  506.   static QString newServicePath(bool showInMenu, const QString &suggestedName,
  507.                                 QString *menuId = 0,
  508.                                 const QStringList *reservedMenuIds = 0);
  509.  
  510.  
  511.   /**
  512.    * Rebuild KSycoca and show a progress dialog while doing so.
  513.    * @param parent Parent widget for the progress dialog
  514.    * @since 3.2
  515.    */
  516.   static void rebuildKSycoca(QWidget *parent);
  517.  
  518. protected:
  519.  
  520.   void init(KDesktopFile *config);
  521.  
  522.   QStringList &accessServiceTypes() { return m_lstServiceTypes; }
  523.  
  524.  
  525. private:
  526.   KService( const KService& ); // forbidden
  527.   KService& operator=(const KService&);
  528.  
  529.   QString m_strType;
  530.   QString m_strName;
  531.   QString m_strExec;
  532.   QString m_strIcon;
  533.   QString m_strTerminalOptions;
  534.   QString m_strPath;
  535.   QString m_strComment;
  536.   QString m_strLibrary;
  537.   QStringList m_lstServiceTypes;
  538.   bool m_bAllowAsDefault;
  539.   int m_initialPreference;
  540.   bool m_bTerminal;
  541.   //bool m_bSuid;
  542.   //QString m_strUsername;
  543.   QString m_strDesktopEntryName;
  544.   //QString m_docPath;
  545.   //bool m_bHideFromPanel;
  546.   DCOPServiceType_t m_DCOPServiceType;
  547.   QMap<QString,QVariant> m_mapProps;
  548.   bool m_bValid;
  549.   QStringList m_lstKeywords;
  550.   QString m_strInit;
  551.   QString m_strGenName;
  552. protected:
  553.   virtual void virtual_hook( int id, void* data );
  554. private:
  555.   class KServicePrivate;
  556.   KServicePrivate* d;
  557. };
  558. #endif
  559.