interface/process.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        process.h
   3 // Purpose:     documentation for wxProcess class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxProcess
  11     @wxheader{process.h}
  12
  13     The objects of this class are used in conjunction with the
  14     wxExecute function. When a wxProcess object is passed to
  15     wxExecute(), its wxProcess::OnTerminate virtual method
  16     is called when the process terminates. This allows the program to be
  17     (asynchronously) notified about the process termination and also retrieve its
  18     exit status which is unavailable from wxExecute() in the case of
  19     asynchronous execution.
  20
  21     Please note that if the process termination notification is processed by the
  22     parent, it is responsible for deleting the wxProcess object which sent it.
  23     However, if it is not processed, the object will delete itself and so the
  24     library users should only delete those objects whose notifications have been
  25     processed (and call wxProcess::Detach for others).
  26
  27     wxProcess also supports IO redirection of the child process. For this, you have
  28     to call its wxProcess::Redirect method before passing it to
  29     wxExecute. If the child process was launched successfully,
  30     wxProcess::GetInputStream,
  31     wxProcess::GetOutputStream and
  32     wxProcess::GetErrorStream can then be used to retrieve
  33     the streams corresponding to the child process standard output, input and
  34     error output respectively.
  35
  36     @b wxPerl note: In wxPerl this class has an additional @c Destroy method,
  37     for explicit destruction.
  38
  39     @library{wxbase}
  40     @category{appmanagement}
  41
  42     @seealso
  43     wxExecute, @ref overview_sampleexec "exec sample"
  44 */
  45 class wxProcess : public wxEvtHandler
  46 {
  47 public:
  48     //@{
  49     /**
  50         Constructs a process object. @e 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 @e 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 @e id.
  57
  58         The second constructor creates an object without any associated parent (and
  59         hence no id neither) but allows to specify the @e flags which can have the
  60         value of @c wxPROCESS_DEFAULT or @c wxPROCESS_REDIRECT. Specifying the
  61         former value has no particular effect while using the latter one is equivalent
  62         to calling Redirect().
  63
  64         @param parent
  65         The event handler parent.
  66
  67         @param id
  68         id of an event.
  69
  70         @param flags
  71         either wxPROCESS_DEFAULT or wxPROCESS_REDIRECT
  72     */
  73     wxProcess(wxEvtHandler * parent = @NULL, int id = -1);
  74     wxProcess(int flags);
  75     //@}
  76
  77     /**
  78         Destroys the wxProcess object.
  79     */
  80     ~wxProcess();
  81
  82     /**
  83         Closes the output stream (the one connected to the stdin of the child
  84         process). This function can be used to indicate to the child process that
  85         there is no more data to be read - usually, a filter program will only
  86         terminate when the input stream is closed.
  87     */
  88     void CloseOutput();
  89
  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 @b should not delete the wxProcess object, but
  96         @b 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     void Detach();
 102
 103     /**
 104         Returns @true if the given process exists in the system.
 105
 106         @sa Kill(), @ref overview_sampleexec "Exec sample"
 107     */
 108     static bool Exists(int pid);
 109
 110     /**
 111         Returns an input stream which corresponds to the standard error output (stderr)
 112         of the child process.
 113     */
 114     wxInputStream* GetErrorStream();
 115
 116     /**
 117         It returns an input stream corresponding to the standard output stream of the
 118         subprocess. If it is @NULL, you have not turned on the redirection.
 119         See Redirect().
 120     */
 121     wxInputStream* GetInputStream();
 122
 123     /**
 124         It returns an output stream correspoding to the input stream of the subprocess.
 125         If it is @NULL, you have not turned on the redirection.
 126         See Redirect().
 127     */
 128     wxOutputStream* GetOutputStream();
 129
 130     /**
 131         Returns the process ID of the process launched by Open().
 132     */
 133     long GetPid();
 134
 135     /**
 136         Returns @true if there is data to be read on the child process standard
 137         error stream.
 138
 139         @sa IsInputAvailable()
 140     */
 141     bool IsErrorAvailable();
 142
 143     /**
 144         Returns @true if there is data to be read on the child process standard
 145         output stream. This allows to write simple (and extremely inefficient)
 146         polling-based code waiting for a better mechanism in future wxWidgets versions.
 147
 148         See the @ref overview_sampleexec "exec sample" for an example of using this
 149         function.
 150
 151         @sa IsInputOpened()
 152     */
 153     bool IsInputAvailable();
 154
 155     /**
 156         Returns @true if the child process standard output stream is opened.
 157     */
 158     bool IsInputOpened();
 159
 160     /**
 161         Send the specified signal to the given process. Possible signal values are:
 162         @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning
 163         under both Unix and Windows but all the other signals are equivalent to
 164         @c wxSIGTERM under Windows.
 165
 166         The @e flags parameter can be wxKILL_NOCHILDREN (the default),
 167         or wxKILL_CHILDREN, in which case the child processes of this
 168         process will be killed too. Note that under Unix, for wxKILL_CHILDREN
 169         to work you should have created the process passing wxEXEC_MAKE_GROUP_LEADER.
 170
 171         Returns the element of @c wxKillError enum:
 172
 173         @sa Exists(), wxKill, @ref overview_sampleexec "Exec sample"
 174     */
 175     static wxKillError Kill(int pid, wxSignal signal = wxSIGNONE,
 176                             int flags = wxKILL_NOCHILDREN);
 177
 178     /**
 179         It is called when the process with the pid
 180
 181         @param pid finishes.
 182         It raises a wxWidgets event when it isn't overridden.
 183
 184         pid
 185         The pid of the process which has just terminated.
 186
 187         @param status
 188         The exit code of the process.
 189     */
 190     void OnTerminate(int pid, int status);
 191
 192     /**
 193         This static method replaces the standard @c popen() function: it launches
 194         the process specified by the @e cmd parameter and returns the wxProcess
 195         object which can be used to retrieve the streams connected to the standard
 196         input, output and error output of the child process.
 197
 198         If the process couldn't be launched, @NULL is returned. Note that in any
 199         case the returned pointer should @b not be deleted, rather the process
 200         object will be destroyed automatically when the child process terminates. This
 201         does mean that the child process should be told to quit before the main program
 202         exits to avoid memory leaks.
 203
 204         @param cmd
 205         The command to execute, including optional arguments.
 206
 207         @param flags
 208         The flags to pass to wxExecute.
 209           NOTE: wxEXEC_SYNC should not be used.
 210
 211         @returns A pointer to new wxProcess object or @NULL on error.
 212
 213         @sa wxExecute
 214     */
 215     static wxProcess * Open(const wxString& cmd,
 216                             int flags = wxEXEC_ASYNC);
 217
 218     /**
 219         Turns on redirection. wxExecute will try to open a couple of pipes
 220         to catch the subprocess stdio. The caught input stream is returned by
 221         GetOutputStream() as a non-seekable stream. The caught output stream is returned
 222         by GetInputStream() as a non-seekable stream.
 223     */
 224     void Redirect();
 225 };
 226
 227
 228 /**
 229     @class wxProcessEvent
 230     @wxheader{process.h}
 231
 232     A process event is sent when a process is terminated.
 233
 234     @library{wxbase}
 235     @category{events}
 236
 237     @seealso
 238     wxProcess, @ref overview_eventhandlingoverview "Event handling overview"
 239 */
 240 class wxProcessEvent : public wxEvent
 241 {
 242 public:
 243     /**
 244         Constructor. Takes a wxProcessObject or window id, a process id and an
 245         exit status.
 246     */
 247     wxProcessEvent(int id = 0, int pid = 0, int exitcode = 0);
 248
 249     /**
 250         Returns the exist status.
 251     */
 252     int GetExitCode();
 253
 254     /**
 255         Returns the process id.
 256     */
 257     int GetPid();
 258 };