\section{\class{wxProcess}}\label{wxprocess}
-The objects of this class are used in conjunction with
+The objects of this class are used in conjunction with the
\helpref{wxExecute}{wxexecute} function. When a wxProcess object is passed to
wxExecute(), its \helpref{OnTerminate()}{wxprocessonterminate} virtual method
is called when the process terminates. This allows the program to be
library users should only delete those objects whose notifications have been
processed (and call \helpref{Detach()}{wxprocessdetach} for others).
+wxProcess also supports IO redirection of the child process. For this, you have
+to call its \helpref{Redirect}{wxprocessredirect} method before passing it to
+\helpref{wxExecute}{wxexecute}. If the child process was launched successfully,
+\helpref{GetInputStream}{wxprocessgetinputstream},
+\helpref{GetOutputStream}{wxprocessgetoutputstream} and
+\helpref{GetErrorStream}{wxprocessgeterrorstream} can then be used to retrieve
+the streams corresponding to the child process stdandard output, input and
+error output respectively.
+
+\perlnote{In wxPerl this class has an additional {\tt Destroy} method,
+for explicit destruction.}
+
\wxheading{Derived from}
\helpref{wxEvtHandler}{wxevthandler}
<wx/process.h>
+\wxheading{See also}
+
+\helpref{wxExecute}{wxexecute}\\
+\helpref{exec sample}{sampleexec}
+
\latexignore{\rtfignore{\wxheading{Members}}}
\membersection{wxProcess::wxProcess}\label{wxprocessconstr}
-\func{}{wxProcess}{\param{wxEvtHandler *}{ parent = NULL}, \param{bool}{ needPipe = FALSE}, \param{int}{ id = -1}}
+\func{}{wxProcess}{\param{wxEvtHandler *}{ parent = NULL}, \param{int}{ id = -1}}
Constructs a process object. {\it id} is only used in the case you want to
use wxWindows events. It identifies this object, or another window that will
receive the event.
-If you set {\it needPipe} to TRUE, wxExecute will try to open a couple of pipes
-to catch the subprocess stdio. The caught input stream is returned by
-GetOutputStream() as a non-seekable stream. The caught output stream is returned
-by GetInputStream() as a non-seekable stream.
-
If the {\it parent} parameter is different from NULL, it will receive
a wxEVT\_END\_PROCESS notification event (you should insert EVT\_END\_PROCESS
macro in the event table of the parent to handle it) with the given {\it id}.
Destroys the wxProcess object.
+\membersection{wxProcess::CloseOutput}\label{wxprocesscloseoutput}
+
+\func{void}{CloseOutput}{\void}
+
+Closes the output stream (the one connected to the stdin of the child
+process). This function can be used to indicate to the child process that
+there is no more data to be read - usually, a filter program will only
+terminate when the input stream is closed.
+
\membersection{wxProcess::Detach}\label{wxprocessdetach}
\func{void}{Detach}{\void}
object will delete itself upon reception of the process termination
notification.
-\membersection{wxProcess::GetInputStream}\label{wxprocessgetinputstream}
+\membersection{wxProcess::GetErrorStream}\label{wxprocessgeterrorstream}
-\constfunc{wxInputStream* }{GetInputStream}{\void}
+\constfunc{wxInputStream* }{GetErrorStream}{\void}
-It returns a input stream correspoding to the output stream of the subprocess.
-If it is NULL, you have not set needPipe to TRUE.
+Returns an input stream which corresponds to the standard error output (stderr)
+of the child process.
\membersection{wxProcess::GetInputStream}\label{wxprocessgetinputstream}
\constfunc{wxInputStream* }{GetInputStream}{\void}
-It returns a output stream corresponding to the input stream of the subprocess.
-If it is NULL, you have not set needPipe to TRUE.
+It returns an input stream corresponding to the standard output stream of the
+subprocess. If it is NULL, you have not turned on the redirection.
+See \helpref{wxProcess::Redirect}{wxprocessredirect}.
+
+\membersection{wxProcess::GetOutputStream}\label{wxprocessgetoutputstream}
+
+\constfunc{wxOutputStream* }{GetOutputStream}{\void}
+
+It returns an output stream correspoding to the input stream of the subprocess.
+If it is NULL, you have not turned on the redirection.
+See \helpref{wxProcess::Redirect}{wxprocessredirect}.
+
+\membersection{wxProcess::Kill}\label{wxprocesskill}
+
+\func{static wxKillError}{Kill}{\param{int}{ pid}, \param{wxSignal}{ signal = wxSIGNONE}}
+
+Send the specified signal to the given process. Possible signal values are:
+
+\begin{verbatim}
+enum wxSignal
+{
+ wxSIGNONE = 0, // verify if the process exists under Unix
+ wxSIGHUP,
+ wxSIGINT,
+ wxSIGQUIT,
+ wxSIGILL,
+ wxSIGTRAP,
+ wxSIGABRT,
+ wxSIGEMT,
+ wxSIGFPE,
+ wxSIGKILL, // forcefully kill, dangerous!
+ wxSIGBUS,
+ wxSIGSEGV,
+ wxSIGSYS,
+ wxSIGPIPE,
+ wxSIGALRM,
+ wxSIGTERM // terminate the process gently
+};
+\end{verbatim}
+
+{\tt wxSIGNONE}, {\tt wxSIGKILL} and {\tt wxSIGTERM} have the same meaning
+under both Unix and Windows but all the other signals are equivalent to
+{\tt wxSIGTERM} under Windows.
+
+Returns the element of {\tt wxKillError} enum:
+
+\begin{verbatim}
+enum wxKillError
+{
+ wxKILL_OK, // no error
+ wxKILL_BAD_SIGNAL, // no such signal
+ wxKILL_ACCESS_DENIED, // permission denied
+ wxKILL_NO_PROCESS, // no such process
+ wxKILL_ERROR // another, unspecified error
+};
+\end{verbatim}
+
+\wxheading{See also}
+
+\helpref{wxProcess::Exists}{wxprocessexists},\rtfsp
+\helpref{wxKill}{wxkill},\rtfsp
+\helpref{Exec sample}{sampleexec}
+
+\membersection{wxProcess::Exists}\label{wxprocessexists}
+
+\func{static bool}{Exists}{\param{int}{ pid}}
+
+Returns {\tt TRUE} if the given process exists in the system.
+
+\wxheading{See also}
+
+\helpref{wxProcess::Kill}{wxprocesskill},\rtfsp
+\helpref{Exec sample}{sampleexec}
\membersection{wxProcess::OnTerminate}\label{wxprocessonterminate}
\constfunc{void}{OnTerminate}{\param{int}{ pid}, \param{int}{ status}}
It is called when the process with the pid {\it pid} finishes.
-It raises a wxWindows event when it isn't overriden.
+It raises a wxWindows event when it isn't overridden.
\docparam{pid}{The pid of the process which has just terminated.}
\docparam{status}{The exit code of the process.}
+\membersection{wxProcess::Redirect}\label{wxprocessredirect}
+
+\func{void}{Redirect}{\void}
+
+Turns on redirection. wxExecute will try to open a couple of pipes
+to catch the subprocess stdio. The caught input stream is returned by
+GetOutputStream() as a non-seekable stream. The caught output stream is returned
+by GetInputStream() as a non-seekable stream.
+
projects / wxWidgets.git / blobdiff