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