- removed a the obsolete KShellProcess class

- added a few methods to OProcess to make it easier to port programs using
  QProcess

1 files changed, 7 insertions, 65 deletions

diff --git a/libopie/oprocess.h b/libopie/oprocess.h
index fd726b4..bf5fe0e 100644
--- a/libopie/oprocess.h
+++ b/libopie/oprocess.h
@@ -62,429 +62,433 @@ class OProcessPrivate;
  *child process has already exited or not.
  *
  *@li  OProcess::NotifyOnExit -- The child process is invoked and both the
  *child and the parent process run concurrently.
  *
  *When the child process exits, the OProcess instance
  *corresponding to it emits the Qt signal @ref processExited().
  *
  *Since this signal is @em not emitted from within a UN*X
  *signal handler, arbitrary function calls can be made.
  *
  *Be aware: When the OProcess objects gets destructed, the child
  *process will be killed if it is still running!
  *This means in particular, that you cannot use a OProcess on the stack
  *with OProcess::NotifyOnExit.
  *
  *@li  OProcess::Block -- The child process starts and the parent process
  *is suspended until the child process exits. (@em Really not recommended
  *for programs with a GUI.)
  *
  *OProcess also provides several functions for determining the exit status
  *and the pid of the child process it represents.
  *
  *Furthermore it is possible to supply command-line arguments to the process
  *in a clean fashion (no null -- terminated stringlists and such...)
  *
  *A small usage example:
  *<pre>
  *OProcess *proc = new OProcess;
  *
  **proc << "my_executable";
  **proc << "These" << "are" << "the" << "command" << "line" << "args";
  *QApplication::connect(proc, SIGNAL(processExited(OProcess *)),
  *                      pointer_to_my_object, SLOT(my_objects_slot(OProcess *)));
  *proc->start();
  *</pre>
  *
  *This will start "my_executable" with the commandline arguments "These"...
  *
  *When the child process exits, the respective Qt signal will be emitted.
  *
  *@sect Communication with the child process
  *
  *OProcess supports communication with the child process through
  *stdin/stdout/stderr.
  *
  *The following functions are provided for getting data from the child
  *process or sending data to the child's stdin (For more information,
  *have a look at the documentation of each function):
  *
  *@li bool @ref writeStdin(char  *buffer, int  buflen);
  *@li  -- Transmit data to the child process's stdin.
  *
  *@li bool @ref closeStdin();
  *@li -- Closes the child process's stdin (which causes it to see an  feof(stdin)).
  *Returns false if you try to close stdin for a process that has been started
  *without a communication channel to stdin.
  *
  *@li bool @ref closeStdout();
  *@li -- Closes the child process's stdout.
  *Returns false if you try to close stdout for a process that has been started
  *without a communication channel to stdout.
  *
  *@li bool @ref closeStderr();
  *@li -- Closes the child process's stderr.
  *Returns false if you try to close stderr for a process that has been started
  *without a communication channel to stderr.
  *
  *
  *@sect QT signals:
  *
  *@li void @ref receivedStdout(OProcess  *proc, char  *buffer, int  buflen);
  *@li  void @ref receivedStderr(OProcess  *proc, char  *buffer, int  buflen);
  *@li  -- Indicates that new data has arrived from either the
  *child process's stdout or stderr.
  *
  *@li  void @ref wroteStdin(OProcess  *proc);
  *@li  -- Indicates that all data that has been sent to the child process
  *by a prior call to @ref writeStdin() has actually been transmitted to the
  *client .
  *
  *@author Christian Czezakte e9025461@student.tuwien.ac.at
  *
  *
  **/
 class OProcess : public QObject
 {
   Q_OBJECT
 
 public:
 
   /**
    * Modes in which the communication channel can be opened.
    *
    * If communication for more than one channel is required,
    * the values have to be or'ed together, for example to get
    * communication with stdout as well as with stdin, you would
    * specify @p Stdin @p | @p Stdout
    *
    * If @p NoRead is specified in conjunction with @p Stdout,
    * no data is actually read from @p Stdout but only
    * the signal @ref childOutput(int fd) is emitted.
    */
   enum Communication { NoCommunication = 0, Stdin = 1, Stdout = 2, Stderr = 4,
                                            AllOutput = 6, All = 7,
                                            NoRead };
 
   /**
    * Run-modes for a child process.
    */
   enum RunMode {
       /**
        * The application does not receive notifications from the subprocess when
        * it is finished or aborted.
        */
        DontCare,
        /**
         * The application is notified when the subprocess dies.
         */
        NotifyOnExit,
        /**
         * The application is suspended until the started process is finished.
         */
        Block };
 
   /**
    * Constructor
    */
-  OProcess();
+  OProcess(QObject *parent = 0, const char *name = 0);
+  OProcess(const QString &arg0, QObject *parent = 0, const char *name = 0);
+  OProcess(const QStringList &args, QObject *parent = 0, const char *name = 0);
 
   /**
    *Destructor:
    *
    *  If the process is running when the destructor for this class
    *  is called, the child process is killed with a SIGKILL, but
    *  only if the run mode is not of type @p DontCare.
    *  Processes started as @p DontCare keep running anyway.
   */
   virtual ~OProcess();
 
   /**
    @deprecated
 
          The use of this function is now deprecated. -- Please use the
          "operator<<" instead of "setExecutable".
 
          Sets the executable to be started with this OProcess object.
          Returns false if the process is currently running (in that
          case the executable remains unchanged.)
 
          @see operator<<
 
   */
   bool setExecutable(const QString& proc);
 
 
   /**
    * Sets the executable and the command line argument list for this process.
    *
    * For example, doing an "ls -l /usr/local/bin" can be achieved by:
    *  <pre>
    *  OProcess p;
    *  ...
    *  p << "ls" << "-l" << "/usr/local/bin"
    *  </pre>
    *
    **/
   OProcess &operator<<(const QString& arg);
   /**
    * Similar to previous method, takes a char *, supposed to be in locale 8 bit already.
    */
   OProcess &operator<<(const char * arg);
   /**
    * Similar to previous method, takes a QCString, supposed to be in locale 8 bit already.
    */
   OProcess &operator<<(const QCString & arg);
 
   /**
    * Sets the executable and the command line argument list for this process,
    * in a single method call, or add a list of arguments.
    **/
   OProcess &operator<<(const QStringList& args);
 
   /**
    * Clear a command line argument list that has been set by using
    * the "operator<<".
   */
   void clearArguments();
 
   /**
    *  Starts the process.
    *  For a detailed description of the
    *  various run modes and communication semantics, have a look at the
    *  general description of the OProcess class.
    *
    *  The following problems could cause this function to
    *    return false:
    *
    *  @li The process is already running.
    *  @li The command line argument list is empty.
    *  @li The starting of the process failed (could not fork).
    *  @li The executable was not found.
    *
    *  @param comm  Specifies which communication links should be
    *  established to the child process (stdin/stdout/stderr). By default,
    *  no communication takes place and the respective communication
    *  signals will never get emitted.
    *
    *  @return true on success, false on error
    *  (see above for error conditions)
    **/
   virtual bool start(RunMode  runmode = NotifyOnExit,
           Communication comm = NoCommunication);
 
   /**
    * Stop the process (by sending it a signal).
    *
            * @param signoThe signal to send. The default is SIGTERM.
    * @return @p true if the signal was delivered successfully.
   */
   virtual bool kill(int signo = SIGTERM);
 
   /**
      @return @p true if the process is (still) considered to be running
   */
   bool isRunning() const;
 
   /** Returns the process id of the process.
    *
    * If it is called after
    * the process has exited, it returns the process id of the last
    *  child process that was created by this instance of OProcess.
    *
    *  Calling it before any child process has been started by this
    *  OProcess instance causes pid() to return 0.
    **/
   pid_t pid() const;
 
   /**
    * Use pid().
    * @deprecated
    */
   pid_t getPid() const { return pid(); }
 
   /**
    * Suspend processing of data from stdout of the child process.
    */
   void suspend();
 
   /**
    * Resume processing of data from stdout of the child process.
    */
   void resume();
 
   /**
    * @return @p true if the process has already finished and has exited
    *  "voluntarily", ie: it has not been killed by a signal.
    *
    * Note that you should check @ref OProcess::exitStatus() to determine
    * whether the process completed its task successful or not.
    */
   bool normalExit() const;
 
   /**
    * Returns the exit status of the process.
    *
    * Please use
    * @ref OProcess::normalExit() to check whether the process has exited
    * cleanly (i.e., @ref OProcess::normalExit() returns @p true) before calling
    * this function because if the process did not exit normally,
    * it does not have a valid exit status.
   */
   int  exitStatus() const;
 
 
   /**
            * Transmit data to the child process's stdin.
    *
    * OProcess::writeStdin may return false in the following cases:
    *
    *     @li The process is not currently running.
    *
    *     @li Communication to stdin has not been requested in the @ref start() call.
    *
    *     @li Transmission of data to the child process by a previous call to
    * @ref writeStdin() is still in progress.
    *
    * Please note that the data is sent to the client asynchronously,
    * so when this function returns, the data might not have been
    * processed by the child process.
    *
    * If all the data has been sent to the client, the signal
    * @ref wroteStdin() will be emitted.
    *
    * Please note that you must not free "buffer" or call @ref writeStdin()
    * again until either a @ref wroteStdin() signal indicates that the
    * data has been sent or a @ref processHasExited() signal shows that
    * the child process is no longer alive...
    **/
   bool writeStdin(const char *buffer, int buflen);
 
+  void flushStdin();
+
   /**
    * This causes the stdin file descriptor of the child process to be
    * closed indicating an "EOF" to the child.
    *
    * @return @p false if no communication to the process's stdin
    *  had been specified in the call to @ref start().
   */
   bool closeStdin();
 
   /**
    * This causes the stdout file descriptor of the child process to be
    * closed.
    *
    * @return @p false if no communication to the process's stdout
    *  had been specified in the call to @ref start().
   */
   bool closeStdout();
 
   /**
    * This causes the stderr file descriptor of the child process to be
    * closed.
    *
    * @return @p false if no communication to the process's stderr
    *  had been specified in the call to @ref start().
   */
   bool closeStderr();
 
   /**
    * Lets you see what your arguments are for debugging.
    */
 
   const QValueList<QCString> &args() { return arguments; }
 
   /**
    * Controls whether the started process should drop any
    * setuid/segid privileges or whether it should keep them
    *
    * The default is @p false : drop privileges
    */
   void setRunPrivileged(bool keepPrivileges);
 
   /**
    * Returns whether the started process will drop any
    * setuid/segid privileges or whether it will keep them
    */
   bool runPrivileged() const;
   
   /**
    * Modifies the environment of the process to be started.
    * This function must be called before starting the process.
    */
   void setEnvironment(const QString &name, const QString &value);
 
   /**
    * Changes the current working directory (CWD) of the process 
    * to be started.
    * This function must be called before starting the process.
    */
   void setWorkingDirectory(const QString &dir);
 
   /**
    * Specify whether to start the command via a shell or directly.
    * The default is to start the command directly.
    * If @p useShell is true @p shell will be used as shell, or
    * if shell is empty, the standard shell is used.
    * @p quote A flag indicating whether to quote the arguments.
    *
    * When using a shell, the caller should make sure that all filenames etc.
    * are properly quoted when passed as argument.
    * @see quote()
    */
   void setUseShell(bool useShell, const char *shell = 0);
 
   /**
    * This function can be used to quote an argument string such that
    * the shell processes it properly. This is e. g. necessary for
    * user-provided file names which may contain spaces or quotes.
    * It also prevents expansion of wild cards and environment variables.
    */
   static QString quote(const QString &arg);
 
   /**
    * Detaches OProcess from child process. All communication is closed.
    * No exit notification is emitted any more for the child process.
    * Deleting the OProcess will no longer kill the child process.
    * Note that the current process remains the parent process of the
    * child process.
    */
   void detach(); 
 
 
 
 signals:
 
   /**
    * Emitted after the process has terminated when
    * the process was run in the @p NotifyOnExit  (==default option to
    * @ref start()) or the @ref Block mode.
    **/
   void processExited(OProcess *proc);
 
 
   /**
    * Emitted, when output from the child process has
    * been received on stdout.
    *
    *  To actually get
    * these signals, the respective communication link (stdout/stderr)
    * has to be turned on in @ref start().
    *
    * @param buffer The data received.
    * @param buflen The number of bytes that are available.
    *
    * You should copy the information contained in @p buffer to your private
    * data structures before returning from this slot.
    **/
   void receivedStdout(OProcess *proc, char *buffer, int buflen);
 
   /**
    * Emitted when output from the child process has
    * been received on stdout.
    *
    * To actually get these signals, the respective communications link 
    * (stdout/stderr) has to be turned on in @ref start() and the 
    * @p NoRead flag should have been passed.
    *
    * You will need to explicitly call resume() after your call to start()
    * to begin processing data from the child process's stdout.  This is
@@ -606,200 +610,138 @@ protected:
         -- frees all allocated communication resources in the parent
         after the process has exited
   */
 
   /**
    * This function is called from "OProcess::start" right before a "fork" takes
    * place. According to
    * the "comm" parameter this function has to initialize the "in", "out" and
    * "err" data member of OProcess.
    *
    * This function should return 0 if setting the needed communication channels
    * was successful.
    *
    * The default implementation is to create UNIX STREAM sockets for the communication,
    * but you could overload this function and establish a TCP/IP communication for
    * network communication, for example.
    */
   virtual int setupCommunication(Communication comm);
 
   /**
    * Called right after a (successful) fork on the parent side. This function
    * will usually do some communications cleanup, like closing the reading end
    * of the "stdin" communication channel.
    *
    * Furthermore, it must also create the QSocketNotifiers "innot", "outnot" and
    * "errnot" and connect their Qt slots to the respective OProcess member functions.
    *
    * For a more detailed explanation, it is best to have a look at the default
    * implementation of "setupCommunication" in kprocess.cpp.
    */
   virtual int commSetupDoneP();
 
   /**
    * Called right after a (successful) fork, but before an "exec" on the child
    * process' side. It usually just closes the unused communication ends of
    * "in", "out" and "err" (like the writing end of the "in" communication
    * channel.
    */
   virtual int commSetupDoneC();
 
 
   /**
    * Immediately called after a process has exited. This function normally
    * calls commClose to close all open communication channels to this
    * process and emits the "processExited" signal (if the process was
    * not running in the "DontCare" mode).
    */
   virtual void processHasExited(int state);
 
   /**
    * Should clean up the communication links to the child after it has
    * exited. Should be called from "processHasExited".
    */
   virtual void commClose();
 
 
   /**
    * the socket descriptors for stdin/stdout/stderr.
    */
   int out[2];
   int in[2];
   int err[2];
 
   /**
    * The socket notifiers for the above socket descriptors.
    */
   QSocketNotifier *innot;
   QSocketNotifier *outnot;
   QSocketNotifier *errnot;
 
   /**
    * Lists the communication links that are activated for the child
    * process.  Should not be modified from derived classes.
    */
   Communication communication;
 
   /**
    * Called by "slotChildOutput" this function copies data arriving from the
    * child process's stdout to the respective buffer and emits the signal
    * "@ref receivedStderr".
    */
   int childOutput(int fdno);
 
   /**
    * Called by "slotChildOutput" this function copies data arriving from the
    * child process's stdout to the respective buffer and emits the signal
    * "@ref receivedStderr"
    */
   int childError(int fdno);
 
   // information about the data that has to be sent to the child:
 
   const char *input_data;  // the buffer holding the data
   int input_sent;    // # of bytes already transmitted
   int input_total;   // total length of input_data
 
   /**
    * @ref OProcessController is a friend of OProcess because it has to have
    * access to various data members.
    */
   friend class OProcessController;
 
 
 private:
   /**
    * Searches for a valid shell. 
    * Here is the algorithm used for finding an executable shell:
    *
    *    @li Try the executable pointed to by the "SHELL" environment
    *    variable with white spaces stripped off
    *
    *    @li If your process runs with uid != euid or gid != egid, a shell
    *    not listed in /etc/shells will not used.
    *
    *    @li If no valid shell could be found, "/bin/sh" is used as a last resort.
    */
   QCString searchShell();
 
   /**
    * Used by @ref searchShell in order to find out whether the shell found
    * is actually executable at all.
    */
   bool isExecutable(const QCString &filename);
 
   // Disallow assignment and copy-construction
   OProcess( const OProcess& );
   OProcess& operator= ( const OProcess& );
 
-protected:
-  virtual void virtual_hook( int id, void* data );
-private:
-  OProcessPrivate *d;
-};
-
-class KShellProcessPrivate;
-
-/**
-* @obsolete
-*
-* This class is obsolete. Use OProcess and OProcess::setUseShell(true)
-* instead.
-*
-*   @short A class derived from @ref OProcess to start child
-        *   processes through a shell.
-*   @author Christian Czezakte <e9025461@student.tuwien.ac.at>
-*   @version $Id$
-*/
-class KShellProcess: public OProcess
-{
-  Q_OBJECT
-
-public:
-
-  /**
-   * Constructor
-   *
-   * By specifying the name of a shell (like "/bin/bash") you can override
-   * the mechanism for finding a valid shell as described in OProcess::searchShell()
-   */
-  KShellProcess(const char *shellname=0);
-
-  /**
-   * Destructor.
-   */
-  ~KShellProcess();
-
-  /**
-   * Starts up the process. -- For a detailed description
-   * have a look at the "start" member function and the detailed
-   * description of @ref OProcess .
-   */
-  virtual bool start(RunMode  runmode = NotifyOnExit,
-                  Communication comm = NoCommunication);
-
-  /**
-   * This function can be used to quote an argument string such that
-   * the shell processes it properly. This is e. g. necessary for
-   * user-provided file names which may contain spaces or quotes.
-   * It also prevents expansion of wild cards and environment variables.
-   */
-  static QString quote(const QString &arg);
-
 private:
+  void init ( );
 
-  QCString shell;
-
-  // Disallow assignment and copy-construction
-  KShellProcess( const KShellProcess& );
-  KShellProcess& operator= ( const KShellProcess& );
-
-protected:
-  virtual void virtual_hook( int id, void* data );
-private:
-  KShellProcessPrivate *d;
+  OProcessPrivate *d;
 };
 
 
 
 #endif