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}, \param{int }{flags = wxKILL\_NOCHILDREN}}
 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 The {\it flags} parameter can be wxKILL\_NOCHILDREN (the default),
 189 or wxKILL\_CHILDREN, in which case the child processes of this
 190 process will be killed too. Note that under Unix, for wxKILL\_CHILDREN
 191 to work you should have created the process passing wxEXEC\_MAKE\_GROUP\_LEADER.
 192
 193 Returns the element of {\tt wxKillError} enum:
 194
 195 \begin{verbatim}
 196 enum wxKillError
 197 {
 198     wxKILL_OK,              // no error
 199     wxKILL_BAD_SIGNAL,      // no such signal
 200     wxKILL_ACCESS_DENIED,   // permission denied
 201     wxKILL_NO_PROCESS,      // no such process
 202     wxKILL_ERROR            // another, unspecified error
 203 };
 204 \end{verbatim}
 205
 206 \wxheading{See also}
 207
 208 \helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
 209 \helpref{wxKill}{wxkill},\rtfsp
 210 \helpref{Exec sample}{sampleexec}
 211
 212 \membersection{wxProcess::Exists}\label{wxprocessexists}
 213
 214 \func{static bool}{Exists}{\param{int}{ pid}}
 215
 216 Returns {\tt true} if the given process exists in the system.
 217
 218 \wxheading{See also}
 219
 220 \helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
 221 \helpref{Exec sample}{sampleexec}
 222
 223 \membersection{wxProcess::OnTerminate}\label{wxprocessonterminate}
 224
 225 \func{void}{OnTerminate}{\param{int}{ pid}, \param{int}{ status}}
 226
 227 It is called when the process with the pid {\it pid} finishes.
 228 It raises a wxWidgets event when it isn't overridden.
 229
 230 \docparam{pid}{The pid of the process which has just terminated.}
 231
 232 \docparam{status}{The exit code of the process.}
 233
 234 \membersection{wxProcess::Open}\label{wxprocessopen}
 235
 236 \func{static wxProcess *}{Open}{\param{const wxString\& }{cmd}, \param{int }{flags = wxEXEC\_ASYNC}}
 237
 238 This static method replaces the standard {\tt popen()} function: it launches
 239 the process specified by the {\it cmd} parameter and returns the wxProcess
 240 object which can be used to retrieve the streams connected to the standard
 241 input, output and error output of the child process.
 242
 243 If the process couldn't be launched, {\tt NULL} is returned. Note that in any
 244 case the returned pointer should {\bf not} be deleted, rather the process
 245 object will be destroyed automatically when the child process terminates. This
 246 does mean that the child process should be told to quit before the main program
 247 exits to avoid memory leaks.
 248
 249 \wxheading{Parameters}
 250
 251 \docparam{cmd}{The command to execute, including optional arguments.}
 252 \docparam{flags}{The flags to pass to \helpref{wxExecute}{wxexecute}.
 253   NOTE: wxEXEC\_SYNC should not be used.}
 254
 255 \wxheading{Return value}
 256
 257 A pointer to new wxProcess object or {\tt NULL} on error.
 258
 259 \wxheading{See also}
 260
 261 \helpref{wxExecute}{wxexecute}
 262
 263 \membersection{wxProcess::GetPid}\label{wxprocessgetpid}
 264
 265 \constfunc{long}{GetPid}{\void}
 266
 267 Returns the process ID of the process launched by \helpref{Open}{wxprocessopen}.
 268
 269 \membersection{wxProcess::Redirect}\label{wxprocessredirect}
 270
 271 \func{void}{Redirect}{\void}
 272
 273 Turns on redirection. wxExecute will try to open a couple of pipes
 274 to catch the subprocess stdio. The caught input stream is returned by
 275 GetOutputStream() as a non-seekable stream. The caught output stream is returned
 276 by GetInputStream() as a non-seekable stream.
 277