interface/process.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        process.h
   3 // Purpose:     interface of wxProcess
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Signal constants used by wxProcess.
  11 */
  12 enum wxSignal
  13 {
  14     wxSIGNONE = 0,  //!< verify if the process exists under Unix
  15     wxSIGHUP,
  16     wxSIGINT,
  17     wxSIGQUIT,
  18     wxSIGILL,
  19     wxSIGTRAP,
  20     wxSIGABRT,
  21     wxSIGEMT,
  22     wxSIGFPE,
  23     wxSIGKILL,      //!< forcefully kill, dangerous!
  24     wxSIGBUS,
  25     wxSIGSEGV,
  26     wxSIGSYS,
  27     wxSIGPIPE,
  28     wxSIGALRM,
  29     wxSIGTERM       //!< terminate the process gently
  30 };
  31
  32 /**
  33     Return values for wxProcess::Kill.
  34 */
  35 enum wxKillError
  36 {
  37     wxKILL_OK,              //!< no error
  38     wxKILL_BAD_SIGNAL,      //!< no such signal
  39     wxKILL_ACCESS_DENIED,   //!< permission denied
  40     wxKILL_NO_PROCESS,      //!< no such process
  41     wxKILL_ERROR            //!< another, unspecified error
  42 };
  43
  44
  45 /**
  46     @class wxProcess
  47     @wxheader{process.h}
  48
  49     The objects of this class are used in conjunction with the ::wxExecute() function.
  50     When a wxProcess object is passed to ::wxExecute(), its OnTerminate() virtual method
  51     is called when the process terminates. This allows the program to be (asynchronously)
  52     notified about the process termination and also retrieve its exit status which is
  53     unavailable from ::wxExecute() in the case of asynchronous execution.
  54
  55     @note If the process termination notification is processed by the
  56     parent, it is responsible for deleting the wxProcess object which sent it.
  57     However, if it is not processed, the object will delete itself and so the
  58     library users should only delete those objects whose notifications have been
  59     processed (and call wxProcess::Detach for others).
  60
  61     wxProcess also supports IO redirection of the child process. For this, you have
  62     to call its Redirect() method before passing it to ::wxExecute().
  63     If the child process was launched successfully, GetInputStream(), GetOutputStream()
  64     and GetErrorStream() can then be used to retrieve the streams corresponding to the
  65     child process standard output, input and error output respectively.
  66
  67     @library{wxbase}
  68     @category{appmanagement}
  69
  70     @see wxExecute(), @ref page_samples_exec "exec sample"
  71 */
  72 class wxProcess : public wxEvtHandler
  73 {
  74 public:
  75     /**
  76         Constructs a process object. @a id is only used in the case you want to
  77         use wxWidgets events. It identifies this object, or another window that will
  78         receive the event.
  79
  80         If the @a parent parameter is different from @NULL, it will receive
  81         a @c wxEVT_END_PROCESS notification event (you should insert @c EVT_END_PROCESS
  82         macro in the event table of the parent to handle it) with the given @a id.
  83
  84         @param parent
  85             The event handler parent.
  86         @param id
  87             id of an event.
  88     */
  89     wxProcess(wxEvtHandler* parent = NULL, int id = -1);
  90
  91     /**
  92         Creates an object without any associated parent (and hence no id neither)
  93         but allows to specify the @a flags which can have the value of
  94         @c wxPROCESS_DEFAULT or @c wxPROCESS_REDIRECT.
  95
  96         Specifying the former value has no particular effect while using the latter
  97         one is equivalent to calling Redirect().
  98     */
  99     wxProcess(int flags);
 100
 101     /**
 102         Destroys the wxProcess object.
 103     */
 104     ~wxProcess();
 105
 106     /**
 107         Closes the output stream (the one connected to the stdin of the child
 108         process).
 109
 110         This function can be used to indicate to the child process that
 111         there is no more data to be read - usually, a filter program will only
 112         terminate when the input stream is closed.
 113     */
 114     void CloseOutput();
 115
 116     /**
 117         Normally, a wxProcess object is deleted by its parent when it receives the
 118         notification about the process termination. However, it might happen that the
 119         parent object is destroyed before the external process is terminated (e.g. a
 120         window from which this external process was launched is closed by the user)
 121         and in this case it @b should not delete the wxProcess object, but
 122         @b should call Detach() instead. After the wxProcess object is detached
 123         from its parent, no notification events will be sent to the parent and the
 124         object will delete itself upon reception of the process termination
 125         notification.
 126     */
 127     void Detach();
 128
 129     /**
 130         Returns @true if the given process exists in the system.
 131
 132         @see Kill(), @ref page_samples_exec "Exec sample"
 133     */
 134     static bool Exists(int pid);
 135
 136     /**
 137         Returns an input stream which corresponds to the standard error output (stderr)
 138         of the child process.
 139     */
 140     wxInputStream* GetErrorStream() const;
 141
 142     /**
 143         It returns an input stream corresponding to the standard output stream of the
 144         subprocess. If it is @NULL, you have not turned on the redirection.
 145
 146         @see Redirect().
 147     */
 148     wxInputStream* GetInputStream() const;
 149
 150     /**
 151         It returns an output stream correspoding to the input stream of the subprocess.
 152         If it is @NULL, you have not turned on the redirection.
 153
 154         @see Redirect().
 155     */
 156     wxOutputStream* GetOutputStream() const;
 157
 158     /**
 159         Returns the process ID of the process launched by Open().
 160     */
 161     long GetPid() const;
 162
 163     /**
 164         Returns @true if there is data to be read on the child process standard
 165         error stream.
 166
 167         @see IsInputAvailable()
 168     */
 169     bool IsErrorAvailable() const;
 170
 171     /**
 172         Returns @true if there is data to be read on the child process standard
 173         output stream.
 174
 175         This allows to write simple (and extremely inefficient) polling-based code
 176         waiting for a better mechanism in future wxWidgets versions.
 177         See the @ref page_samples_exec "exec sample" for an example of using this
 178         function.
 179
 180         @see IsInputOpened()
 181     */
 182     bool IsInputAvailable() const;
 183
 184     /**
 185         Returns @true if the child process standard output stream is opened.
 186     */
 187     bool IsInputOpened() const;
 188
 189     /**
 190         Send the specified signal to the given process. Possible signal values
 191         can be one of the ::wxSignal enumeration values.
 192
 193         @c wxSIGNONE, @c wxSIGKILL and @c wxSIGTERM have the same meaning
 194         under both Unix and Windows but all the other signals are equivalent to
 195         @c wxSIGTERM under Windows.
 196
 197         The @a flags parameter can be @c wxKILL_NOCHILDREN (the default),
 198         or @c wxKILL_CHILDREN, in which case the child processes of this
 199         process will be killed too. Note that under Unix, for @c wxKILL_CHILDREN
 200         to work you should have created the process passing @c wxEXEC_MAKE_GROUP_LEADER.
 201
 202         Returns the element of ::wxKillError enum.
 203
 204         @see Exists(), wxKill(), @ref page_samples_exec "Exec sample"
 205     */
 206     static wxKillError Kill(int pid, wxSignal signal = wxSIGNONE,
 207                             int flags = wxKILL_NOCHILDREN);
 208
 209     /**
 210         It is called when the process with the pid @a pid finishes.
 211         It raises a wxWidgets event when it isn't overridden.
 212
 213         @param pid
 214             The pid of the process which has just terminated.
 215         @param status
 216             The exit code of the process.
 217     */
 218     void OnTerminate(int pid, int status);
 219
 220     /**
 221         This static method replaces the standard @c popen() function: it launches
 222         the process specified by the @a cmd parameter and returns the wxProcess
 223         object which can be used to retrieve the streams connected to the standard
 224         input, output and error output of the child process.
 225
 226         If the process couldn't be launched, @NULL is returned.
 227
 228         @remarks
 229         In any case the returned pointer should @b not be deleted, rather the process
 230         object will be destroyed automatically when the child process terminates. This
 231         does mean that the child process should be told to quit before the main program
 232         exits to avoid memory leaks.
 233
 234         @param cmd
 235             The command to execute, including optional arguments.
 236         @param flags
 237             The flags to pass to ::wxExecute().
 238             Note: @c wxEXEC_SYNC should not be used.
 239
 240         @returns A pointer to new wxProcess object or @NULL on error.
 241
 242         @see ::wxExecute()
 243     */
 244     static wxProcess* Open(const wxString& cmd,
 245                            int flags = wxEXEC_ASYNC);
 246
 247     /**
 248         Turns on redirection.
 249
 250         ::wxExecute() will try to open a couple of pipes to catch the subprocess stdio.
 251         The caught input stream is returned by GetOutputStream() as a non-seekable stream.
 252         The caught output stream is returned by GetInputStream() as a non-seekable stream.
 253     */
 254     void Redirect();
 255 };
 256
 257
 258
 259 /**
 260     @class wxProcessEvent
 261     @wxheader{process.h}
 262
 263     A process event is sent when a process is terminated.
 264
 265     @beginEventTable{wxProcessEvent}
 266     @event{EVT_END_PROCESS(id, func)}
 267            Process a @c wxEVT_END_PROCESS event. @a id is the identifier of the process
 268            object (the id passed to the wxProcess constructor) or a window to receive
 269            the event.
 270     @endEventTable
 271
 272     @library{wxbase}
 273     @category{events}
 274
 275     @see wxProcess, @ref overview_eventhandling
 276 */
 277 class wxProcessEvent : public wxEvent
 278 {
 279 public:
 280     /**
 281         Constructor.
 282
 283         Takes a wxProcessObject or window id, a process id and an exit status.
 284     */
 285     wxProcessEvent(int id = 0, int pid = 0, int exitcode = 0);
 286
 287     /**
 288         Returns the exist status.
 289     */
 290     int GetExitCode();
 291
 292     /**
 293         Returns the process id.
 294     */
 295     int GetPid() const;
 296 };
 297