1/* This file is part of the KDE libraries
2 Copyright (C) 1997 David Sweet <dsweet@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18#ifndef K3PROCIO_H
19#define K3PROCIO_H
20
21#include <kde3support_export.h>
22#include <k3process.h>
23
24#include <QtCore/QString>
25
26class KProcIOPrivate;
27class QTextCodec;
28
29/**
30 * @obsolete Use KProcess and KPtyProcess instead.
31 *
32 * This class provides a slightly simpler interface to the communication
33 * functions provided by K3Process. The simplifications are:
34 * @li The buffer for a write is copied to an internal K3ProcIO
35 * buffer and maintained/freed appropriately. There is no need
36 * to be concerned with wroteStdin() signals _at_all_.
37 * @li readln() reads a line of data and buffers any leftovers.
38 * @li Conversion from/to unicode.
39 *
40 * Basically, K3ProcIO gives you buffered I/O similar to fgets()/fputs().
41 *
42 * Aside from these, and the fact that start() takes different
43 * parameters, use this class just like K3Process.
44 *
45 * @author David Sweet
46 * @short A slightly simpler interface to K3Process
47 **/
48
49
50class KDE3SUPPORT_EXPORT_DEPRECATED K3ProcIO : public K3Process
51{
52 Q_OBJECT
53
54public:
55 /**
56 * Constructor
57 */
58 explicit K3ProcIO ( QTextCodec *codec = 0 );
59
60 /**
61 * Destructor
62 */
63 ~K3ProcIO();
64
65 /**
66 * Sets the communication mode to be passed to K3Process::start()
67 * by start(). The default communication mode is K3Process::All.
68 * You probably want to use this function in conjunction with
69 * K3Process::setUsePty().
70 * @param comm the communication mode
71 */
72 void setComm (Communication comm);
73
74 /**
75 * Starts the process. It will fail in the following cases:
76 * @li The process is already running.
77 * @li The command line argument list is empty.
78 * @li The starting of the process failed (could not fork).
79 * @li The executable was not found.
80 *
81 * @param runmode For a detailed description of the
82 * various run modes, have a look at the
83 * general description of the K3Process class.
84 * @param includeStderr If true, data from both stdout and stderr is
85 * listened to. If false, only stdout is listened to.
86 * @return true on success, false on error.
87 **/
88 bool start (RunMode runmode = NotifyOnExit, bool includeStderr = false);
89
90 /**
91 * Writes text to stdin of the process.
92 * @param line Text to write.
93 * @param appendnewline if true, a newline '\\n' is appended.
94 * @return true if successful, false otherwise
95 **/
96 bool writeStdin(const QString &line, bool appendnewline=true);
97
98 /**
99 * Writes text to stdin of the process.
100 * @param line Text to write.
101 * @param appendnewline if true, a newline '\\n' is appended.
102 * @return true if successful, false otherwise
103 **/
104 bool writeStdin(const QByteArray &line, bool appendnewline);
105
106 /**
107 * Writes data to stdin of the process.
108 * @param data Data to write.
109 * @return true if successful, false otherwise
110 **/
111 bool writeStdin(const QByteArray &data);
112
113 /**
114 * Closes stdin after all data has been send.
115 */
116 void closeWhenDone();
117
118 /**
119 * Reads a line of text (up to and including '\\n').
120 *
121 * Use readln() in response to a readReady() signal.
122 * You may use it multiple times if more than one line of data is
123 * available.
124 * Be sure to use ackRead() when you have finished processing the
125 * readReady() signal. This informs K3ProcIO that you are ready for
126 * another readReady() signal.
127 *
128 * readln() never blocks.
129 *
130 * autoAck==true makes these functions call ackRead() for you.
131 *
132 * @param line is used to store the line that was read.
133 * @param autoAck when true, ackRead() is called for you.
134 * @param partial when provided the line is returned
135 * even if it does not contain a '\\n'. *partial will be set to
136 * false if the line contains a '\\n' and false otherwise.
137 * @return the number of characters read, or -1 if no data is available.
138 **/
139 int readln (QString &line, bool autoAck=true, bool *partial=0);
140
141 /**
142 * Reset the class. Doesn't kill the process.
143 **/
144 void resetAll ();
145
146 /**
147 * Call this after you have finished processing a readReady()
148 * signal. This call need not be made in the slot that was signalled
149 * by readReady(). You won't receive any more readReady() signals
150 * until you acknowledge with ackRead(). This prevents your slot
151 * from being reentered while you are still processing the current
152 * data. If this doesn't matter, then call ackRead() right away in
153 * your readReady()-processing slot.
154 **/
155 void ackRead ();
156
157 /**
158 * Turns readReady() signals on and off.
159 * You can turn this off at will and not worry about losing any data.
160 * (as long as you turn it back on at some point...)
161 * @param enable true to turn the signals on, false to turn them off
162 */
163 void enableReadSignals (bool enable);
164
165Q_SIGNALS:
166 /**
167 * Emitted when the process is ready for reading.
168 * @param pio the process that emitted the signal
169 * @see enableReadSignals()
170 */
171 void readReady(K3ProcIO *pio);
172
173protected:
174 void controlledEmission ();
175
176protected Q_SLOTS:
177 void received (K3Process *proc, char *buffer, int buflen);
178 void sent (K3Process *);
179
180private:
181 KProcIOPrivate* const d;
182};
183
184#endif // K3PROCIO_H
185
186