This concrete class provides the implementation of Command Processor for a TShell engine. More...

Detailed Description

This concrete class provides the implementation of Command Processor for a TShell engine.

The implementation assumes a single threaded model, i.e. the Command Processor and all of its commands run in a single thread. It is APPLICATION's responsibility to provide any desired multi-threaded support. There are two caveats to the single-threaded model:

o The output of the commands are mutex protected.  This allows the
  Output stream to be 'shared' with other sub-systems and/or
  threads (e.g. the shell shares the same Output stream as the
  Cpl::System::Trace logging output).

o The stop() method can be called safely from other threads.

Commands have the following syntax:

o A command starts with a printable ASCII character and ends with
  a newline.

o Non-printable ASCII characters are not allowed.

o Any line that starts with a '#' is treated as comment line and
  is ignored.

o Format of a command is: verb [arg]*  where the verb and arguments
  are separated by spaces.  Arguments can contain spaces character
  by enclosing the argument with double quote characters.  A double
  quote character can be embedded inside a quoted string by preceding
  it the double quote character with the escape character.  The escape
  character can be embedded by escaping the escape character.

The USE_CPL_TSHELL_PROCESSOR_SILENT_WHEN_PUBLIC switch is use to alter the TShell's output behavior - to not 'say anything' until a user has successfully been authenticated (using the 'User' command

HOW TO Enable Security:

- Set OPTION_TSHELL_CMD_COMMAND_DEFAULT_PERMISSION_LEVEL to something
  other than ePUBLIC.  This will be the permission for all legacy (i.e.
  not Security aware) TShell commands

- Recommend turning on the switch: USE_CPL_TSHELL_PROCESSOR_SILENT_WHEN_PUBLIC

