]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/process.tex
Fixed two instances of : inbetween wxRect and method name (Inside and Intersects...
[wxWidgets.git] / docs / latex / wx / process.tex
1 \section{\class{wxProcess}}\label{wxprocess}
2
3 The objects of this class are used in conjunction with the
4 \helpref{wxExecute}{wxexecute} function. When a wxProcess object is passed to
5 wxExecute(), its \helpref{OnTerminate()}{wxprocessonterminate} virtual method
6 is called when the process terminates. This allows the program to be
7 (asynchronously) notified about the process termination and also retrieve its
8 exit status which is unavailable from wxExecute() in the case of
9 asynchronous execution.
10
11 Please note that if the process termination notification is processed by the
12 parent, it is responsible for deleting the wxProcess object which sent it.
13 However, if it is not processed, the object will delete itself and so the
14 library users should only delete those objects whose notifications have been
15 processed (and call \helpref{Detach()}{wxprocessdetach} for others).
16
17 wxProcess also supports IO redirection of the child process. For this, you have
18 to call its \helpref{Redirect}{wxprocessredirect} method before passing it to
19 \helpref{wxExecute}{wxexecute}. If the child process was launched successfully,
20 \helpref{GetInputStream}{wxprocessgetinputstream},
21 \helpref{GetOutputStream}{wxprocessgetoutputstream} and
22 \helpref{GetErrorStream}{wxprocessgeterrorstream} can then be used to retrieve
23 the streams corresponding to the child process standard output, input and
24 error output respectively.
25
26 \perlnote{In wxPerl this class has an additional {\tt Destroy} method,
27 for explicit destruction.}
28
29 \wxheading{Derived from}
30
31 \helpref{wxEvtHandler}{wxevthandler}
32
33 \wxheading{Include files}
34
35 <wx/process.h>
36
37 \wxheading{See also}
38
39 \helpref{wxExecute}{wxexecute}\\
40 \helpref{exec sample}{sampleexec}
41
42 \latexignore{\rtfignore{\wxheading{Members}}}
43
44 \membersection{wxProcess::wxProcess}\label{wxprocessctor}
45
46 \func{}{wxProcess}{\param{wxEvtHandler *}{ parent = NULL}, \param{int}{ id = -1}}
47
48 \func{}{wxProcess}{\param{int }{flags}}
49
50 Constructs a process object. {\it id} is only used in the case you want to
51 use wxWidgets events. It identifies this object, or another window that will
52 receive the event.
53
54 If the {\it parent} parameter is different from NULL, it will receive
55 a wxEVT\_END\_PROCESS notification event (you should insert EVT\_END\_PROCESS
56 macro in the event table of the parent to handle it) with the given {\it id}.
57
58 The second constructor creates an object without any associated parent (and
59 hence no id neither) but allows to specify the {\it flags} which can have the
60 value of {\tt wxPROCESS\_DEFAULT} or {\tt wxPROCESS\_REDIRECT}. Specifying the
61 former value has no particular effect while using the latter one is equivalent
62 to calling \helpref{Redirect}{wxprocessredirect}.
63
64 \wxheading{Parameters}
65
66 \docparam{parent}{The event handler parent.}
67
68 \docparam{id}{id of an event.}
69
70 \docparam{flags}{either {\tt wxPROCESS\_DEFAULT} or {\tt wxPROCESS\_REDIRECT}}
71
72 \membersection{wxProcess::\destruct{wxProcess}}\label{wxprocessdtor}
73
74 \func{}{\destruct{wxProcess}}{\void}
75
76 Destroys the wxProcess object.
77
78 \membersection{wxProcess::CloseOutput}\label{wxprocesscloseoutput}
79
80 \func{void}{CloseOutput}{\void}
81
82 Closes the output stream (the one connected to the stdin of the child
83 process). This function can be used to indicate to the child process that
84 there is no more data to be read - usually, a filter program will only
85 terminate when the input stream is closed.
86
87 \membersection{wxProcess::Detach}\label{wxprocessdetach}
88
89 \func{void}{Detach}{\void}
90
91 Normally, a wxProcess object is deleted by its parent when it receives the
92 notification about the process termination. However, it might happen that the
93 parent object is destroyed before the external process is terminated (e.g. a
94 window from which this external process was launched is closed by the user)
95 and in this case it {\bf should not delete} the wxProcess object, but
96 {\bf should call Detach()} instead. After the wxProcess object is detached
97 from its parent, no notification events will be sent to the parent and the
98 object will delete itself upon reception of the process termination
99 notification.
100
101 \membersection{wxProcess::GetErrorStream}\label{wxprocessgeterrorstream}
102
103 \constfunc{wxInputStream* }{GetErrorStream}{\void}
104
105 Returns an input stream which corresponds to the standard error output (stderr)
106 of the child process.
107
108 \membersection{wxProcess::GetInputStream}\label{wxprocessgetinputstream}
109
110 \constfunc{wxInputStream* }{GetInputStream}{\void}
111
112 It returns an input stream corresponding to the standard output stream of the
113 subprocess. If it is NULL, you have not turned on the redirection.
114 See \helpref{wxProcess::Redirect}{wxprocessredirect}.
115
116 \membersection{wxProcess::GetOutputStream}\label{wxprocessgetoutputstream}
117
118 \constfunc{wxOutputStream* }{GetOutputStream}{\void}
119
120 It returns an output stream correspoding to the input stream of the subprocess.
121 If it is NULL, you have not turned on the redirection.
122 See \helpref{wxProcess::Redirect}{wxprocessredirect}.
123
124 \membersection{wxProcess::IsErrorAvailable}\label{wxprocessiserroravailable}
125
126 \constfunc{bool}{IsErrorAvailable}{\void}
127
128 Returns {\tt true} if there is data to be read on the child process standard
129 error stream.
130
131 \wxheading{See also}
132
133 \helpref{IsInputAvailable}{wxprocessisinputavailable}
134
135 \membersection{wxProcess::IsInputAvailable}\label{wxprocessisinputavailable}
136
137 \constfunc{bool}{IsInputAvailable}{\void}
138
139 Returns {\tt true} if there is data to be read on the child process standard
140 output stream. This allows to write simple (and extremely inefficient)
141 polling-based code waiting for a better mechanism in future wxWidgets versions.
142
143 See the \helpref{exec sample}{sampleexec} for an example of using this
144 function.
145
146 \wxheading{See also}
147
148 \helpref{IsInputOpened}{wxprocessisinputopened}
149
150 \membersection{wxProcess::IsInputOpened}\label{wxprocessisinputopened}
151
152 \constfunc{bool}{IsInputOpened}{\void}
153
154 Returns {\tt true} if the child process standard output stream is opened.
155
156 \membersection{wxProcess::Kill}\label{wxprocesskill}
157
158 \func{static wxKillError}{Kill}{\param{int}{ pid}, \param{wxSignal}{ signal = wxSIGNONE}}
159
160 Send the specified signal to the given process. Possible signal values are:
161
162 \begin{verbatim}
163 enum wxSignal
164 {
165 wxSIGNONE = 0, // verify if the process exists under Unix
166 wxSIGHUP,
167 wxSIGINT,
168 wxSIGQUIT,
169 wxSIGILL,
170 wxSIGTRAP,
171 wxSIGABRT,
172 wxSIGEMT,
173 wxSIGFPE,
174 wxSIGKILL, // forcefully kill, dangerous!
175 wxSIGBUS,
176 wxSIGSEGV,
177 wxSIGSYS,
178 wxSIGPIPE,
179 wxSIGALRM,
180 wxSIGTERM // terminate the process gently
181 };
182 \end{verbatim}
183
184 {\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning
185 under both Unix and Windows but all the other signals are equivalent to
186 {\tt wxSIGTERM} under Windows.
187
188 Returns the element of {\tt wxKillError} enum:
189
190 \begin{verbatim}
191 enum wxKillError
192 {
193 wxKILL_OK, // no error
194 wxKILL_BAD_SIGNAL, // no such signal
195 wxKILL_ACCESS_DENIED, // permission denied
196 wxKILL_NO_PROCESS, // no such process
197 wxKILL_ERROR // another, unspecified error
198 };
199 \end{verbatim}
200
201 \wxheading{See also}
202
203 \helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
204 \helpref{wxKill}{wxkill},\rtfsp
205 \helpref{Exec sample}{sampleexec}
206
207 \membersection{wxProcess::Exists}\label{wxprocessexists}
208
209 \func{static bool}{Exists}{\param{int}{ pid}}
210
211 Returns {\tt true} if the given process exists in the system.
212
213 \wxheading{See also}
214
215 \helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
216 \helpref{Exec sample}{sampleexec}
217
218 \membersection{wxProcess::OnTerminate}\label{wxprocessonterminate}
219
220 \func{void}{OnTerminate}{\param{int}{ pid}, \param{int}{ status}}
221
222 It is called when the process with the pid {\it pid} finishes.
223 It raises a wxWidgets event when it isn't overridden.
224
225 \docparam{pid}{The pid of the process which has just terminated.}
226
227 \docparam{status}{The exit code of the process.}
228
229 \membersection{wxProcess::Open}\label{wxprocessopen}
230
231 \func{static wxProcess *}{Open}{\param{const wxString\& }{cmd} \param{int }{flags = wxEXEC\_ASYNC}}
232
233 This static method replaces the standard {\tt popen()} function: it launches
234 the process specified by the {\it cmd} parameter and returns the wxProcess
235 object which can be used to retrieve the streams connected to the standard
236 input, output and error output of the child process.
237
238 If the process couldn't be launched, {\tt NULL} is returned. Note that in any
239 case the returned pointer should {\bf not} be deleted, rather the process
240 object will be destroyed automatically when the child process terminates. This
241 does mean that the child process should be told to quit before the main program
242 exits to avoid memory leaks.
243
244 \wxheading{Parameters}
245
246 \docparam{cmd}{The command to execute, including optional arguments.}
247 \docparam{flags}{The flags to pass to \helpref{wxExecute}{wxexecute}.
248 NOTE: wxEXEC\_SYNC should not be used.}
249
250 \wxheading{Return value}
251
252 A pointer to new wxProcess object or {\tt NULL} on error.
253
254 \wxheading{See also}
255
256 \helpref{wxExecute}{wxexecute}
257
258 \membersection{wxProcess::Redirect}\label{wxprocessredirect}
259
260 \func{void}{Redirect}{\void}
261
262 Turns on redirection. wxExecute will try to open a couple of pipes
263 to catch the subprocess stdio. The caught input stream is returned by
264 GetOutputStream() as a non-seekable stream. The caught output stream is returned
265 by GetInputStream() as a non-seekable stream.
266