]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/process.h
Use DESTDIR properly and fix change-install-names script. Closes #12461
[wxWidgets.git] / interface / wx / process.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: process.h
3 // Purpose: interface of wxProcess
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 Signal constants used by wxProcess.
11 */
12 enum wxSignal
13 {
14 wxSIGNONE = 0, //!< verify if the process exists under Unix
15 wxSIGHUP,
16 wxSIGINT,
17 wxSIGQUIT,
18 wxSIGILL,
19 wxSIGTRAP,
20 wxSIGABRT,
21 wxSIGEMT,
22 wxSIGFPE,
23 wxSIGKILL, //!< forcefully kill, dangerous!
24 wxSIGBUS,
25 wxSIGSEGV,
26 wxSIGSYS,
27 wxSIGPIPE,
28 wxSIGALRM,
29 wxSIGTERM //!< terminate the process gently
30 };
31
32 /**
33 Return values for wxProcess::Kill.
34 */
35 enum wxKillError
36 {
37 wxKILL_OK, //!< no error
38 wxKILL_BAD_SIGNAL, //!< no such signal
39 wxKILL_ACCESS_DENIED, //!< permission denied
40 wxKILL_NO_PROCESS, //!< no such process
41 wxKILL_ERROR //!< another, unspecified error
42 };
43
44
45 /**
46 @class wxProcess
47
48 The objects of this class are used in conjunction with the ::wxExecute() function.
49 When a wxProcess object is passed to ::wxExecute(), its OnTerminate() virtual method
50 is called when the process terminates. This allows the program to be (asynchronously)
51 notified about the process termination and also retrieve its exit status which is
52 unavailable from ::wxExecute() in the case of asynchronous execution.
53
54 @note
55 If the @c wxEVT_END_PROCESS event sent after termination is processed by the
56 parent, then it is responsible for deleting the wxProcess object which sent it.
57 However, if it is not processed, the object will <b>delete itself</b> and so the
58 library users should only delete those objects whose notifications have been
59 processed (and call wxProcess::Detach for others).
60 This also means that unless you're going to process the @c wxEVT_END_PROCESS event,
61 you <b>must</b> allocate the wxProcess class on the heap.
62
63 wxProcess also supports IO redirection of the child process. For this, you have
64 to call its Redirect() method before passing it to ::wxExecute().
65 If the child process was launched successfully, GetInputStream(), GetOutputStream()
66 and GetErrorStream() can then be used to retrieve the streams corresponding to the
67 child process standard output, input and error output respectively.
68
69 @beginEventEmissionTable{wxProcessEvent}
70 @event{EVT_END_PROCESS(id, func)}
71 Process a @c wxEVT_END_PROCESS event, sent by wxProcess::OnTerminate upon
72 the external process termination.
73 @endEventTable
74
75 @library{wxbase}
76 @category{appmanagement}
77
78 @beginWxPerlOnly
79 In wxPerl this class has an additional @c Destroy method,
80 for explicit destruction.
81 @endWxPerlOnly
82
83 @see wxExecute(), @ref page_samples_exec
84 */
85 class wxProcess : public wxEvtHandler
86 {
87 public:
88 /**
89 Constructs a process object. @a id is only used in the case you want to
90 use wxWidgets events. It identifies this object, or another window that will
91 receive the event.
92
93 If the @a parent parameter is different from @NULL, it will receive
94 a @c wxEVT_END_PROCESS notification event (you should insert @c EVT_END_PROCESS
95 macro in the event table of the parent to handle it) with the given @a id.
96
97 @param parent
98 The event handler parent.
99 @param id
100 id of an event.
101 */
102 wxProcess(wxEvtHandler* parent = NULL, int id = -1);
103
104 /**
105 Creates an object without any associated parent (and hence no id neither)
106 but allows to specify the @a flags which can have the value of
107 @c wxPROCESS_DEFAULT or @c wxPROCESS_REDIRECT.
108
109 Specifying the former value has no particular effect while using the latter
110 one is equivalent to calling Redirect().
111 */
112 wxProcess(int flags);
113
114 /**
115 Destroys the wxProcess object.
116 */
117 virtual ~wxProcess();
118
119 /**
120 Closes the output stream (the one connected to the stdin of the child
121 process).
122
123 This function can be used to indicate to the child process that
124 there is no more data to be read - usually, a filter program will only
125 terminate when the input stream is closed.
126
127 Notice that GetOutputStream() will return @NULL after the output stream
128 is closed.
129 */
130 void CloseOutput();
131
132 /**
133 Detaches this event handler from the parent specified in the constructor
134 (see wxEvtHandler::Unlink() for a similar but not identic function).
135
136 Normally, a wxProcess object is deleted by its parent when it receives the
137 notification about the process termination.
138
139 However, it might happen that the parent object is destroyed before the external
140 process is terminated (e.g. a window from which this external process was launched
141 is closed by the user) and in this case it @b should not delete the wxProcess
142 object, but @b should call Detach() instead.
143
144 After the wxProcess object is detached from its parent, no notification events
145 will be sent to the parent and the object will delete itself upon reception of
146 the process termination notification.
147 */
148 void Detach();
149
150 /**
151 Returns @true if the given process exists in the system.
152
153 @see Kill(), @ref page_samples_exec "Exec sample"
154 */
155 static bool Exists(int pid);
156
157 /**
158 Returns an input stream which corresponds to the standard error output (stderr)
159 of the child process.
160 */
161 wxInputStream* GetErrorStream() const;
162
163 /**
164 It returns an input stream corresponding to the standard output stream of the
165 subprocess. If it is @NULL, you have not turned on the redirection.
166
167 @see Redirect().
168 */
169 wxInputStream* GetInputStream() const;
170
171 /**
172 It returns an output stream corresponding to the input stream of the subprocess.
173
174 If it is @NULL, you have not turned on the redirection or already
175 called CloseOutput().
176
177 @see Redirect().
178 */
179 wxOutputStream* GetOutputStream() const;
180
181 /**
182 Returns the process ID of the process launched by Open() or set by
183 wxExecute() (if you passed this wxProcess as argument).
184 */
185 long GetPid() const;
186
187 /**
188 Returns @true if there is data to be read on the child process standard
189 error stream.
190
191 @see IsInputAvailable()
192 */
193 bool IsErrorAvailable() const;
194
195 /**
196 Returns @true if there is data to be read on the child process standard
197 output stream.
198
199 This allows to write simple (and extremely inefficient) polling-based code
200 waiting for a better mechanism in future wxWidgets versions.
201 See the @ref page_samples_exec "exec sample" for an example of using this
202 function.
203
204 @see IsInputOpened()
205 */
206 bool IsInputAvailable() const;
207
208 /**
209 Returns @true if the child process standard output stream is opened.
210 */
211 bool IsInputOpened() const;
212
213 /**
214 Send the specified signal to the given process. Possible signal values
215 can be one of the ::wxSignal enumeration values.
216
217 @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning
218 under both Unix and Windows but all the other signals are equivalent to
219 @c wxSIGTERM under Windows.
220
221 The @a flags parameter can be @c wxKILL_NOCHILDREN (the default),
222 or @c wxKILL_CHILDREN, in which case the child processes of this
223 process will be killed too. Note that under Unix, for @c wxKILL_CHILDREN
224 to work you should have created the process passing @c wxEXEC_MAKE_GROUP_LEADER.
225
226 Returns the element of ::wxKillError enum.
227
228 @see Exists(), wxKill(), @ref page_samples_exec "Exec sample"
229 */
230 static wxKillError Kill(int pid, wxSignal sig = wxSIGTERM,
231 int flags = wxKILL_NOCHILDREN);
232
233 /**
234 It is called when the process with the pid @a pid finishes.
235 It raises a wxWidgets event when it isn't overridden.
236
237 Note that this function won't be called if you Kill() the process.
238
239 @param pid
240 The pid of the process which has just terminated.
241 @param status
242 The exit code of the process.
243 */
244 virtual void OnTerminate(int pid, int status);
245
246 /**
247 This static method replaces the standard @c popen() function: it launches
248 the process specified by the @a cmd parameter and returns the wxProcess
249 object which can be used to retrieve the streams connected to the standard
250 input, output and error output of the child process.
251
252 If the process couldn't be launched, @NULL is returned.
253
254 @remarks
255 In any case the returned pointer should @b not be deleted, rather the process
256 object will be destroyed automatically when the child process terminates. This
257 does mean that the child process should be told to quit before the main program
258 exits to avoid memory leaks.
259
260 @param cmd
261 The command to execute, including optional arguments.
262 @param flags
263 The flags to pass to ::wxExecute().
264 Note: @c wxEXEC_SYNC should not be used.
265
266 @return A pointer to new wxProcess object or @NULL on error.
267
268 @see ::wxExecute()
269 */
270 static wxProcess* Open(const wxString& cmd,
271 int flags = wxEXEC_ASYNC);
272
273 /**
274 Turns on redirection.
275
276 ::wxExecute() will try to open a couple of pipes to catch the subprocess stdio.
277 The caught input stream is returned by GetOutputStream() as a non-seekable stream.
278 The caught output stream is returned by GetInputStream() as a non-seekable stream.
279 */
280 void Redirect();
281 };
282
283
284
285 /**
286 @class wxProcessEvent
287
288 A process event is sent to the wxEvtHandler specified to wxProcess
289 when a process is terminated.
290
291 @beginEventTable{wxProcessEvent}
292 @event{EVT_END_PROCESS(id, func)}
293 Process a @c wxEVT_END_PROCESS event. @a id is the identifier of the process
294 object (the id passed to the wxProcess constructor) or a window to receive
295 the event.
296 @endEventTable
297
298 @library{wxbase}
299 @category{events}
300
301 @see wxProcess, @ref overview_events
302 */
303 class wxProcessEvent : public wxEvent
304 {
305 public:
306 /**
307 Constructor.
308
309 Takes a wxProcessObject or window id, a process id and an exit status.
310 */
311 wxProcessEvent(int id = 0, int pid = 0, int exitcode = 0);
312
313 /**
314 Returns the exist status.
315 */
316 int GetExitCode();
317
318 /**
319 Returns the process id.
320 */
321 int GetPid();
322 };
323