Home2L - C/C++ API v1.4-0-g38cc (2024-05-25)
Smart Tools for a Private Home
List of all members
CShellSession Class Reference

Description

Session shell: Multiple commands are executed through one shell.

All commands are executed through a common command shell, which is (re-)opened by the 'Start' method and left open until 'Done' is called. Compared to a bare shell, this greatly improves efficiency if multiple commands have to be executed on a remote host.

Definition at line 2062 of file base.H.

#include "base.H"

Inheritance diagram for CShellSession:
Inheritance graph
[legend]

Public Member Functions

Extra features ...
void SetHost (const char *_host)
 Define a remote host; must be called before first Start() call.
 
const char * Host ()
 
bool HasHost ()
 
Execution control...
virtual bool Start (const char *cmd, bool readStdErr=false)
 Start command. More...
 
virtual void Wait ()
 Wait until current command completes.
 
Accessing stdin & stdout...
virtual void CheckIO (bool *canWrite, bool *canRead, TTicks maxTime=-1)
 Check whether the i/o channels can take/deliver data. More...
 
virtual void WriteLine (const char *line)
 Blocking write, execution is guaranteed. To avoid blocking, run Writable() or CheckI() first.
 
virtual void WriteClose ()
 Close the write channel.
 
virtual bool ReadLine (CString *str)
 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 ()
 Close the read channel.
 
int ReadFd ()
 Get FD to allow select() by owner with multiple scripts.
 
int WriteFd ()
 Get FD to allow select() by owner with multiple scripts.
 
- Public Member Functions inherited from CShell
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 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.
 
int Run (const char *cmd, const char *input=NULL, CString *output=NULL)
 Run command 'cmd' synchronously and return its exit code. 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).
 
void WriteLine (CString *str)
 Write a line.
 
bool Readable ()
 Poll for readability.
 

Member Function Documentation

◆ Start()

virtual bool CShellSession::Start ( const char *  cmd,
bool  readStdErr = false 
)
virtual

Start command.

Parameters
cmdThe exact (and arbitrary) shell command. On Android, relative paths are prepended with HOME2L_ROOT.
readStdErrdecides 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().

Implements CShell.

◆ CheckIO()

virtual void CShellSession::CheckIO ( bool *  canWrite,
bool *  canRead,
TTicks  maxTime = -1 
)
virtual

Check whether the i/o channels can take/deliver data.

Parameters
canWritemay point to a variable that will be set, depending on whether at least one byte can be written to the external command.
canReadmay point to a variable that will be set, depending on whether at least one byte can be read from the external command.
maxTimeis 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.

Implements CShell.


The documentation for this class was generated from the following file: