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