/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the Qt3Support module of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#include "q3process.h"

#ifndef QT_NO_PROCESS

#include "qapplication.h"

#include "private/q3membuf_p.h"

#include <stdio.h>

#include <stdlib.h>

QT_BEGIN_NAMESPACE

//#define QT_Q3PROCESS_DEBUG

/*!

    \class Q3Process

    \brief The Q3Process class is used to start external programs and

    to communicate with them.

    \compat

    You can write to the started program's standard input, and can

    read the program's standard output and standard error. You can

    pass command line arguments to the program either in the

    constructor or with setArguments() or addArgument(). The program's

    working directory can be set with setWorkingDirectory(). If you

    need to set up environment variables pass them to the start() or

    launch() functions (see below). The processExited() signal is

    emitted if the program exits. The program's exit status is

    available from exitStatus(), although you could simply call

    normalExit() to see if the program terminated normally.

    There are two different ways to start a process. If you just want

    to run a program, optionally passing data to its standard input at

    the beginning, use one of the launch() functions. If you want full

    control of the program's standard input (especially if you don't

    know all the data you want to send to standard input at the

    beginning), use the start() function.

    If you use start() you can write to the program's standard input

    using writeToStdin() and you can close the standard input with

    closeStdin(). The wroteToStdin() signal is emitted if the data

    sent to standard input has been written. You can read from the

    program's standard output using readStdout() or readLineStdout().

    These functions return an empty QByteArray if there is no data to

    read. The readyReadStdout() signal is emitted when there is data

    available to be read from standard output. Standard error has a

    set of functions that correspond to the standard output functions,

    i.e. readStderr(), readLineStderr() and readyReadStderr().

    If you use one of the launch() functions the data you pass will be

    sent to the program's standard input which will be closed once all

    the data has been written. You should \e not use writeToStdin() or

    closeStdin() if you use launch(). If you need to send data to the

    program's standard input after it has started running use start()

    instead of launch().

    Both start() and launch() can accept a string list of strings each

    of which has the format, key=value, where the keys are the names

    of environment variables.

    You can test to see if a program is running with isRunning(). The

    program's process identifier is available from

    processIdentifier(). If you want to terminate a running program

    use tryTerminate(), but note that the program may ignore this. If

    you \e really want to terminate the program, without it having any

    chance to clean up, you can use kill().

    Although you may need quotes for a file named on the command line

    (e.g. if it contains spaces) you shouldn't use extra quotes for

    arguments passed to addArgument() or setArguments().

    The readyReadStdout() signal is emitted when there is new data on

    standard output. This happens asynchronously: you don't know if

    more data will arrive later.

    In the above example you could connect the processExited() signal

    to the slot UicManager::readFromStdout() instead. If you do so,

    you will be certain that all the data is available when the slot

    is called. On the other hand, you must wait until the process has

    finished before doing any processing.

    Note that if you are expecting a lot of output from the process,

    you may hit platform-dependent limits to the pipe buffer size. The

    solution is to make sure you connect to the output, e.g. the

    readyReadStdout() and readyReadStderr() signals and read the data

    as soon as it becomes available.

    Please note that Q3Process does not emulate a shell. This means that

    Q3Process does not do any expansion of arguments: a '*' is passed as a '*'

    to the program and is \e not replaced by all the files, a '$HOME' is also

    passed literally and is \e not replaced by the environment variable HOME

    and the special characters for IO redirection ('>', '|', etc.) are also

    passed literally and do \e not have the special meaning as they have in a

    shell.

    Also note that Q3Process does not emulate a terminal. This means that

    certain programs which need direct terminal control, do not work as

    expected with Q3Process. Such programs include console email programs (like

    pine and mutt) but also programs which require the user to enter a password

    (like su and ssh).

    \section1 Notes for Windows users

    Some Windows commands, for example, \c dir, are not provided by

    separate applications, but by the command interpreter.

    If you attempt to use Q3Process to execute these commands directly

    it won't work. One possible solution is to execute the command

    interpreter itself (\c cmd.exe on some Windows systems), and ask

    the interpreter to execute the desired command.

    Under Windows there are certain problems starting 16-bit applications

    and capturing their output. Microsoft recommends using an intermediate

    application to start 16-bit applications.

    \sa Q3Socket

*/

/*!

    \enum Q3Process::Communication

    This enum type defines the communication channels connected to the

    process.

    \value Stdin  Data can be written to the process's standard input.

    \value Stdout  Data can be read from the process's standard

    output.

    \value Stderr  Data can be read from the process's standard error.

    \value DupStderr  Both the process's standard error output \e and

    its standard output are written to its standard output. (Like

    Unix's dup2().) This means that nothing is sent to the standard

    error output. This is especially useful if your application

    requires that the output on standard output and on standard error

    must be read in the same order that they are produced. This is a

    flag, so to activate it you must pass \c{Stdout|Stderr|DupStderr},

    or \c{Stdin|Stdout|Stderr|DupStderr} if you want to provide input,

    to the setCommunication() call.

    \sa setCommunication() communication()

*/

