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 | |
26 | class KProcIOPrivate; |
27 | class 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 | |
50 | class KDE3SUPPORT_EXPORT_DEPRECATED K3ProcIO : public K3Process |
51 | { |
52 | Q_OBJECT |
53 | |
54 | public: |
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 | |
165 | Q_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 | |
173 | protected: |
174 | void controlledEmission (); |
175 | |
176 | protected Q_SLOTS: |
177 | void received (K3Process *proc, char *buffer, int buflen); |
178 | void sent (K3Process *); |
179 | |
180 | private: |
181 | KProcIOPrivate* const d; |
182 | }; |
183 | |
184 | #endif // K3PROCIO_H |
185 | |
186 | |