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