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 2058 of file base.H.

#include "base.H"

Inheritance diagram for CShellSession:

Public Member Functions
Extra features ...
void	SetHost (const char *_host)
	Define a remote host; must be called before first Start() call.
const char *	Host ()
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

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().

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

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.

Implements CShell.

---

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

• common/base.H