-rw-r--r-- | libopie/oprocess.h | 24 |
1 files changed, 15 insertions, 9 deletions
diff --git a/libopie/oprocess.h b/libopie/oprocess.h index bf5fe0e..f2853b0 100644 --- a/libopie/oprocess.h +++ b/libopie/oprocess.h | |||
@@ -37,25 +37,25 @@ | |||
37 | #include <qvaluelist.h> | 37 | #include <qvaluelist.h> |
38 | #include <qcstring.h> | 38 | #include <qcstring.h> |
39 | #include <qobject.h> | 39 | #include <qobject.h> |
40 | 40 | ||
41 | class QSocketNotifier; | 41 | class QSocketNotifier; |
42 | class OProcessPrivate; | 42 | class OProcessPrivate; |
43 | 43 | ||
44 | /** | 44 | /** |
45 | * Child process invocation, monitoring and control. | 45 | * Child process invocation, monitoring and control. |
46 | * | 46 | * |
47 | * @sect General usage and features | 47 | * @sect General usage and features |
48 | * | 48 | * |
49 | *This class allows a KDE application to start child processes without having | 49 | *This class allows a KDE and OPIE application to start child processes without having |
50 | *to worry about UN*X signal handling issues and zombie process reaping. | 50 | *to worry about UN*X signal handling issues and zombie process reaping. |
51 | * | 51 | * |
52 | *@see KProcIO | 52 | *@see KProcIO |
53 | * | 53 | * |
54 | *Basically, this class distinguishes three different ways of running | 54 | *Basically, this class distinguishes three different ways of running |
55 | *child processes: | 55 | *child processes: |
56 | * | 56 | * |
57 | *@li OProcess::DontCare -- The child process is invoked and both the child | 57 | *@li OProcess::DontCare -- The child process is invoked and both the child |
58 | *process and the parent process continue concurrently. | 58 | *process and the parent process continue concurrently. |
59 | * | 59 | * |
60 | *Starting a DontCare child process means that the application is | 60 | *Starting a DontCare child process means that the application is |
61 | *not interested in any notification to determine whether the | 61 | *not interested in any notification to determine whether the |
@@ -179,25 +179,31 @@ public: | |||
179 | * The application is notified when the subprocess dies. | 179 | * The application is notified when the subprocess dies. |
180 | */ | 180 | */ |
181 | NotifyOnExit, | 181 | NotifyOnExit, |
182 | /** | 182 | /** |
183 | * The application is suspended until the started process is finished. | 183 | * The application is suspended until the started process is finished. |
184 | */ | 184 | */ |
185 | Block }; | 185 | Block }; |
186 | 186 | ||
187 | /** | 187 | /** |
188 | * Constructor | 188 | * Constructor |
189 | */ | 189 | */ |
190 | OProcess(QObject *parent = 0, const char *name = 0); | 190 | OProcess(QObject *parent = 0, const char *name = 0); |
191 | /** | ||
192 | * Constructor | ||
193 | */ | ||
191 | OProcess(const QString &arg0, QObject *parent = 0, const char *name = 0); | 194 | OProcess(const QString &arg0, QObject *parent = 0, const char *name = 0); |
195 | /** | ||
196 | * Constructor | ||
197 | */ | ||
192 | OProcess(const QStringList &args, QObject *parent = 0, const char *name = 0); | 198 | OProcess(const QStringList &args, QObject *parent = 0, const char *name = 0); |
193 | 199 | ||
194 | /** | 200 | /** |
195 | *Destructor: | 201 | *Destructor: |
196 | * | 202 | * |
197 | * If the process is running when the destructor for this class | 203 | * If the process is running when the destructor for this class |
198 | * is called, the child process is killed with a SIGKILL, but | 204 | * is called, the child process is killed with a SIGKILL, but |
199 | * only if the run mode is not of type @p DontCare. | 205 | * only if the run mode is not of type @p DontCare. |
200 | * Processes started as @p DontCare keep running anyway. | 206 | * Processes started as @p DontCare keep running anyway. |
201 | */ | 207 | */ |
202 | virtual ~OProcess(); | 208 | virtual ~OProcess(); |
203 | 209 | ||
@@ -401,33 +407,33 @@ public: | |||
401 | * Controls whether the started process should drop any | 407 | * Controls whether the started process should drop any |
402 | * setuid/segid privileges or whether it should keep them | 408 | * setuid/segid privileges or whether it should keep them |
403 | * | 409 | * |
404 | * The default is @p false : drop privileges | 410 | * The default is @p false : drop privileges |
405 | */ | 411 | */ |
406 | void setRunPrivileged(bool keepPrivileges); | 412 | void setRunPrivileged(bool keepPrivileges); |
407 | 413 | ||
408 | /** | 414 | /** |
409 | * Returns whether the started process will drop any | 415 | * Returns whether the started process will drop any |
410 | * setuid/segid privileges or whether it will keep them | 416 | * setuid/segid privileges or whether it will keep them |
411 | */ | 417 | */ |
412 | bool runPrivileged() const; | 418 | bool runPrivileged() const; |
413 | 419 | ||
414 | /** | 420 | /** |
415 | * Modifies the environment of the process to be started. | 421 | * Modifies the environment of the process to be started. |
416 | * This function must be called before starting the process. | 422 | * This function must be called before starting the process. |
417 | */ | 423 | */ |
418 | void setEnvironment(const QString &name, const QString &value); | 424 | void setEnvironment(const QString &name, const QString &value); |
419 | 425 | ||
420 | /** | 426 | /** |
421 | * Changes the current working directory (CWD) of the process | 427 | * Changes the current working directory (CWD) of the process |
422 | * to be started. | 428 | * to be started. |
423 | * This function must be called before starting the process. | 429 | * This function must be called before starting the process. |
424 | */ | 430 | */ |
425 | void setWorkingDirectory(const QString &dir); | 431 | void setWorkingDirectory(const QString &dir); |
426 | 432 | ||
427 | /** | 433 | /** |
428 | * Specify whether to start the command via a shell or directly. | 434 | * Specify whether to start the command via a shell or directly. |
429 | * The default is to start the command directly. | 435 | * The default is to start the command directly. |
430 | * If @p useShell is true @p shell will be used as shell, or | 436 | * If @p useShell is true @p shell will be used as shell, or |
431 | * if shell is empty, the standard shell is used. | 437 | * if shell is empty, the standard shell is used. |
432 | * @p quote A flag indicating whether to quote the arguments. | 438 | * @p quote A flag indicating whether to quote the arguments. |
433 | * | 439 | * |
@@ -443,25 +449,25 @@ public: | |||
443 | * user-provided file names which may contain spaces or quotes. | 449 | * user-provided file names which may contain spaces or quotes. |
444 | * It also prevents expansion of wild cards and environment variables. | 450 | * It also prevents expansion of wild cards and environment variables. |
445 | */ | 451 | */ |
446 | static QString quote(const QString &arg); | 452 | static QString quote(const QString &arg); |
447 | 453 | ||
448 | /** | 454 | /** |
449 | * Detaches OProcess from child process. All communication is closed. | 455 | * Detaches OProcess from child process. All communication is closed. |
450 | * No exit notification is emitted any more for the child process. | 456 | * No exit notification is emitted any more for the child process. |
451 | * Deleting the OProcess will no longer kill the child process. | 457 | * Deleting the OProcess will no longer kill the child process. |
452 | * Note that the current process remains the parent process of the | 458 | * Note that the current process remains the parent process of the |
453 | * child process. | 459 | * child process. |
454 | */ | 460 | */ |
455 | void detach(); | 461 | void detach(); |
456 | 462 | ||
457 | 463 | ||
458 | 464 | ||
459 | signals: | 465 | signals: |
460 | 466 | ||
461 | /** | 467 | /** |
462 | * Emitted after the process has terminated when | 468 | * Emitted after the process has terminated when |
463 | * the process was run in the @p NotifyOnExit (==default option to | 469 | * the process was run in the @p NotifyOnExit (==default option to |
464 | * @ref start()) or the @ref Block mode. | 470 | * @ref start()) or the @ref Block mode. |
465 | **/ | 471 | **/ |
466 | void processExited(OProcess *proc); | 472 | void processExited(OProcess *proc); |
467 | 473 | ||
@@ -477,33 +483,33 @@ signals: | |||
477 | * @param buffer The data received. | 483 | * @param buffer The data received. |
478 | * @param buflen The number of bytes that are available. | 484 | * @param buflen The number of bytes that are available. |
479 | * | 485 | * |
480 | * You should copy the information contained in @p buffer to your private | 486 | * You should copy the information contained in @p buffer to your private |
481 | * data structures before returning from this slot. | 487 | * data structures before returning from this slot. |
482 | **/ | 488 | **/ |
483 | void receivedStdout(OProcess *proc, char *buffer, int buflen); | 489 | void receivedStdout(OProcess *proc, char *buffer, int buflen); |
484 | 490 | ||
485 | /** | 491 | /** |
486 | * Emitted when output from the child process has | 492 | * Emitted when output from the child process has |
487 | * been received on stdout. | 493 | * been received on stdout. |
488 | * | 494 | * |
489 | * To actually get these signals, the respective communications link | 495 | * To actually get these signals, the respective communications link |
490 | * (stdout/stderr) has to be turned on in @ref start() and the | 496 | * (stdout/stderr) has to be turned on in @ref start() and the |
491 | * @p NoRead flag should have been passed. | 497 | * @p NoRead flag should have been passed. |
492 | * | 498 | * |
493 | * You will need to explicitly call resume() after your call to start() | 499 | * You will need to explicitly call resume() after your call to start() |
494 | * to begin processing data from the child process's stdout. This is | 500 | * to begin processing data from the child process's stdout. This is |
495 | * to ensure that this signal is not emitted when no one is connected | 501 | * to ensure that this signal is not emitted when no one is connected |
496 | * to it, otherwise this signal will not be emitted. | 502 | * to it, otherwise this signal will not be emitted. |
497 | * | 503 | * |
498 | * The data still has to be read from file descriptor @p fd. | 504 | * The data still has to be read from file descriptor @p fd. |
499 | **/ | 505 | **/ |
500 | void receivedStdout(int fd, int &len); | 506 | void receivedStdout(int fd, int &len); |
501 | 507 | ||
502 | 508 | ||
503 | /** | 509 | /** |
504 | * Emitted, when output from the child process has | 510 | * Emitted, when output from the child process has |
505 | * been received on stderr. | 511 | * been received on stderr. |
506 | * To actually get | 512 | * To actually get |
507 | * these signals, the respective communication link (stdout/stderr) | 513 | * these signals, the respective communication link (stdout/stderr) |
508 | * has to be turned on in @ref start(). | 514 | * has to be turned on in @ref start(). |
509 | * | 515 | * |
@@ -541,25 +547,25 @@ protected slots: | |||
541 | */ | 547 | */ |
542 | 548 | ||
543 | /** | 549 | /** |
544 | * Called when another bulk of data can be sent to the child's | 550 | * Called when another bulk of data can be sent to the child's |
545 | * stdin. If there is no more data to be sent to stdin currently | 551 | * stdin. If there is no more data to be sent to stdin currently |
546 | * available, this function must disable the QSocketNotifier "innot". | 552 | * available, this function must disable the QSocketNotifier "innot". |
547 | */ | 553 | */ |
548 | void slotSendData(int dummy); | 554 | void slotSendData(int dummy); |
549 | 555 | ||
550 | protected: | 556 | protected: |
551 | 557 | ||
552 | /** | 558 | /** |
553 | * Sets up the environment according to the data passed via | 559 | * Sets up the environment according to the data passed via |
554 | * setEnvironment(...) | 560 | * setEnvironment(...) |
555 | */ | 561 | */ |
556 | void setupEnvironment(); | 562 | void setupEnvironment(); |
557 | 563 | ||
558 | /** | 564 | /** |
559 | * The list of the process' command line arguments. The first entry | 565 | * The list of the process' command line arguments. The first entry |
560 | * in this list is the executable itself. | 566 | * in this list is the executable itself. |
561 | */ | 567 | */ |
562 | QValueList<QCString> arguments; | 568 | QValueList<QCString> arguments; |
563 | /** | 569 | /** |
564 | * How to run the process (Block, NotifyOnExit, DontCare). You should | 570 | * How to run the process (Block, NotifyOnExit, DontCare). You should |
565 | * not modify this data member directly from derived classes. | 571 | * not modify this data member directly from derived classes. |
@@ -703,25 +709,25 @@ protected: | |||
703 | int input_sent; // # of bytes already transmitted | 709 | int input_sent; // # of bytes already transmitted |
704 | int input_total; // total length of input_data | 710 | int input_total; // total length of input_data |
705 | 711 | ||
706 | /** | 712 | /** |
707 | * @ref OProcessController is a friend of OProcess because it has to have | 713 | * @ref OProcessController is a friend of OProcess because it has to have |
708 | * access to various data members. | 714 | * access to various data members. |
709 | */ | 715 | */ |
710 | friend class OProcessController; | 716 | friend class OProcessController; |
711 | 717 | ||
712 | 718 | ||
713 | private: | 719 | private: |
714 | /** | 720 | /** |
715 | * Searches for a valid shell. | 721 | * Searches for a valid shell. |
716 | * Here is the algorithm used for finding an executable shell: | 722 | * Here is the algorithm used for finding an executable shell: |
717 | * | 723 | * |
718 | * @li Try the executable pointed to by the "SHELL" environment | 724 | * @li Try the executable pointed to by the "SHELL" environment |
719 | * variable with white spaces stripped off | 725 | * variable with white spaces stripped off |
720 | * | 726 | * |
721 | * @li If your process runs with uid != euid or gid != egid, a shell | 727 | * @li If your process runs with uid != euid or gid != egid, a shell |
722 | * not listed in /etc/shells will not used. | 728 | * not listed in /etc/shells will not used. |
723 | * | 729 | * |
724 | * @li If no valid shell could be found, "/bin/sh" is used as a last resort. | 730 | * @li If no valid shell could be found, "/bin/sh" is used as a last resort. |
725 | */ | 731 | */ |
726 | QCString searchShell(); | 732 | QCString searchShell(); |
727 | 733 | ||