You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdelibs/tdecore/kprocio.h

218 lines
6.8 KiB

/* This file is part of the KDE libraries
Copyright (C) 1997 David Sweet <dsweet@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 version 2 as published by the Free Software Foundation.
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 KPROCIO_H_
#define KPROCIO_H_
#include <tqstring.h>
#include <kprocess.h>
#include <tqstrlist.h>
#include "tdelibs_export.h"
class KProcIOPrivate;
class TQTextCodec;
/**
* KProcIO
*
* This class provides a slightly simpler interface to the communication
* functions provided by TDEProcess. The simplifications are:
* @li The buffer for a write is copied to an internal KProcIO
* buffer and maintained/freed appropriately. There is no need
* to be concerned with wroteStdin() signals _at_all_.
* @li readln() reads a line of data and buffers any leftovers.
* @li Conversion from/to unicode.
*
* Basically, KProcIO gives you buffered I/O similar to fgets()/fputs().
*
* Aside from these, and the fact that start() takes different
* parameters, use this class just like TDEProcess.
*
* @author David Sweet
* @short A slightly simpler interface to TDEProcess
**/
class TDECORE_EXPORT KProcIO : public TDEProcess
{
Q_OBJECT
public:
/**
* Constructor
*/
KProcIO ( TQTextCodec *codec = 0 );
/**
* Destructor
*/
~KProcIO();
/**
* Sets the communication mode to be passed to TDEProcess::start()
* by start(). The default communication mode is TDEProcess::All.
* You probably want to use this function in conjunction with
* TDEProcess::setUsePty().
* @param comm the communication mode
*/
void setComm (Communication comm);
/**
* Starts the process. It will fail in the following cases:
* @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 runmode For a detailed description of the
* various run modes, have a look at the
* general description of the TDEProcess class.
* @param includeStderr If true, data from both stdout and stderr is
* listened to. If false, only stdout is listened to.
* @return true on success, false on error.
**/
bool start (RunMode runmode = NotifyOnExit, bool includeStderr = false);
/**
* Writes text to stdin of the process.
* @param line Text to write.
* @param appendnewline if true, a newline '\\n' is appended.
* @return true if successful, false otherwise
**/
bool writeStdin(const TQString &line, bool appendnewline=true);
/**
* Writes text to stdin of the process.
* @param line Text to write.
* @param appendnewline if true, a newline '\\n' is appended.
* @return true if successful, false otherwise
**/
bool writeStdin(const TQCString &line, bool appendnewline);
/**
* Writes data to stdin of the process.
* @param data Data to write.
* @return true if successful, false otherwise
**/
bool writeStdin(const TQByteArray &data);
//I like fputs better -- it's the same as writeStdin
//inline
/**
* This function just calls writeStdin().
*
* @param line Text to write.
* @param AppendNewLine if true, a newline '\\n' is appended.
* @return true if successful, false otherwise
* @deprecated
**/
KDE_DEPRECATED bool fputs (const TQString &line, bool AppendNewLine=true)
{ return writeStdin(line, AppendNewLine); }
/**
* Closes stdin after all data has been send.
*/
void closeWhenDone();
/**
* Reads a line of text (up to and including '\\n').
*
* Use readln() in response to a readReady() signal.
* You may use it multiple times if more than one line of data is
* available.
* Be sure to use ackRead() when you have finished processing the
* readReady() signal. This informs KProcIO that you are ready for
* another readReady() signal.
*
* readln() never blocks.
*
* autoAck==true makes these functions call ackRead() for you.
*
* @param line is used to store the line that was read.
* @param autoAck when true, ackRead() is called for you.
* @param partial when provided the line is returned
* even if it does not contain a '\\n'. *partial will be set to
* false if the line contains a '\\n' and false otherwise.
* @return the number of characters read, or -1 if no data is available.
**/
int readln (TQString &line, bool autoAck=true, bool *partial=0);
/**
* This function calls readln().
* @param line is used to store the line that was read.
* @param autoAck when true, ackRead() is called for you.
* @return the number of characters read, or -1 if no data is available.
* @deprecated use readln. Note that it has an inverted autoAck default,
* though.
**/
KDE_DEPRECATED int fgets (TQString &line, bool autoAck=false)
{ return readln (line, autoAck); }
/**
* Reset the class. Doesn't kill the process.
**/
void resetAll ();
/**
* Call this after you have finished processing a readReady()
* signal. This call need not be made in the slot that was signalled
* by readReady(). You won't receive any more readReady() signals
* until you acknowledge with ackRead(). This prevents your slot
* from being reentered while you are still processing the current
* data. If this doesn't matter, then call ackRead() right away in
* your readReady()-processing slot.
**/
void ackRead ();
/**
* Turns readReady() signals on and off.
* You can turn this off at will and not worry about losing any data.
* (as long as you turn it back on at some point...)
* @param enable true to turn the signals on, false to turn them off
*/
void enableReadSignals (bool enable);
signals:
/**
* Emitted when the process is ready for reading.
* @param pio the process that emitted the signal
* @see enableReadSignals()
*/
void readReady(KProcIO *pio);
protected:
TQPtrList<TQByteArray> outbuffer;
TQCString recvbuffer;
TQTextCodec *codec;
int rbi;
bool needreadsignal, readsignalon, writeready;
void controlledEmission ();
protected slots:
void received (TDEProcess *proc, char *buffer, int buflen);
void sent (TDEProcess *);
protected:
virtual void virtual_hook( int id, void* data );
private:
KProcIOPrivate *d;
};
#endif // KPROCIO_H_