1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
/* 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 <qstring.h>
#include <kprocess.h>
#include <qstrlist.h>
#include "kdelibs_export.h"
class KProcIOPrivate;
class QTextCodec;
/**
* KProcIO
*
* This class provides a slightly simpler interface to the communication
* functions provided by KProcess. 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 KProcess.
*
* @author David Sweet
* @short A slightly simpler interface to KProcess
**/
class KDECORE_EXPORT KProcIO : public KProcess
{
Q_OBJECT
public:
/**
* Constructor
*/
KProcIO ( QTextCodec *codec = 0 );
/**
* Destructor
*/
~KProcIO();
/**
* Sets the communication mode to be passed to KProcess::start()
* by start(). The default communication mode is KProcess::All.
* You probably want to use this function in conjunction with
* KProcess::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 KProcess 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 QString &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 QCString &line, bool appendnewline);
/**
* Writes data to stdin of the process.
* @param data Data to write.
* @return true if successful, false otherwise
**/
bool writeStdin(const QByteArray &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 QString &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 (QString &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 (QString &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:
QPtrList<QByteArray> outbuffer;
QCString recvbuffer;
QTextCodec *codec;
int rbi;
bool needreadsignal, readsignalon, writeready;
void controlledEmission ();
protected slots:
void received (KProcess *proc, char *buffer, int buflen);
void sent (KProcess *);
protected:
virtual void virtual_hook( int id, void* data );
private:
KProcIOPrivate *d;
};
#endif // KPROCIO_H_
|