/*!

    Constructs a Q3Process object. The \a parent and \a name parameters

    are passed to the QObject constructor.

    \sa setArguments() addArgument() start()

*/

Q3Process::Q3Process( QObject *parent, const char *name )

    : QObject( parent, name ), ioRedirection( false ), notifyOnExit( false ),

    wroteToStdinConnected( false ),

    readStdoutCalled( false ), readStderrCalled( false ),

    comms( Stdin|Stdout|Stderr )

{

    init();

}

/*!

    Constructs a Q3Process with \a arg0 as the command to be executed.

    The \a parent and \a name parameters are passed to the QObject

    constructor.

    The process is not started. You must call start() or launch() to

    start the process.

    \sa setArguments() addArgument() start()

*/

Q3Process::Q3Process( const QString& arg0, QObject *parent, const char *name )

    : QObject( parent, name ), ioRedirection( false ), notifyOnExit( false ),

    wroteToStdinConnected( false ),

    readStdoutCalled( false ), readStderrCalled( false ),

    comms( Stdin|Stdout|Stderr )

{

    init();

    addArgument( arg0 );

}

/*!

    Constructs a Q3Process with \a args as the arguments of the

    process. The first element in the list is the command to be

    executed. The other elements in the list are the arguments to this

    command. The \a parent and \a name parameters are passed to the

    QObject constructor.

    The process is not started. You must call start() or launch() to

    start the process.

    \sa setArguments() addArgument() start()

*/

Q3Process::Q3Process( const QStringList& args, QObject *parent, const char *name )

    : QObject( parent, name ), ioRedirection( false ), notifyOnExit( false ),

    wroteToStdinConnected( false ),

    readStdoutCalled( false ), readStderrCalled( false ),

    comms( Stdin|Stdout|Stderr )

{

    init();

    setArguments( args );

}

/*!

    \fn Q3Process::~Q3Process()

    Destroys the instance.

    If the process is running, it is <b>not</b> terminated! The

    standard input, standard output and standard error of the process

    are closed.

    You can connect the destroyed() signal to the kill() slot, if you

    want the process to be terminated automatically when the instance

    is destroyed.

    \sa tryTerminate() kill()

*/

/*!

    Returns the list of arguments that are set for the process.

    Arguments can be specified with the constructor or with the

    functions setArguments() and addArgument().

    Note that if you want to iterate over the list, you should iterate

    over a copy, e.g.

    \snippet doc/src/snippets/code/src_qt3support_other_q3process.cpp 0

    \sa setArguments() addArgument()

*/

QStringList Q3Process::arguments() const

{

    return _arguments;

}

/*!

    Clears the list of arguments that are set for the process.

    \sa setArguments() addArgument()

*/

void Q3Process::clearArguments()

{

    _arguments.clear();

}

/*!

    Sets \a args as the arguments for the process. The first element

    in the list is the command to be executed. The other elements in

    the list are the arguments to the command. Any previous arguments

    are deleted.

    Q3Process does not perform argument substitutions; for example, if you

    specify "*" or "$DISPLAY", these values are passed to the process

    literally. If you want to have the same behavior as the shell

    provides, you must do the substitutions yourself; i.e. instead of

    specifying a "*" you must specify the list of all the filenames in

    the current directory, and instead of "$DISPLAY" you must specify

    the value of the environment variable \c DISPLAY.

    Note for Windows users. The standard Windows shells, e.g. \c

    command.com and \c cmd.exe, do not perform file globbing, i.e.

    they do not convert a "*" on the command line into a list of files

    in the current directory. For this reason most Windows

    applications implement their own file globbing, and as a result of

    this, specifying an argument of "*" for a Windows application is

    likely to result in the application performing a file glob and

    ending up with a list of filenames.

    \sa arguments() addArgument()

*/

void Q3Process::setArguments( const QStringList& args )

{

    _arguments = args;

}

/*!

    Adds \a arg to the end of the list of arguments.

    The first element in the list of arguments is the command to be

    executed; the following elements are the command's arguments.

    \sa arguments() setArguments()

*/

void Q3Process::addArgument( const QString& arg )

{

    _arguments.append( arg );

}

#ifndef QT_NO_DIR

/*!

    Returns the working directory that was set with

    setWorkingDirectory(), or the current directory if none has been

    explicitly set.

    \sa setWorkingDirectory() QDir::current()

*/

QDir Q3Process::workingDirectory() const

{

    return workingDir;

}