- Include the Cpl::TShell::Cmd::User command and provide an 
  implementation of the Cpl::TShell::Security interface (that is passed 
  to the command's constructor).

- Optionally include new security aware commands

#include <Processor.h>

Inheritance diagram for Cpl::TShell::Processor:

[legend]

Collaboration diagram for Cpl::TShell::Processor:

[legend]

Public Member Functions
	Processor (Cpl::Container::Map< Command > &commands, Cpl::Text::Frame::StreamDecoder &deframer, Cpl::Text::Frame::StreamEncoder &framer, Cpl::System::Mutex &outputLock, char commentChar='#', char argEscape='`', char argDelimiter=' ', char argQuote='"', char argTerminator='\n', Security::Permission_T initialPermissionLevel = Security::ePUBLIC )
	Constructor.

bool	start (Cpl::Io::Input &infd, Cpl::Io::Output &outfd, bool blocking=true) noexcept
	See Cpl::TShell::ProcessorApi.

int	poll () noexcept
	See Cpl::TShell::ProcessorApi.

void	requestStop () noexcept
	See Cpl::TShell::ProcessorApi.

char	getEscapeChar () noexcept
	See Cpl::TShell::ProcessorApi.

char	getDelimiterChar () noexcept
	See Cpl::TShell::ProcessorApi.

char	getQuoteChar () noexcept
	See Cpl::TShell::ProcessorApi.

char	getTerminatorChar () noexcept
	See Cpl::TShell::ProcessorApi.

Cpl::Container::Map< Command > &	getCommands () noexcept
	See Cpl::TShell::Context_.

bool	writeFrame (const char *text) noexcept
	See Cpl::TShell::Context_.

bool	writeFrame (const char *text, size_t maxBytes) noexcept
	See Cpl::TShell::Context_.

Cpl::Text::String &	getOutputBuffer () noexcept
	See Cpl::TShell::Context_.

Cpl::Text::String &	getTokenBuffer () noexcept
	See Cpl::TShell::Context_.

Cpl::Text::String &	getTokenBuffer2 () noexcept
	See Cpl::TShell::Context_.

bool	oobRead (void *buffer, int numBytes, int &bytesRead) noexcept
	See Cpl::TShell::Context_.

Security::Permission_T	getUserPermissionLevel () const noexcept
	See Cpl::TShell::Context_.

Security::Permission_T	setUserPermissionLevel (Security::Permission_T newPermissionLevel) noexcept
	See Cpl::TShell::Context_.

Public Member Functions inherited from Cpl::TShell::Context_
virtual	~Context_ ()
	Virtual destructor.

Public Member Functions inherited from Cpl::TShell::ProcessorApi
virtual	~ProcessorApi ()
	Virtual destructor.

Protected Member Functions
virtual Command::Result_T	executeCommand (char *deframedInput, Cpl::Io::Output &outfd) noexcept
	Helper method that attempts to execute the content of the de-framed/decoded 'inputString'.

bool	outputCommandError (Command::Result_T result, const char *deframedInput) noexcept
	Helper method.

int	getAndProcessFrame (Cpl::Io::Output &outfd) noexcept
	Helper method that performs a 'single' read cycle of the input stream.

virtual int	readInput (size_t &frameSize) noexcept
	Helper method that executes the decoder, i.e.

Protected Attributes
Cpl::Container::Map< Command > &	m_commands
	Command list.

Cpl::Text::Frame::StreamDecoder &	m_deframer
	Raw input de-framer.

Cpl::Text::Frame::StreamEncoder &	m_framer
	Output framer handle.

Cpl::System::Mutex &	m_outLock
	Output lock.

Security::Permission_T	m_userPermLevel
	User's permission level.

char	m_comment
	Comment character.

char	m_esc
	Argument Escape character.

char	m_del
	Argument delimiter.

char	m_quote
	Argument quote character.

char	m_term
	Argument terminator character.

bool	m_writeCommandPrompt
	Set to true when 'command prompt' should be outputted.

size_t	m_frameSize
	Current frame size.

bool	m_running
	My run state.

char	m_inputBuffer [OPTION_CPL_TSHELL_PROCESSOR_INPUT_SIZE+1]
	Input Frame buffer.

Cpl::Text::FString< OPTION_CPL_TSHELL_PROCESSOR_OUTPUT_SIZE >	m_outputBuffer
	Buffer that is used to construct output messages.

Cpl::Text::FString< OPTION_CPL_TSHELL_PROCESSOR_INPUT_SIZE >	m_tokenBuffer
	Shared token work buffer.

Cpl::Text::FString< OPTION_CPL_TSHELL_PROCESSOR_INPUT_SIZE >	m_tokenBuffer2
	Shared token work buffer.

Constructor & Destructor Documentation

◆ Processor()

Cpl::TShell::Processor::Processor	(	Cpl::Container::Map< Command > &	commands,
		Cpl::Text::Frame::StreamDecoder &	deframer,
		Cpl::Text::Frame::StreamEncoder &	framer,
		Cpl::System::Mutex &	outputLock,
		char	commentChar = `'#'`,
		char	argEscape = '`',
		char	argDelimiter = `' '`,
		char	argQuote = `'"'`,
		char	argTerminator = `'\n'`,
		Security::Permission_T	initialPermissionLevel = `Security::ePUBLIC`
	)

Constructor.

Parameters

commands	Set of supported commands
deframer	Frame decoder used to identify individual command strings within the raw Input stream
framer	Frame encoder used to encapsulate the output of command in the Output stream.
outputLock	Mutex to be used for ensuring the atomic output of the commands.
commentChar	The comment character used to indicate that the input string is a comment and should not be executed.
argEscape	Escape character to be used when escaping double quote characters inside a quoted argument.
argDelimiter	The delimiter character used to separate the command verb and arguments.
argQuote	The quote character used to 'double quote' a argument string.
argTerminator	The command terminator character.
initialPermissionLevel	The initial minimum permission level that a user needs to issue command(s)

Member Function Documentation

◆ executeCommand()

virtual Command::Result_T Cpl::TShell::Processor::executeCommand	(	char *	deframedInput,
		Cpl::Io::Output &	outfd
	)

protectedvirtualnoexcept

Helper method that attempts to execute the content of the de-framed/decoded 'inputString'.

The method returns the result code of the execute command. If 'inputString' is not a valid command, then the appropriate error/result code is returned.

◆ getAndProcessFrame()

int Cpl::TShell::Processor::getAndProcessFrame ( Cpl::Io::Output & outfd )

protectednoexcept

Helper method that performs a 'single' read cycle of the input stream.

Returns 0 if successful. Returns 1 if exiting. Returns -1 on error

◆ getCommands()

Cpl::Container::Map< Command > & Cpl::TShell::Processor::getCommands ( )

virtualnoexcept

See Cpl::TShell::Context_.

Implements Cpl::TShell::Context_.

◆ getDelimiterChar()

char Cpl::TShell::Processor::getDelimiterChar ( )

virtualnoexcept

See Cpl::TShell::ProcessorApi.

Implements Cpl::TShell::ProcessorApi.

◆ getEscapeChar()

char Cpl::TShell::Processor::getEscapeChar ( )

virtualnoexcept

See Cpl::TShell::ProcessorApi.

Implements Cpl::TShell::ProcessorApi.

◆ getOutputBuffer()

Cpl::Text::String & Cpl::TShell::Processor::getOutputBuffer ( )

virtualnoexcept

See Cpl::TShell::Context_.

Implements Cpl::TShell::Context_.

◆ getQuoteChar()

char Cpl::TShell::Processor::getQuoteChar ( )

virtualnoexcept

See Cpl::TShell::ProcessorApi.

Implements Cpl::TShell::ProcessorApi.

◆ getTerminatorChar()

char Cpl::TShell::Processor::getTerminatorChar ( )

virtualnoexcept

See Cpl::TShell::ProcessorApi.

Implements Cpl::TShell::ProcessorApi.

◆ getTokenBuffer()

Cpl::Text::String & Cpl::TShell::Processor::getTokenBuffer ( )

virtualnoexcept

See Cpl::TShell::Context_.

Implements Cpl::TShell::Context_.

◆ getTokenBuffer2()

Cpl::Text::String & Cpl::TShell::Processor::getTokenBuffer2 ( )

virtualnoexcept

See Cpl::TShell::Context_.

Implements Cpl::TShell::Context_.

◆ getUserPermissionLevel()

Security::Permission_T Cpl::TShell::Processor::getUserPermissionLevel ( ) const

virtualnoexcept

See Cpl::TShell::Context_.

Implements Cpl::TShell::Context_.

◆ oobRead()

bool Cpl::TShell::Processor::oobRead	(	void *	buffer,
		int	numBytes,
		int &	bytesRead
	)

virtualnoexcept

See Cpl::TShell::Context_.

Implements Cpl::TShell::Context_.

◆ outputCommandError()

bool Cpl::TShell::Processor::outputCommandError	(	Command::Result_T	result,
		const char *	deframedInput
	)

protectednoexcept

Helper method.

◆ poll()

int Cpl::TShell::Processor::poll ( )

virtualnoexcept

See Cpl::TShell::ProcessorApi.

Implements Cpl::TShell::ProcessorApi.

◆ readInput()

virtual int Cpl::TShell::Processor::readInput ( size_t & frameSize )

protectedvirtualnoexcept

Helper method that executes the decoder, i.e.

logic to parse the incoming text. Returns 1 if a full/valid frame was found. Returns 0 if input frame is incomplete. Return -1 if an error occurred.

Reimplemented in Cpl::TShell::PolledProcessor.

◆ requestStop()

void Cpl::TShell::Processor::requestStop ( )

virtualnoexcept

See Cpl::TShell::ProcessorApi.

Implements Cpl::TShell::ProcessorApi.

◆ setUserPermissionLevel()

Security::Permission_T Cpl::TShell::Processor::setUserPermissionLevel ( Security::Permission_T newPermissionLevel )

virtualnoexcept

See Cpl::TShell::Context_.

Implements Cpl::TShell::Context_.

◆ start()

bool Cpl::TShell::Processor::start	(	Cpl::Io::Input &	infd,
		Cpl::Io::Output &	outfd,
		bool	blocking = `true`
	)

virtualnoexcept

See Cpl::TShell::ProcessorApi.

Implements Cpl::TShell::ProcessorApi.

◆ writeFrame() [1/2]

bool Cpl::TShell::Processor::writeFrame ( const char * text )

virtualnoexcept

See Cpl::TShell::Context_.

Implements Cpl::TShell::Context_.

◆ writeFrame() [2/2]

bool Cpl::TShell::Processor::writeFrame	(	const char *	text,
		size_t	maxBytes
	)

virtualnoexcept

See Cpl::TShell::Context_.

Implements Cpl::TShell::Context_.

Member Data Documentation

◆ m_commands

Cpl::Container::Map<Command>& Cpl::TShell::Processor::m_commands

protected

Command list.

◆ m_comment

char Cpl::TShell::Processor::m_comment

protected

Comment character.

◆ m_deframer

Cpl::Text::Frame::StreamDecoder& Cpl::TShell::Processor::m_deframer

protected

Raw input de-framer.

◆ m_del

char Cpl::TShell::Processor::m_del

protected

Argument delimiter.

◆ m_esc

char Cpl::TShell::Processor::m_esc

protected

Argument Escape character.

◆ m_framer

Cpl::Text::Frame::StreamEncoder& Cpl::TShell::Processor::m_framer

protected

Output framer handle.

◆ m_frameSize

size_t Cpl::TShell::Processor::m_frameSize

protected

Current frame size.

◆ m_inputBuffer

char Cpl::TShell::Processor::m_inputBuffer[OPTION_CPL_TSHELL_PROCESSOR_INPUT_SIZE+1]

protected

Input Frame buffer.

◆ m_outLock

Cpl::System::Mutex& Cpl::TShell::Processor::m_outLock

protected

Output lock.

◆ m_outputBuffer

Cpl::Text::FString<OPTION_CPL_TSHELL_PROCESSOR_OUTPUT_SIZE> Cpl::TShell::Processor::m_outputBuffer

protected

Buffer that is used to construct output messages.

◆ m_quote

char Cpl::TShell::Processor::m_quote

protected

Argument quote character.

◆ m_running

bool Cpl::TShell::Processor::m_running

protected

My run state.

◆ m_term

char Cpl::TShell::Processor::m_term

protected

Argument terminator character.

◆ m_tokenBuffer

Cpl::Text::FString<OPTION_CPL_TSHELL_PROCESSOR_INPUT_SIZE> Cpl::TShell::Processor::m_tokenBuffer

protected

Shared token work buffer.

◆ m_tokenBuffer2

Cpl::Text::FString<OPTION_CPL_TSHELL_PROCESSOR_INPUT_SIZE> Cpl::TShell::Processor::m_tokenBuffer2

protected

Shared token work buffer.

◆ m_userPermLevel

Security::Permission_T Cpl::TShell::Processor::m_userPermLevel

protected

User's permission level.

◆ m_writeCommandPrompt

bool Cpl::TShell::Processor::m_writeCommandPrompt

protected

Set to true when 'command prompt' should be outputted.

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

Cpl/TShell/Processor.h

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ Processor()

Member Function Documentation

◆ executeCommand()

◆ getAndProcessFrame()

◆ getCommands()

◆ getDelimiterChar()

◆ getEscapeChar()

◆ getOutputBuffer()

◆ getQuoteChar()

◆ getTerminatorChar()

◆ getTokenBuffer()

◆ getTokenBuffer2()

◆ getUserPermissionLevel()

◆ oobRead()

◆ outputCommandError()

◆ poll()

◆ readInput()

◆ requestStop()

◆ setUserPermissionLevel()

◆ start()

◆ writeFrame() [1/2]

◆ writeFrame() [2/2]

Member Data Documentation

◆ m_commands

◆ m_comment

◆ m_deframer

◆ m_del

◆ m_esc

◆ m_framer

◆ m_frameSize

◆ m_inputBuffer

◆ m_outLock

◆ m_outputBuffer

◆ m_quote

◆ m_running

◆ m_term

◆ m_tokenBuffer

◆ m_tokenBuffer2

◆ m_userPermLevel

◆ m_writeCommandPrompt