tdelibs/kio/kio/kservice.h

/* This file is part of the KDE project
   Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/

#ifndef __kservices_h__
#define __kservices_h__

#include <tqstringlist.h>
#include <tqmap.h>
#include <tqvariant.h>
#include <kicontheme.h>

#include "ksycocaentry.h"

class TQDataStream;
class KDesktopFile;
class KService;
class KBuildSycoca;
class TQWidget;

/**
 * Represent a service, i.e. an application bound to one or several mimetypes
 * (or servicetypes) as written in its desktop entry file.
 *
 * A service may be a library, too.
 * The starting point you need is often the static methods.
 * Service types are stored as desktop files in the "service" resource..
 *
 * @see KServiceType
 * @see KServiceGroup
 * @author Torben Weis <weis@kde.org>
 */
class KIO_EXPORT KService : public KSycocaEntry
{
  K_SYCOCATYPE( KST_KService, KSycocaEntry )

  friend class KBuildSycoca;

public:
  typedef KSharedPtr<KService> Ptr;
  typedef TQValueList<Ptr> List;
public:
  /**
   * Construct a temporary service with a given name, exec-line and icon.
   * @param _name the name of the service
   * @param _exec the executable
   * @param _icon the name of the icon
   */
  KService( const TQString & _name, const TQString &_exec, const TQString &_icon);

  /**
   * Construct a service and take all information from a config file.
   *
   * @param _fullpath Full path to the config file.
   */
  explicit KService( const TQString & _fullpath );

  /**
   * Construct a service and take all information from a desktop file.
   * @param config the desktop file to read
   */
  KService( KDesktopFile *config ); // KDE-4.0: make explicit

  /**
   * @internal
   * Construct a service from a stream.
   * The stream must already be positionned at the correct offset.
   */
  KService( TQDataStream& _str, int offset );

  virtual ~KService();

  /**
   * Returns the type of the service.
   * @return the type of the service ("Application" or "Service")
   */
  virtual TQString type() const { return m_strType; }
  /**
   * Returns the name of the service.
   * @return the name of the service,
   *         or TQString::null if not set
   */
  virtual TQString name() const { return m_strName; }
  /**
   * Returns the executable.
   * @return the command that the service executes,
   *         or TQString::null if not set
   */
  TQString exec() const { return m_strExec; }
  /**
   * Returns the name of the service's library.
   * @return the name of the library that contains the services
   *         implementation,
   *         or TQString::null if not set
   */
  TQString library() const { return m_strLibrary; }
  /**
   * Returns the name of the init function to call (KControl modules).
   * @return the name of the init function to call in this service
   *         during startup of KDE. (KControl modules only),
   *         or TQString::null if not set
   */
  TQString init() const { return m_strInit; }

  /**
   * Returns the name of the icon.
   * @return the icon associated with the service,
   *         or "unknown" if not set
   */
  TQString icon() const { return m_strIcon; }
  /**
   * Returns the pixmap that represents the icon.
   * @return a pixmap for this service (finds and loads icon()),
   *         null if not set
   * @see icon()
   */
  TQPixmap pixmap( KIcon::Group _group, int _force_size = 0, int _state = 0,
                  TQString * _path = 0L ) const;
  /**
   * Checks whethe the service should be run in a terminal.
   * @return true if the service is to be run in a terminal.
   */
  bool terminal() const { return m_bTerminal; }
  /**
   * Returns any options associated with the terminal the service
   * runs in, if it requires a terminal.
   *
   * The service must be a tty-oriented program.
   * @return the terminal options,
   *         or TQString::null if not set
   */
  TQString terminalOptions() const { return m_strTerminalOptions; }
  /**
   * Checks whether the service runs with a different user id.
   * @return true if the service has to be run under a different uid.
   * @see username()
   */
  bool substituteUid() const;
  /**
   * Returns the user name, if the service runs with a
   * different user id.
   * @return the username under which the service has to be run,
   *         or TQString::null if not set
   * @see substututeUid()a
   */
  TQString username() const;

