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 / krun.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-22  |  17.7 KB  |  504 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 1998, 1999 Torben Weis <weis@kde.org>
  3.    Copyright (C) 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 __k_run_h__
  22. #define __k_run_h__
  23.  
  24. #include <sys/stat.h>
  25. #include <sys/types.h>
  26.  
  27. #include <qobject.h>
  28. #include <qtimer.h>
  29. #include <qstring.h>
  30. #include <kurl.h>
  31. #include <kstartupinfo.h>
  32.  
  33. class KProcess;
  34. class KService;
  35. namespace KIO {
  36.    class Job;
  37.    class StatJob;
  38. }
  39.  
  40. /**
  41.  * To open files with their associated applications in KDE, use KRun.
  42.  *
  43.  * It can execute any desktop entry, as well as any file, using
  44.  * the default application or another application "bound" to the file type
  45.  * (or URL protocol).
  46.  *
  47.  * In that example, the mimetype of the file is not known by the application,
  48.  * so a KRun instance must be created. It will determine the mimetype by itself.
  49.  * If the mimetype is known, or if you even know the service (application) to
  50.  * use for this file, use one of the static methods.
  51.  *
  52.  * By default KRun uses auto deletion. It causes the KRun instance to delete
  53.  * itself when the it finished its task. If you allocate the KRun
  54.  * object on the stack you must disable auto deletion, otherwise it will crash.
  55.  *
  56.  * @short Opens files with their associated applications in KDE
  57.  */
  58. class KIO_EXPORT KRun : public QObject
  59. {
  60.   Q_OBJECT
  61. public:
  62.   /**
  63.    * Create a KRun object to run the preferred application for a file/URL.
  64.    * KRun will first determine the type of the file, and will then
  65.    * run the associated application.
  66.    *
  67.    * @param url the URL of the file or directory to 'run'
  68.    *
  69.    * @param mode The @p st_mode field of <tt>struct stat</tt>. If
  70.    *        you don't know this set it to 0.
  71.    *
  72.    * @param isLocalFile
  73.    *        If this parameter is set to @p false then @p url is
  74.    *        examined to find out whether it is a local URL or
  75.    *        not. This flag is just used to improve speed, since the
  76.    *        function KURL::isLocalFile is a bit slow.
  77.    *
  78.    * @param showProgressInfo
  79.    *        Whether to show progress information when determining the
  80.    *        type of the file (i.e. when using KIO::stat and KIO::mimetype)
  81.    *        Before you set this to false to avoid a dialog box, think about
  82.    *        a very slow FTP server...
  83.    *        It is always better to provide progress info in such cases.
  84.    */
  85.   KRun( const KURL& url, mode_t mode = 0,
  86.     bool isLocalFile = false, bool showProgressInfo = true );
  87.  
  88.   /**
  89.    * BIC: Combine with the above ctor for KDE 4.0.
  90.    * @param window
  91.    *        The top-level widget of the app that invoked this object.
  92.    *        It is used to make sure private information like passwords
  93.    *        are properly handled per application.
  94.    * @param url the URL of the file or directory to 'run'
  95.    *
  96.    * @param mode The @p st_mode field of <tt>struct stat</tt>. If
  97.    *        you don't know this set it to 0.
  98.    *
  99.    * @param isLocalFile
  100.    *        If this parameter is set to @p false then @p url is
  101.    *        examined to find out whether it is a local URL or
  102.    *        not. This flag is just used to improve speed, since the
  103.    *        function KURL::isLocalFile is a bit slow.
  104.    *
  105.    * @param showProgressInfo
  106.    *        Whether to show progress information when determining the
  107.    *        type of the file (i.e. when using KIO::stat and KIO::mimetype)
  108.    *        Before you set this to false to avoid a dialog box, think about
  109.    *        a very slow FTP server...
  110.    *        It is always better to provide progress info in such cases.
  111.    */
  112.   KRun( const KURL& url, QWidget* window, mode_t mode = 0,
  113.     bool isLocalFile = false, bool showProgressInfo = true );
  114.  
  115.   /**
  116.    * Destructor. Don't call it yourself, since a KRun object auto-deletes
  117.    * itself.
  118.    */
  119.   virtual ~KRun();
  120.  
  121.   /**
  122.    * Abort this KRun. This kills any jobs launched by it,
  123.    * and leads to deletion if auto-deletion is on.
  124.    * This is much safer than deleting the KRun (in case it's
  125.    * currently showing an error dialog box, for instance)
  126.    */
  127.   void abort();
  128.  
  129.   /**
  130.    * Returns true if the KRun instance has an error.
  131.    * @return true when an error occurred
  132.    * @see error()
  133.    */
  134.   bool hasError() const { return m_bFault; }
  135.  
  136.   /**
  137.    * Returns true if the KRun instance has finished.
  138.    * @return true if the KRun instance has finished
  139.    * @see finished()
  140.    */
  141.   bool hasFinished() const { return m_bFinished; }
  142.  
  143.   /**
  144.    * Checks whether auto delete is activated.
  145.    * Auto-deletion causes the KRun instance to delete itself
  146.    * when it finished its task.
  147.    * By default auto deletion is on.
  148.    * @return true if auto deletion is on, false otherwise
  149.    */
  150.   bool autoDelete() const { return m_bAutoDelete; }
  151.  
  152.   /**
  153.    * Enables or disabled auto deletion.
  154.    * Auto deletion causes the KRun instance to delete itself
  155.    * when it finished its task. If you allocate the KRun
  156.    * object on the stack you must disable auto deletion.
  157.    * By default auto deletion is on.
  158.    * @param b true to enable auto deletion, false to disable
  159.    */
  160.   void setAutoDelete(bool b) { m_bAutoDelete = b; }
  161.  
  162.   /**
  163.    * Set the preferred service for opening this URL, after
  164.    * its mimetype will have been found by KRun. IMPORTANT: the service is
  165.    * only used if its configuration says it can handle this mimetype.
  166.    * This is used for instance for the X-KDE-LastOpenedWith key, for
  167.    * the recent documents list.
  168.    * @param desktopEntryName the desktopEntryName of the service, e.g. "kate".
  169.    */
  170.   void setPreferredService( const QString& desktopEntryName );
  171.  
  172.   /**
  173.    * Sets whether executables, .desktop files or shell scripts should
  174.    * be run by KRun. This is enabled by default.
  175.    * @param b whether to run executable files or not.
  176.    * @see isExecutable()
  177.    * @since 3.2
  178.    */
  179.   void setRunExecutables(bool b);
  180.  
  181.   /**
  182.    * Sets whether the external webbrowser setting should be honoured.
  183.    * This is enabled by default.
  184.    * This should only be disabled in webbrowser applications.
  185.    * @param b whether to enable the external browser or not.
  186.    * @since 3.4
  187.    */
  188.   void setEnableExternalBrowser(bool b);
  189.  
  190.   /**
  191.    * Sets the file name to use in the case of downloading the file to a tempfile
  192.    * in order to give to a non-url-aware application. Some apps rely on the extension
  193.    * to determine the mimetype of the file. Usually the file name comes from the URL,
  194.    * but in the case of the HTTP Content-Disposition header, we need to override the
  195.    * file name.
  196.    * @since 3.5.3
  197.    */
  198.   void setSuggestedFileName( const QString& fileName );
  199.  
  200.   /**
  201.    * Open a list of URLs with a certain service (application).
  202.    *
  203.    * @param _service the service to run
  204.    * @param _urls the list of URLs, can be empty (app launched
  205.    *        without argument)
  206.    * @param window The top-level widget of the app that invoked this object.
  207.    * @param tempFiles if true and _urls are local files, they will be deleted
  208.    *        when the application exits.
  209.    * @return the process id, or 0 on error
  210.    * @since 3.5.2
  211.    */
  212.   static pid_t run( const KService& _service, const KURL::List& _urls, QWidget* window, bool tempFiles = false );
  213.   /**
  214.    * Open a list of URLs with a certain service (application).
  215.    *
  216.    * @param _service the service to run
  217.    * @param _urls the list of URLs, can be empty (app launched
  218.    *        without argument)
  219.    * @param tempFiles if true and _urls are local files, they will be deleted
  220.    *        when the application exits.
  221.    * @return the process id, or 0 on error
  222.    */
  223.   // BIC merge second overload with first one, using tempFiles=false
  224.   static pid_t run( const KService& _service, const KURL::List& _urls, bool tempFiles );
  225.   static pid_t run( const KService& _service, const KURL::List& _urls );
  226.   /// @since 3.5.3
  227.   /// @internal
  228.   static pid_t run( const KService& _service, const KURL::List& _urls, QWidget* window, bool tempFiles, const QString& suggestedFileName );
  229.  
  230.   /**
  231.    * Open a list of URLs with.
  232.    *
  233.    * @param _exec the name of the executable, for example
  234.    *        "/usr/bin/netscape".
  235.    * @param _urls  the list of URLs to open, can be empty (app launched without argument)
  236.    * @param _name the logical name of the application, for example
  237.    *        "Netscape 4.06".
  238.    * @param _icon the icon which should be used by the application.
  239.    * @param _obsolete1 Do not use!
  240.    * @param _obsolete2 Do not use!
  241.    * @return the process id, or 0 on error
  242.    */
  243.   static pid_t run( const QString& _exec, const KURL::List& _urls,
  244.            const QString& _name = QString::null,
  245.            const QString& _icon = QString::null,
  246.            const QString& _obsolete1 = QString::null,
  247.            const QString& _obsolete2 = QString::null );
  248.  
  249.   /**
  250.    * Open the given URL.
  251.    *
  252.    * This function is used after the mime type
  253.    * is found out. It will search for all services which can handle
  254.    * the mime type and call run() afterwards.
  255.    * @param _url the URL to open
  256.    * @param _mimetype the mime type of the resource
  257.    * @param tempFile if true and _url is a local file, it will be deleted
  258.    *        when the launched application exits.
  259.    * @param runExecutables if false then local .desktop files,
  260.    *        executables and shell scripts will not be run.
  261.    *        See also isExecutable().
  262.    * @return the process id, or 0 on error
  263.    */
  264.   // BIC Merge second overload with first one using runExecutables=true, and
  265.   // merge third overload with first one as well using tempFiles=false and
  266.   // runExecutables=true
  267.   static pid_t runURL( const KURL& _url, const QString& _mimetype, bool tempFile, bool runExecutables);
  268.   static pid_t runURL( const KURL& _url, const QString& _mimetype, bool tempFile);
  269.   static pid_t runURL( const KURL& _url, const QString& _mimetype );
  270.   /// @since 3.5.3
  271.   /// @internal
  272.   static pid_t runURL( const KURL& _url, const QString& _mimetype, bool tempFile, bool runExecutables, const QString& suggestedFileName );
  273.  
  274.   /**
  275.    * Run the given shell command and notifies kicker of the starting
  276.    * of the application. If the program to be called doesn't exist,
  277.    * an error box will be displayed.
  278.    *
  279.    * Use only when you know the full command line. Otherwise use the other
  280.    * static methods, or KRun's constructor.
  281.    *
  282.    * @p _cmd must be a shell command. You must not append "&"
  283.    * to it, since the function will do that for you.
  284.    *
  285.    * @return PID of running command, 0 if it could not be started, 0 - (PID
  286.    * of running command) if command was unsafe for map notification.
  287.    */
  288.   static pid_t runCommand( QString cmd );
  289.  
  290.   /**
  291.    * Same as the other runCommand(), but it also takes the name of the
  292.    * binary, to display an error message in case it couldn't find it.
  293.    *
  294.    * @param cmd must be a shell command. You must not append "&"
  295.    * to it, since the function will do that for you.
  296.    * @param execName the name of the executable
  297.    * @param icon icon for app starting notification
  298.    * @return PID of running command, 0 if it could not be started, 0 - (PID
  299.    * of running command) if command was unsafe for map notification.
  300.    */
  301.   static pid_t runCommand( const QString& cmd, const QString & execName, const QString & icon );
  302.  
  303.   /**
  304.    * Display the Open-With dialog for those URLs, and run the chosen application.
  305.    * @param lst the list of applications to run
  306.    * @param tempFiles if true and lst are local files, they will be deleted
  307.    *        when the application exits.
  308.    * @return false if the dialog was canceled
  309.    */
  310.   // BIC merge second overload with first one, using tempFiles=false
  311.   static bool displayOpenWithDialog( const KURL::List& lst, bool tempFiles );
  312.   static bool displayOpenWithDialog( const KURL::List& lst );
  313.   /// @since 3.5.3
  314.   /// @internal
  315.   static bool displayOpenWithDialog( const KURL::List& lst, bool tempFiles, const QString& suggestedFileName );
  316.  
  317.   /**
  318.    * Quotes a string for the shell.
  319.    * @param _str the string to quote. The quoted string will be written here
  320.    */
  321.   static void shellQuote( QString &_str );
  322.  
  323.   /**
  324.    * Processes a Exec= line as found in .desktop files.
  325.    * @param _service the service to extract information from.
  326.    * @param _urls The urls the service should open.
  327.    * @param has_shell If true, the arguments are going to be fed into a
  328.    *        shell e.g by using system().
  329.    *        If false, the arguments are going to be fed into a exec() kind
  330.    *        call.
  331.    *        If the arguments are intended for an exec() kind of call and
  332.    *        the Exec line contains shell commands then "/bin/sh -c" is added.
  333.    * @param tempFiles if true and _urls are local files, they will be deleted
  334.    *        when the application exits.
  335.    * @return a list of arguments suitable for either system() or exec().
  336.    */
  337.   static QStringList processDesktopExec(const KService &_service, const KURL::List &_urls, bool has_shell, bool tempFiles);
  338.   static QStringList processDesktopExec(const KService &_service, const KURL::List &_urls, bool has_shell);
  339.   /// @since 3.5.3
  340.   /// @internal
  341.   static QStringList processDesktopExec(const KService &_service, const KURL::List &_urls, bool has_shell, bool tempFiles, const QString& suggestedFileName);
  342.  
  343.   /**
  344.    * Given a full command line (e.g. the Exec= line from a .desktop file),
  345.    * extract the name of the binary being run.
  346.    * @param execLine the full command line
  347.    * @param removePath if true, remove a (relative or absolute) path. E.g. /usr/bin/ls becomes ls.
  348.    * @return the name of the binary to run
  349.    * @since 3.1
  350.    */
  351.   static QString binaryName( const QString & execLine, bool removePath );
  352.  
  353.   /**
  354.    * Returns whether @p serviceType refers to an executable program instead
  355.    * of a data file.
  356.    * @since 3.2
  357.    */
  358.   static bool isExecutable( const QString& serviceType );
  359.  
  360.   /**
  361.    * Returns wether the @p url of @p mimetype is executable.
  362.    * To be executable the file must pass the following rules:
  363.    * -# Must reside on the local filesystem.
  364.    * -# Must be marked as executable for the user by the filesystem.
  365.    * -# The mime type must inherit application/x-executable or application/x-executable-script.
  366.    * To allow a script to run when the above rules are satisfied add the entry
  367.    * @code
  368.    * X-KDE-IsAlso=application/x-executable-script
  369.    * @endcode
  370.    * to the mimetype's desktop file.
  371.    * @since 3.3
  372.    */
  373.    static bool isExecutableFile( const KURL& url, const QString &mimetype );
  374.  
  375.    /**
  376.     * @internal
  377.     * @since 3.4
  378.     */
  379.     static bool checkStartupNotify( const QString& binName, const KService* service, bool* silent_arg, QCString* wmclass_arg );
  380.  
  381. signals:
  382.   /**
  383.    * Emitted when the operation finished.
  384.    * @see hasFinished()
  385.    */
  386.   void finished();
  387.   /**
  388.    * Emitted when the operation had an error.
  389.    * @see hasError()
  390.    */
  391.   void error();
  392.  
  393. protected slots:
  394.   void slotTimeout();
  395.   void slotScanFinished( KIO::Job * );
  396.   void slotScanMimeType( KIO::Job *, const QString &type );
  397.   virtual void slotStatResult( KIO::Job * );
  398.  
  399. protected:
  400.   virtual void init();
  401.  
  402.   virtual void scanFile();
  403.  
  404.   /**
  405.    * Called if the mimetype has been detected. The function checks
  406.    * whether the document and appends the gzip protocol to the
  407.    * URL. Otherwise runURL is called to finish the job.
  408.    */
  409.   virtual void foundMimeType( const QString& _type );
  410.  
  411.   virtual void killJob();
  412.  
  413.   KURL m_strURL;
  414.   bool m_bFault;
  415.   bool m_bAutoDelete;
  416.   bool m_bProgressInfo;
  417.   bool m_bFinished;
  418.   KIO::Job * m_job;
  419.   QTimer m_timer;
  420.  
  421.   /**
  422.    * Used to indicate that the next action is to scan the file.
  423.    * This action is invoked from slotTimeout.
  424.    */
  425.   bool m_bScanFile;
  426.   bool m_bIsDirectory;
  427.  
  428.   /**
  429.    * USed to indicate that the next action is to initialize.
  430.    * This action is invoked from slotTimeout
  431.    */
  432.   bool m_bInit;
  433.  
  434.   bool m_bIsLocalFile;
  435.   mode_t m_mode;
  436.  
  437. protected:
  438.   virtual void virtual_hook( int id, void* data );
  439.  
  440. private:
  441.   void init (const KURL& url, QWidget* window, mode_t mode,
  442.              bool isLocalFile, bool showProgressInfo);
  443. private:
  444.   class KRunPrivate;
  445.   KRunPrivate *d;
  446. };
  447.  
  448. #ifndef KDE_NO_COMPAT
  449. /**
  450.  * @deprecated. Kept for source compatibility, does nothing nowadays.
  451.  * Do not use in new source.
  452.  * KRun can open the openwith dialog directly now.
  453.  * Use KRun::displayOpenWithDialog() if you were using KOpenWithHandler directly.
  454.  */
  455. class KIO_EXPORT_DEPRECATED KOpenWithHandler
  456. {
  457. public:
  458.   KOpenWithHandler() {}
  459.   static bool exists() { return true; }
  460. };
  461. #endif
  462.  
  463. /**
  464.  * @internal
  465.  * This class watches a process launched by KRun.
  466.  * It sends a notification when the process exits (for the taskbar)
  467.  * and it will show an error message if necessary (e.g. "program not found").
  468.  */
  469. class KIO_EXPORT KProcessRunner : public QObject
  470. {
  471.   Q_OBJECT
  472.  
  473.   public:
  474.  
  475.     static pid_t run(KProcess *, const QString & binName);
  476. #ifdef Q_WS_X11 // We don't have KStartupInfo in Qt/Embedded
  477.     static pid_t run(KProcess *, const QString & binName, const KStartupInfoId& id );
  478. #endif
  479.  
  480.     virtual ~KProcessRunner();
  481.  
  482.     pid_t pid() const;
  483.  
  484.   protected slots:
  485.  
  486.     void slotProcessExited(KProcess *);
  487.  
  488.   private:
  489.  
  490.     KProcessRunner(KProcess *, const QString & binName);
  491. #ifdef Q_WS_X11 // We don't have KStartupInfo in Qt/Embedded
  492.     KProcessRunner(KProcess *, const QString & binName, const KStartupInfoId& id );
  493. #endif
  494.     KProcessRunner();
  495.  
  496.     KProcess * process_;
  497.     QString binName;
  498. #ifdef Q_WS_X11 // We don't have KStartupInfo in Qt/Embedded
  499.     KStartupInfoId id_;
  500. #endif
  501. };
  502.  
  503. #endif
  504.