Poco::OSP

namespace Shell

Overview

Functions: AbstractCommand, Command, CommandProcessor, ShellConnection, commandName, context, createCommand, defineOptions, displayHelp, execute, executeImpl, handleHelp, handleOption, init, initImpl, operator =, options, processOptions, stopOptionsProcessing, ~AbstractCommand, ~Command, ~CommandFactory

Functions

AbstractCommand

AbstractCommand(
    const std::string & description,
    const std::string & usage
);

Creates the AbstractCommand. Creates the AbstractCommand, using the given description and usage hint.

The given description and usage hint is used in the help text given if the command is invoked with the —help option.

Command

Command();

Creates the Command.

CommandProcessor

CommandProcessor(
    Poco::OSP::BundleContext::Ptr pContext
);

Creates the CommandProcessor, using the given bundle context.

ShellConnection

ShellConnection(
    const Poco::Net::StreamSocket & s,
    CommandProcessor & processor,
    const std::string & authServiceName
);

Creates the ShellConnection.

commandName

const std::string & commandName() const;

Returns the command name.

context

Poco::OSP::BundleContext::Ptr context() const;

Returns the context. The pointer is guaranteed to be valid.

createCommand virtual

virtual Command * createCommand() = 0;

Create a Command object.

defineOptions virtual

virtual void defineOptions(
    Poco::Util::OptionSet & options
);

Called before command line processing begins. If a Command wants to support command line arguments, it must override this method and call the base class implementation as well.

The default implementation only defines the —help option.

A Command should specify a callback to handle the option.

displayHelp

void displayHelp(
    std::ostream & ostr
);

Writes a help text to the given stream.

execute

class OSPShell_API AbstractCommand :public Command { public :virtual int execute(
    Session & session,
    const std::vector < std::string > & args,
    std::ostream & ostr
);

AbstractCommand provides a partial implementation of Command, doing automatic argument handling based on the options handling framework from the Util library.

Options must be given in Unix-style syntax (-o or —option).

Option handling for commands works in a similar way to command line options handling in the Poco::Util::Application class.

execute virtual

virtual int execute(
    Session & session,
    const std::vector < std::string > & args,
    std::ostream & ostr
) = 0;

Execute the command, using the given arguments, within the given session. The first element of the args vector is the command name.

Any output produced by executing the command can be written to the given output stream.

An integer must be returned that denotes success or failure of the command. Upon success, 0 shall be returned. The CommandStatus enumeration defines a few commonly used error codes that should be used. Other statis codes in the range 0 - 99 can be used as well. Negative status codes are reserved for internal use.

executeImpl virtual

virtual int executeImpl(
    Session & session,
    const std::vector < std::string > & args,
    std::ostream & ostr
) = 0;

Execute the command, using the given arguments. Called by AbstractCommand::execute() after options have been handled.

Any output produced by executing the command can be written to the given output stream.

An integer must be returned that denotes success or failure of the command. Upon success, 0 shall be returned. The CommandStatus enumeration defines a few commonly used error codes that should be used.

handleHelp

void handleHelp(
    const std::string & name,
    const std::string & value
);

Handles the —help command line option.

handleOption virtual

virtual void handleOption(
    const std::string & name,
    const std::string & value
);

Called when the option with the given name is encountered during command line arguments processing.

The default implementation does option validation, bindings and callback handling.

Overriding implementations must call the base class implementation.

init

void init(
    Poco::OSP::BundleContext::Ptr pContext
);

Initializes the factory with the given BundleContext.

initImpl

protected :virtual void initImpl();

Add extra initialization code by overriding this method in your subclass.

operator =

Command & operator = (
    const Command & param390
);

operator =

CommandFactory & operator = (
    const CommandFactory & param391
);

options

const Poco::Util::OptionSet & options() const;

Returns the application's option set.

processOptions

void processOptions(
    std::vector < std::string > & args
);

Processes command-line options.

stopOptionsProcessing

void stopOptionsProcessing();

If called from an option callback, stops all further options processing.

If called, the following options on the command line will not be processed, and required options will not be checked.

This is useful, for example, if an option for displaying help information has been encountered and no other things besides displaying help shall be done.

~AbstractCommand virtual

virtual ~AbstractCommand();

Destroys the AbstractCommand.

~Command virtual

virtual ~Command();

Destroys the Command.

~CommandFactory virtual

virtual ~CommandFactory();

A factory for Command objects. Creates the CommandFactory. Destroys the CommandFactory.

Variables

FactoryPtr

class OSPShell_API CommandProcessor { public :typedef Poco::SharedPtr < CommandFactory > FactoryPtr;

The CommandProcessor parses command lines and invokes commands.

STATUS_INTERMEDIATE

class OSPShell_API ShellConnection :public Poco::Net::TCPServerConnection { public :enum StatusCode { STATUS_INTERMEDIATE = 100, STATUS_OK = 200, STATUS_GOODBYE = 201, STATUS_CLIENT_ERROR = 400, STATUS_CLIENT_USAGE = 401, STATUS_CLIENT_DENIED = 403, STATUS_SERVER_ERROR = 500 };

The ShellConnection class receives commands over a TCP connection and sends responses back to the client.

Commands are received one per line, and responses are sent in RFC 2821-style response chunks. Every command can send multiple response chunks. Intermediate response chunks have a status code of 100, and can occur more than once. The final chunk has a status code has a 200, 4xx or 500 status code and is exactly one line long. If the command was successful, the status code is 200 and the response text is "OK". If the command was not successful (its return code was not 0), the status code is 400 + return code. If the comand resulted in an exception, the status code is 500.

Example (positive response to help command):

100-The following commands are available:
100-bundles (ls, ss)
100-services (lss)
100-start
100-stop
...
100-set
100 Enter <command> --help for more information about a command
200 OK

Example (negative response to login command):

403 DENIED

STATUS_OK

class OSPShell_API Command { public :enum CommandStatus { STATUS_OK = 0, STATUS_USAGE = 1, STATUS_ERROR = 2, STATUS_DENIED = 3 };

Command defines the interface every shell command must implement.

The interface is quite simple, consisting only of a single member function that subclasses must override. successful execution command line usage error command execution error bad credentials or insufficient permissions to execute the command

_commandName

std::string _commandName;

_description

private :std::string _description;

_options

Poco::Util::OptionSet _options;

_pContext

BundleContext::Ptr _pContext;

_showHelp

bool _showHelp;

_stopOptionsProcessing

bool _stopOptionsProcessing;

_usage

std::string _usage;