  /**
   * Returns the path to the location where the service desktop entry
   * is stored.
   *
   * This is a relative path if the desktop entry was found in any
   * of the locations pointed to by $KDEDIRS (e.g. "Internet/kppp.desktop")
   * It is a full path if the desktop entry originates from another
   * location.
   * @return the path of the service's desktop file,
   *         or TQString::null if not set
   */
  TQString desktopEntryPath() const { return entryPath(); }

  /**
   * Returns the filename of the service desktop entry without any
   * extension. E.g. "kppp"
   * @return the name of the desktop entry without path or extension,
   *         or TQString::null if not set
   */
  TQString desktopEntryName() const { return m_strDesktopEntryName; }

  /**
   * Returns the menu ID of the service desktop entry.
   * The menu ID is used to add or remove the entry to a menu.
   * @return the menu ID
   * @since 3.2
   */
  TQString menuId() const;

  /**
   * Returns a normalized ID suitable for storing in configuration files.
   * It will be based on the menu-id when available and otherwise falls
   * back to desktopEntryPath()
   * @return the storage ID
   * @since 3.2
   */
  TQString storageId() const;

  /**
   * Describes the DCOP type of the service.
   * @li None - This service has no DCOP support
   * @li Unique - This service provides a unique DCOP service.
   *              The service name is equal to the desktopEntryName.
   * @li Multi - This service provides a DCOP service which can be run
   *             with multiple instances in parallel. The service name of
   *             an instance is equal to the desktopEntryName + "-" +
   *             the PID of the process.
   * @li Wait - This service has no DCOP support, the launcher will wait
   *            till it is finished.
   */
  enum DCOPServiceType_t { DCOP_None = 0, DCOP_Unique, DCOP_Multi, DCOP_Wait };

  /**
   * Returns the DCOPServiceType supported by this service.
   * @return the DCOPServiceType supported by this service
   */
  DCOPServiceType_t DCOPServiceType() const { return m_DCOPServiceType; }

  /**
   * Returns the working directory to run the program in.
   * @return the working directory to run the program in,
   *         or TQString::null if not set
   */
  TQString path() const { return m_strPath; }

  /**
   * Returns the descriptive comment for the service, if there is one.
   * @return the descriptive comment for the service, or TQString::null
   *         if not set
   */
  TQString comment() const { return m_strComment; }

  /**
   * Returns the generic name for the service, if there is one
   * (e.g. "Mail Client").
   * @return the generic name,
   *         or TQString::null if not set
   */
  TQString genericName() const { return m_strGenName; }

  /**
   * Returns the untranslated (US English) generic name
   * for the service, if there is one
   * (e.g. "Mail Client").
   * @return the generic name,
   *         or TQString::null if not set
   * @since 3.2
   */
  TQString untranslatedGenericName() const;

  /**
   * Returns a list of descriptive keywords the service, if there are any.
   * @return the list of keywords
   */
  TQStringList keywords() const { return m_lstKeywords; }

  /**
   * Returns a list of VFolder categories.
   * @return the list of VFolder categories
   * @since 3.1
   */
  TQStringList categories() const;

  /**
   * Returns the service types that this service supports.
   * @return the list of service types that are supported
   */
  TQStringList serviceTypes() const { return m_lstServiceTypes; }

  /**
   * Checks whether the service supports this service type
   * @param _service The name of the service type you are
   *        interested in determining whether this services supports.
   *
   * @return true if the service you specified is supported,
   *        otherwise false.
   */
  bool hasServiceType( const TQString& _service ) const;

  /**
   * Set to true if it is allowed to use this service as the default (main)
   * action for the files it supports (e.g. Left Click in a file manager, or KRun in general).
   *
   * If not, then this service is only available in RMB popups, so it must
   * be selected explicitely by the user in order to be used.
   * Note that servicemenus supersede this functionality though, at least in konqueror.
   *
   * @return true if the service may be used as the default (main) handler
   */
  bool allowAsDefault() const { return m_bAllowAsDefault; }