/*!

    Sets \a dir as the working directory for processes. This does not

    affect running processes; only processes that are started

    afterwards are affected.

    Setting the working directory is especially useful for processes

    that try to access files with relative paths.

    \sa workingDirectory() start()

*/

void Q3Process::setWorkingDirectory( const QDir& dir )

{

    workingDir = dir;

}

#endif //QT_NO_DIR

/*!

    Returns the communication required with the process, i.e. some

    combination of the \c Communication flags.

    \sa setCommunication()

*/

int Q3Process::communication() const

{

    return comms;

}

/*!

    Sets \a commFlags as the communication required with the process.

    \a commFlags is a bitwise OR of the flags defined by the \c

    Communication enum.

    The default is \c{Stdin|Stdout|Stderr}.

    \sa communication()

*/

void Q3Process::setCommunication( int commFlags )

{

    comms = commFlags;

}

/*!

    Returns true if the process has exited normally; otherwise returns

    false. This implies that this function returns false if the

    process is still running.

    \sa isRunning() exitStatus() processExited()

*/

bool Q3Process::normalExit() const

{

    // isRunning() has the side effect that it determines the exit status!

    if ( isRunning() )

	return false;

    else

	return exitNormal;

}

/*!

    Returns the exit status of the process or 0 if the process is

    still running. This function returns immediately and does not wait

    until the process is finished.

    If normalExit() is false (e.g. if the program was killed or

    crashed), this function returns 0, so you should check the return

    value of normalExit() before relying on this value.

    \sa normalExit() processExited()

*/

int Q3Process::exitStatus() const

{

    // isRunning() has the side effect that it determines the exit status!

    if ( isRunning() )

	return 0;

    else

	return exitStat;

}

/*!

    Reads the data that the process has written to standard output.

    When new data is written to standard output, the class emits the

    signal readyReadStdout().

    If there is no data to read, this function returns a QByteArray of

    size 0: it does not wait until there is something to read.

    \sa readyReadStdout() readLineStdout() readStderr() writeToStdin()

*/

QByteArray Q3Process::readStdout()

{

    if ( readStdoutCalled ) {

	return QByteArray();

    }

    readStdoutCalled = true;

    Q3Membuf *buf = membufStdout();

    readStdoutCalled = false;

    return buf->readAll();

}

/*!

    Reads the data that the process has written to standard error.

    When new data is written to standard error, the class emits the

    signal readyReadStderr().

    If there is no data to read, this function returns a QByteArray of

    size 0: it does not wait until there is something to read.

    \sa readyReadStderr() readLineStderr() readStdout() writeToStdin()

*/

QByteArray Q3Process::readStderr()

{

    if ( readStderrCalled ) {

	return QByteArray();

    }

    readStderrCalled = true;

    Q3Membuf *buf = membufStderr();

    readStderrCalled = false;

    return buf->readAll();

}

/*!

    Reads a line of text from standard output, excluding any trailing

    newline or carriage return characters, and returns it. Returns

    an empty string if canReadLineStdout() returns false.

    By default, the text is interpreted to be in Latin-1 encoding. If you need

    other codecs, you can set a different codec with

    QTextCodec::setCodecForCStrings().

    \sa canReadLineStdout() readyReadStdout() readStdout() readLineStderr()

*/

QString Q3Process::readLineStdout()

{

    QByteArray a( 256 );

    Q3Membuf *buf = membufStdout();

    if ( !buf->scanNewline( &a ) ) {

      if ( !canReadLineStdout() )

	return QString();

      if ( !buf->scanNewline( &a ) )

	return QLatin1String(buf->readAll());

    }

    uint size = a.size();

    buf->consumeBytes( size, 0 );

    // get rid of terminating \n or \r\n

    if ( size>0 && a.at( size - 1 ) == '\n' ) {

      if ( size>1 && a.at( size - 2 ) == '\r' )

	a.chop(2);

      else

	a.chop(1);

    }

    return QString(QString::fromLatin1(a.constData()));

}

/*!

    Reads a line of text from standard error, excluding any trailing

    newline or carriage return characters and returns it. Returns

    an empty string if canReadLineStderr() returns false.

    By default, the text is interpreted to be in Latin-1 encoding. If you need

    other codecs, you can set a different codec with

    QTextCodec::setCodecForCStrings().

    \sa canReadLineStderr() readyReadStderr() readStderr() readLineStdout()

*/

QString Q3Process::readLineStderr()

{

    QByteArray a( 256 );

    Q3Membuf *buf = membufStderr();

    if ( !buf->scanNewline( &a ) ) {

      if ( !canReadLineStderr() )

	return QString();

      if ( !buf->scanNewline( &a ) )

	return QString( QString::fromLatin1( buf->readAll().constData() ) );

    }

    uint size = a.size();

    buf->consumeBytes( size, 0 );

    // get rid of terminating \n or \r\n