Home2L - C/C++ API v1.4-0-g38cc (2024-05-25)
Smart Tools for a Private Home
|
Abstract base class for shells that can execute system commands.
Note: All methods (for one object) must be called from the same thread.
#include "base.H"
Public Member Functions | |
Execution control... | |
virtual bool | Start (const char *cmd, bool readStdErr=false)=0 |
Start command. More... | |
virtual bool | StartRestricted (const char *name, const char *args=NULL) |
Same as 'Start', but fetch the command from the environment. More... | |
virtual bool | IsRunning () |
Still running? | |
virtual void | Wait ()=0 |
Wait until current command completes. | |
virtual void | Kill (int sig=SIGTERM) |
Kill the current command nicely. This may not work for all types of shells. A Wait() invocation is required anyway afterwards. | |
int | ExitCode () |
Get the exit code of last command. | |
Simple running... | |
int | Run (const char *cmd, const char *input=NULL, CString *output=NULL) |
Run command 'cmd' synchronously and return its exit code. More... | |
Accessing stdin & stdout... | |
virtual void | CheckIO (bool *canWrite, bool *canRead, TTicks maxTime=-1)=0 |
Check whether the i/o channels can take/deliver data. More... | |
bool | WaitUntilReadable (TTicks maxTime=-1) |
Wait until output of the external command is readable. Be aware of potential deadlocks. This command can only be safely used if the external command does not wait for input. More... | |
bool | WaitUntilWritable (TTicks maxTime=-1) |
Wait until the external command can accept written input. Be aware of potential deadlocks. This command can only be safely used if the external command does not produce any output. More... | |
bool | Writable () |
Poll for writability (non-blocking). | |
virtual void | WriteLine (const char *line)=0 |
Blocking write, execution is guaranteed. To avoid blocking, run Writable() or CheckI() first. | |
void | WriteLine (CString *str) |
Write a line. | |
virtual void | WriteClose ()=0 |
Close the write channel. | |
bool | Readable () |
Poll for readability. | |
virtual bool | ReadLine (CString *str)=0 |
Non-Blocking read, returns 'true' on success. str can be NULL, in which case the line is ignored, given the reading was successul. | |
virtual bool | ReadClosed ()=0 |
Close the read channel. | |
|
pure virtual |
Start command.
cmd | The exact (and arbitrary) shell command. On Android, relative paths are prepended with HOME2L_ROOT. |
readStdErr | decides whether STDERR is redirected to STDIN and also returned via ReadLine() and friends. By default, it is left undirected. |
If a previous command is still running, Wait() is executed before. On error, a warning is printed and 'false' is returned. Only one command can be executed at a time. It can be understood that the Start() method includes an implicit Mutex-Lock operation, and the lock has been obtained (only) if 'true' is returned. The corresponding Mutex-Unlock operation is implied by calling Wait().
Implemented in CShellBare, and CShellSession.
|
virtual |
Same as 'Start', but fetch the command from the environment.
This way, only commands explicitly defined in the environment settings are allowed, which is a security improvment. The actual command is taken from the environment variable rc.cmd.<name>
. The command name may contain the placeholder "%s", which is replaced by args
. This mode of command definition is meant for remote network execution to avoid security holes.
int CShell::Run | ( | const char * | cmd, |
const char * | input = NULL , |
||
CString * | output = NULL |
||
) |
Run command 'cmd' synchronously and return its exit code.
The standard input is taken from 'input' and the output is writen to the string referred to by 'output'. This function is only appropriate for short running commands since the calling thread blocks until the command completes.
|
pure virtual |
Check whether the i/o channels can take/deliver data.
canWrite | may point to a variable that will be set, depending on whether at least one byte can be written to the external command. |
canRead | may point to a variable that will be set, depending on whether at least one byte can be read from the external command. |
maxTime | is the maximum waiting time in milliseconds. A value <0 lets it wait forever, a value 0 does not cause any waiting at all. |
If any of the two pointers 'canWrite' and 'canRead' is 'NULL', the caller indicates that he is not interested in the respective result. Hence, the method waits until the respective other channel is ready.
In situations, where CheckIO() would wait forever, it returns immediately with both flags set to 'false' (for example: read channel already closed, and canWrite == NULL
). Note: As long as both the read and the write channel are open, the caller (usually) must always write and read as much as possible. Otherwise, a deadlock may occur.
Implemented in CShellBare, and CShellSession.
|
inline |
|
inline |