  /**
   * Checks whether this service can handle several files as
   * startup arguments.
   * @return true if multiple files may be passed to this service at
   * startup. False if only one file at a time may be passed.
   */
  bool allowMultipleFiles() const;

  /**
   * What preference to associate with this service initially (before
   * the user has had any chance to define a profile for it).
   * The bigger the value, the most preferred the service is.
   * @return the service preference level of the service
   */
  int initialPreference() const { return m_initialPreference; }

  /**
   * What preference to associate with this service initially
   * for handling the specified mimetype. (before the user has
   * had any chance to define a profile for it).
   * The bigger the value, the most preferred the service is.
   * @return the service preference level of the service for
   * this mimetype
   */
  int initialPreferenceForMimeType( const TQString& mimeType ) const;

  /**
   * @internal. Allows KServiceType::offers to tweak the initial preference.
   */
  void setInitialPreference( int i ) { m_initialPreference = i; }

  /**
   * Whether the entry should be suppressed in menus.
   * @return true to suppress this service
   */
  bool noDisplay() const;
  /**
   * check if the application entry is important
   */
  bool SuSEunimportant() const;

  /**
   * Name of the application this service belongs to.
   * (Useful for e.g. plugins)
   * @return the parent application, or TQString::null if not set
   * @since 3.1
   */
  TQString parentApp() const;

  /**
   * Returns the requested property. Some often used properties
   * have convenience access functions like exec(),
   * serviceTypes etc.
   *
   * It depends upon the serviceTypes() of this service which
   * properties a service can have.
   *
   * @param _name the name of the property
   * @return the property, or invalid if not found
   * @see KServiceType
   */
  virtual TQVariant property( const TQString& _name ) const;

  /**
   * Returns the requested property.
   *
   * @param _name the name of the property
   * @param t the assumed type of the property
   * @return the property, or invalid if not found
   * @see KServiceType
   * @since 3.2
   */
  TQVariant property( const TQString& _name, TQVariant::Type t ) const;

  /**
   * Returns the list of all properties that this service can have.
   * That means, that some of these properties may be empty.
   * @return the list of supported properties
   */
  virtual TQStringList propertyNames() const;

  /**
   * Checks whether the service is valid.
   * @return true if the service is valid (e.g. name is not empty)
   */
  bool isValid() const { return m_bValid; }

  /**
   * Returns a path that can be used for saving changes to this
   * service
   * @return path that can be used for saving changes to this service
   * @since 3.2
   */
  TQString locateLocal();

  /**
   * @internal
   * Load the service from a stream.
   */
  virtual void load( TQDataStream& );
  /**
   * @internal
   * Save the service to a stream.
   */
  virtual void save( TQDataStream& );
  /**
   * @internal
   * Set the menu id
   */
  void setMenuId(const TQString &menuId);
  /**
   * @internal
   * Sets whether to use a terminal or not
   */
  void setTerminal(bool b) { m_bTerminal = b; }
  /**
   * @internal
   * Sets the terminal options to use
   */
  void setTerminalOptions(const TQString &options) { m_strTerminalOptions = options; }

  /**
   * Find a service by name, i.e. the translated Name field. You should
   * really not use this method, since the name is translated.
   *
   * @param _name the name to search
   * @return a pointer to the requested service or 0 if the service is
   *         unknown.
   * @em Very @em important: Don't store the result in a KService* !
   */
  static Ptr serviceByName( const TQString& _name );

  /**
   * Find a service based on its path as returned by desktopEntryPath().
   * It's usually better to use serviceByStorageId() instead.
   *
   * @param _path the path of the configuration file
   * @return a pointer to the requested service or 0 if the service is
   *         unknown.
   * @em Very @em important: Don't store the result in a KService* !
   */
  static Ptr serviceByDesktopPath( const TQString& _path );

