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{wxprocessconstr}
  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 wxWindows 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}}
  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::Kill}\label{wxprocesskill}
 125
 126 \func{static wxKillError}{Kill}{\param{int}{ pid}, \param{wxSignal}{ signal = wxSIGNONE}}
 127
 128 Send the specified signal to the given process. Possible signal values are:
 129
 130 \begin{verbatim}
 131 enum wxSignal
 132 {
 133     wxSIGNONE = 0,  // verify if the process exists under Unix
 134     wxSIGHUP,
 135     wxSIGINT,
 136     wxSIGQUIT,
 137     wxSIGILL,
 138     wxSIGTRAP,
 139     wxSIGABRT,
 140     wxSIGEMT,
 141     wxSIGFPE,
 142     wxSIGKILL,      // forcefully kill, dangerous!
 143     wxSIGBUS,
 144     wxSIGSEGV,
 145     wxSIGSYS,
 146     wxSIGPIPE,
 147     wxSIGALRM,
 148     wxSIGTERM       // terminate the process gently
 149 };
 150 \end{verbatim}
 151
 152 {\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning
 153 under both Unix and Windows but all the other signals are equivalent to
 154 {\tt wxSIGTERM} under Windows.
 155
 156 Returns the element of {\tt wxKillError} enum:
 157
 158 \begin{verbatim}
 159 enum wxKillError
 160 {
 161     wxKILL_OK,              // no error
 162     wxKILL_BAD_SIGNAL,      // no such signal
 163     wxKILL_ACCESS_DENIED,   // permission denied
 164     wxKILL_NO_PROCESS,      // no such process
 165     wxKILL_ERROR            // another, unspecified error
 166 };
 167 \end{verbatim}
 168
 169 \wxheading{See also}
 170
 171 \helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
 172 \helpref{wxKill}{wxkill},\rtfsp
 173 \helpref{Exec sample}{sampleexec}
 174
 175 \membersection{wxProcess::Exists}\label{wxprocessexists}
 176
 177 \func{static bool}{Exists}{\param{int}{ pid}}
 178
 179 Returns {\tt TRUE} if the given process exists in the system.
 180
 181 \wxheading{See also}
 182
 183 \helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
 184 \helpref{Exec sample}{sampleexec}
 185
 186 \membersection{wxProcess::OnTerminate}\label{wxprocessonterminate}
 187
 188 \constfunc{void}{OnTerminate}{\param{int}{ pid}, \param{int}{ status}}
 189
 190 It is called when the process with the pid {\it pid} finishes.
 191 It raises a wxWindows event when it isn't overridden.
 192
 193 \docparam{pid}{The pid of the process which has just terminated.}
 194
 195 \docparam{status}{The exit code of the process.}
 196
 197 \membersection{wxProcess::Open}\label{wxprocessopen}
 198
 199 \func{static wxProcess *}{Open}{\param{const wxString\& }{cmd} \param{int }{flags = wxEXEC\_ASYNC}}
 200
 201 This static method replaces the standard {\tt popen()} function: it launches
 202 the process specified by the {\it cmd} parameter and returns the wxProcess
 203 object which can be used to retrieve the streams connected to the standard
 204 input, output and error output of the child process.
 205
 206 If the process couldn't be launched, {\tt NULL} is returned. Note that in any
 207 case the returned pointer should {\bf not} be deleted, rather the process
 208 object will be destroyed automatically when the child process terminates. This
 209 does mean that the child process should be told to quit before the main program
 210 exits to avoid memory leaks.
 211
 212 \wxheading{Parameters}
 213
 214 \docparam{cmd}{The command to execute, including optional arguments.}
 215 \docparam{flags}{The flags to pass to \helpref{wxExecute}{wxexecute}.
 216   NOTE: wxEXEC_SYNC should not be used.}
 217
 218 \wxheading{Return value}
 219
 220 A pointer to new wxProcess object or {\tt NULL} on error.
 221
 222 \wxheading{See also}
 223
 224 \helpref{wxExecute}{wxexecute}
 225
 226 \membersection{wxProcess::Redirect}\label{wxprocessredirect}
 227
 228 \func{void}{Redirect}{\void}
 229
 230 Turns on redirection. wxExecute will try to open a couple of pipes
 231 to catch the subprocess stdio. The caught input stream is returned by
 232 GetOutputStream() as a non-seekable stream. The caught output stream is returned
 233 by GetInputStream() as a non-seekable stream.
 234