  /**
   * Find a service by the name of its desktop file, not depending on
   * its actual location (as long as it's under the applnk or service
   * directories). For instance "konqbrowser" or "kcookiejar". Note that
   * the ".desktop" extension is implicit.
   *
   * This is the recommended method (safe even if the user moves stuff)
   * but note that it assumes that no two entries have the same filename.
   *
   * @param _name the name of the configuration file
   * @return a pointer to the requested service or 0 if the service is
   *         unknown.
   * @em Very @em important: Don't store the result in a KService* !
   */
  static Ptr serviceByDesktopName( const TQString& _name );

  /**
   * Find a service by its menu-id
   *
   * @param _menuId the menu id of the service
   * @return a pointer to the requested service or 0 if the service is
   *         unknown.
   * @em Very @em important: Don't store the result in a KService* !
   * @since 3.2
   */
  static Ptr serviceByMenuId( const TQString& _menuId );

  /**
   * Find a service by its storage-id or desktop-file path. This
   * function will try very hard to find a matching service.
   *
   * @param _storageId the storage id or desktop-file path of the service
   * @return a pointer to the requested service or 0 if the service is
   *         unknown.
   * @em Very @em important: Don't store the result in a KService* !
   * @since 3.2
   */
  static Ptr serviceByStorageId( const TQString& _storageId );

  /**
   * Returns the whole list of services.
   *
   *  Useful for being able to
   * to display them in a list box, for example.
   * More memory consuming than the ones above, don't use unless
   * really necessary.
   * @return the list of all services
   */
  static List allServices();

  /**
   * Returns all services that require initialisation.
   *
   * Only needed by "kcminit"
   * @return the list of all services that need to be initialized
   */
  static List allInitServices();

  /**
   * Returns a path that can be used to create a new KService based
   * on @p suggestedName.
   * @param showInMenu true, if the service should be shown in the KDE menu
   *        false, if the service should be hidden from the menu
   * @param suggestedName name to base the file on, if a service with such
   *        name already exists, a prefix will be added to make it unique.
   * @param menuId If provided, menuId will be set to the menu id to use for
   *        the KService
   * @param reservedMenuIds If provided, the path and menu id will be chosen
   *        in such a way that the new menu id does not conflict with any
   *        of the reservedMenuIds
   * @return The path to use for the new KService.
   * @since 3.2
   */
  static TQString newServicePath(bool showInMenu, const TQString &suggestedName,
                                TQString *menuId = 0,
                                const TQStringList *reservedMenuIds = 0);


  /**
   * Rebuild KSycoca and show a progress dialog while doing so.
   * @param parent Parent widget for the progress dialog
   * @since 3.2
   */
  static void rebuildKSycoca(TQWidget *parent);

protected:

  void init(KDesktopFile *config);

  TQStringList &accessServiceTypes() { return m_lstServiceTypes; }


private:
  KService( const KService& ); // forbidden
  KService& operator=(const KService&);

  TQString m_strType;
  TQString m_strName;
  TQString m_strExec;
  TQString m_strIcon;
  TQString m_strTerminalOptions;
  TQString m_strPath;
  TQString m_strComment;
  TQString m_strLibrary;
  TQStringList m_lstServiceTypes;
  bool m_bAllowAsDefault;
  int m_initialPreference;
  bool m_bTerminal;
  //bool m_bSuid;
  //TQString m_strUsername;
  TQString m_strDesktopEntryName;
  //TQString m_docPath;
  //bool m_bHideFromPanel;
  DCOPServiceType_t m_DCOPServiceType;
  TQMap<TQString,TQVariant> m_mapProps;
  bool m_bValid;
  TQStringList m_lstKeywords;
  TQString m_strInit;
  TQString m_strGenName;
protected:
  virtual void virtual_hook( int id, void* data );
private:
  class KServicePrivate;
  KServicePrivate* d;
};
#endif