PTLib  Version 2.10.10
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
cli.h
Go to the documentation of this file.
1 /*
2  * cli.h
3  *
4  * Command line interpreter
5  *
6  * Copyright (C) 2006-2008 Post Increment
7  *
8  * The contents of this file are subject to the Mozilla Public License
9  * Version 1.0 (the "License"); you may not use this file except in
10  * compliance with the License. You may obtain a copy of the License at
11  * http://www.mozilla.org/MPL/
12  *
13  * Software distributed under the License is distributed on an "AS IS"
14  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
15  * the License for the specific language governing rights and limitations
16  * under the License.
17  *
18  * The Original Code is WOpenMCU
19  *
20  * The Initial Developer of the Original Code is Post Increment
21  *
22  * Contributor(s): Craig Southeren (craigs@postincrement.com)
23  * Robert Jongbloed (robertj@voxlucida.com.au)
24  *
25  * Portions of this code were written by Post Increment (http://www.postincrement.com)
26  * with the assistance of funding from US Joint Forces Command Joint Concept Development &
27  * Experimentation (J9) http://www.jfcom.mil/about/abt_j9.htm
28  *
29  * Further assistance for enhancements from Imagicle spa
30  *
31  * $Revision: 24931 $
32  * $Author: csoutheren $
33  * $Date: 2010-12-07 20:01:15 -0600 (Tue, 07 Dec 2010) $
34  */
35 
36 #ifndef PTLIB_CLI_H
37 #define PTLIB_CLI_H
38 
39 #include <ptlib.h>
40 #include <ptlib/sockets.h>
41 
42 #include <list>
43 
44 
56 class PCLI : public PObject
57 {
58  PCLASSINFO(PCLI, PObject);
59  public:
60  class Context;
61 
64  class Context : public PIndirectChannel
65  {
66  public:
71  Context(
72  PCLI & cli
73  );
74 
78  virtual ~Context();
80 
97  virtual PBoolean Write(
98  const void * buf,
99  PINDEX len
100  );
102 
107  bool Start();
108 
112  void Stop();
113 
119  virtual void OnStart();
120 
126  virtual void OnStop();
127 
130  virtual bool WritePrompt();
131 
135  virtual bool ReadAndProcessInput();
136 
140  virtual bool ProcessInput(int ch);
141  virtual bool ProcessInput(const PString & line);
142 
149  virtual void OnCompletedLine();
151 
156  PCLI & GetCLI() const { return m_cli; }
157 
160  bool IsProcessingCommand() const { return m_state == e_ProcessingCommand; }
162 
163  protected:
164  PDECLARE_NOTIFIER(PThread, Context, ThreadMain);
165 
171 
172  enum State {
177  } m_state;
179  };
180 
183  class Arguments : public PArgList
184  {
185  public:
188  Arguments(
189  Context & context,
190  const PString & rawLine
191  );
193 
198  Context & WriteUsage();
199 
203  const PString & error = PString::Empty()
204  );
206 
211  Context & GetContext() const { return m_context; }
213 
214  protected:
218 
219  friend class PCLI;
220  };
221 
222 
227  PCLI(
228  const char * prompt = NULL
229  );
230 
234  virtual ~PCLI();
236 
247  virtual bool Start(
248  bool runInBackground = true
249  );
250 
255  virtual void Stop();
256 
259  bool StartContext(
260  PChannel * channel,
261  bool autoDelete = true,
262  bool runInBackground = true
263  );
264  bool StartContext(
265  PChannel * readChannel,
266  PChannel * writeChannel,
267  bool autoDeleteRead = true,
268  bool autoDeleteWrite = true,
269  bool runInBackground = true
270  );
271 
275  virtual Context * CreateContext();
276 
280  virtual Context * AddContext(
281  Context * context = NULL
282  );
283 
287  virtual void RemoveContext(
288  Context * context
289  );
290 
293  virtual void GarbageCollection();
294 
302  virtual void OnReceivedLine(
303  Arguments & line
304  );
305 
318  virtual bool OnLogIn(
319  const PString & username,
320  const PString & password
321  );
322 
325  void Broadcast(
326  const PString & message
327  ) const;
328 
339  bool SetCommand(
340  const char * command,
341  const PNotifier & notifier,
342  const char * help = NULL,
343  const char * usage = NULL
344  );
345 
348  void ShowHelp(
349  Context & context
350  );
352 
358  const PString & GetNewLine() const { return m_newLine; }
359 
363  void SetNewLine(const PString & newLine) { m_newLine = newLine; }
364 
368  bool GetRequireEcho() const { return m_requireEcho; }
369 
373  void SetRequireEcho(bool requireEcho) { m_requireEcho = requireEcho; }
374 
378  const PString & GetEditCharacters() const { return m_editCharacters; }
379 
383  void SetEditCharacters(const PString & editCharacters) { m_editCharacters = editCharacters; }
384 
388  const PString & GetPrompt() const { return m_prompt; }
389 
393  void SetPrompt(const PString & prompt) { m_prompt = prompt; }
394 
398  const PString & GetUsernamePrompt() const { return m_usernamePrompt; }
399 
403  void SetUsernamePrompt(const PString & prompt) { m_usernamePrompt = prompt; }
404 
408  const PString & GetPasswordPrompt() const { return m_passwordPrompt; }
409 
413  void SetPasswordPrompt(const PString & prompt) { m_passwordPrompt = prompt; }
414 
418  const PString & GetUsername() const { return m_username; }
419 
423  void SetUsername(const PString & username) { m_username = username; }
424 
428  const PString & GetPassword() const { return m_password; }
429 
433  void SetPassword(const PString & password) { m_password = password; }
434 
438  const PCaselessString & GetExitCommand() const { return m_exitCommand; }
439 
443  void SetExitCommand(const PCaselessString & exitCommand) { m_exitCommand = exitCommand; }
444 
448  const PCaselessString & GetHelpCommand() const { return m_helpCommand; }
449 
453  void SetHelpCommand(const PCaselessString & helpCommand) { m_helpCommand = helpCommand; }
454 
459  const PString & GetHelpOnHelp() const { return m_helpOnHelp; }
460 
465  void SetHelpOnHelp(const PCaselessString & helpOnHelp) { m_helpOnHelp = helpOnHelp; }
466 
471 
475  void SetRepeatCommand(const PCaselessString & repeatCommand) { m_repeatCommand = repeatCommand; }
476 
481 
485  void SetHistoryCommand(const PCaselessString & historyCommand) { m_historyCommand = historyCommand; }
486 
490  const PString & GetNoHistoryError() const { return m_noHistoryError; }
491 
495  void SetNoHistoryError(const PString & noHistoryError) { m_noHistoryError = noHistoryError; }
496 
501 
505  void SetCommandUsagePrefix(const PString & commandUsagePrefix) { m_commandUsagePrefix = commandUsagePrefix; }
506 
511 
515  void SetCommandErrorPrefix(const PString & commandErrorPrefix) { m_commandErrorPrefix = commandErrorPrefix; }
516 
521 
525  void SetUnknownCommandError(const PString & unknownCommandError) { m_unknownCommandError = unknownCommandError; }
527 
530  virtual Context * StartForeground();
531 
534  virtual bool RunContext(Context * context);
535 
536 
537  protected:
555 
560  };
561  typedef std::map<PString, InternalCommand> CommandMap_t;
563 
564  typedef std::list<Context *> ContextList_t;
567 };
568 
569 
572 class PCLIStandard : public PCLI
573 {
574  public:
579  PCLIStandard(
580  const char * prompt = NULL
581  );
583 
590  virtual bool Start(
591  bool runInBackground = true
592  );
594 
596 };
597 
598 
603 class PCLISocket : public PCLI
604 {
605  public:
608  PCLISocket(
609  WORD port = 0,
610  const char * prompt = NULL,
611  bool singleThreadForAll = false
612  );
613  ~PCLISocket();
615 
622  virtual bool Start(
623  bool runInBackground = true
624  );
625 
633  virtual void Stop();
634 
638  virtual Context * AddContext(
639  Context * context = NULL
640  );
641 
645  virtual void RemoveContext(
646  Context * context
647  );
649 
654  bool Listen(
655  WORD port = 0
656  );
657 
660  WORD GetPort() const { return m_listenSocket.GetPort(); }
662 
663  protected:
664  PDECLARE_NOTIFIER(PThread, PCLISocket, ThreadMain);
666  bool HandleIncoming();
667  virtual PTCPSocket * CreateSocket();
668 
670 
673 
674  typedef std::map<PSocket *, Context *> ContextMap_t;
676 };
677 
678 
683 class PCLITelnet : public PCLISocket
684 {
685  public:
688  PCLITelnet(
689  WORD port = 0,
690  const char * prompt = NULL,
691  bool singleThreadForAll = false
692  );
694 
695  protected:
696  virtual PTCPSocket * CreateSocket();
697 };
698 
699 
700 #endif // PTLIB_CLI_H
701 
702 
703 // End Of File ///////////////////////////////////////////////////////////////
PTCPSocket m_listenSocket
Definition: cli.h:671
void SetHelpOnHelp(const PCaselessString &helpOnHelp)
Set help on help.
Definition: cli.h:465
Definition: cli.h:175
std::list< Context * > ContextList_t
Definition: cli.h:564
void SetUsername(const PString &username)
Set username for log in validation.
Definition: cli.h:423
void SetHistoryCommand(const PCaselessString &historyCommand)
Set command that will list/execute command history.
Definition: cli.h:485
PCaselessString m_exitCommand
Definition: cli.h:546
void ShowHelp(Context &context)
Show help for registered commands to the context.
virtual ~PCLI()
Destroy the command line interpreter.
PMutex m_contextMutex
Definition: cli.h:566
const PString & GetEditCharacters() const
Get characters used for editing (backspace/delete) command lines.
Definition: cli.h:378
virtual void Stop()
Stop and clean up command line interpreters.
void SetEditCharacters(const PString &editCharacters)
Set characters used for editing (backspace/delete) command lines.
Definition: cli.h:383
PString m_passwordPrompt
Definition: cli.h:543
PString m_newLine
Definition: cli.h:538
PString m_helpOnHelp
Definition: cli.h:548
virtual bool ReadAndProcessInput()
Read a character from the attached channel an process.
Class specialisation for PNotifierTemplate<INT>
PCaselessString m_historyCommand
Definition: cli.h:550
Context & GetContext() const
Get the CLI context supplying the command line arguments.
Definition: cli.h:211
const PString & GetNewLine() const
Get new line string output at the end of every line.
Definition: cli.h:358
PString m_usernamePrompt
Definition: cli.h:542
Definition: cli.h:556
PThread * m_thread
Definition: cli.h:672
This class is an enhancement to PArgList to add context.
Definition: cli.h:183
virtual bool RunContext(Context *context)
Run a context.
const PCaselessString & GetExitCommand() const
Get command to be used to exit session.
Definition: cli.h:438
const PString & GetPrompt() const
Get prompt used for command line interpreter.
Definition: cli.h:388
virtual Context * AddContext(Context *context=NULL)
Add a command line interpreter context to the system.
virtual bool WritePrompt()
Write prompt (depending on state) to channel.
const PCaselessString & GetHelpCommand() const
Get command to be used to display help.
Definition: cli.h:448
PString m_prompt
Definition: cli.h:541
This is a channel that operates indirectly through another channel(s).
Definition: indchan.h:49
virtual void OnStop()
Callback for when context is stopping.
This class is a variation of a string that ignores case.
Definition: pstring.h:1708
PStringList m_commandHistory
Definition: cli.h:169
virtual void OnReceivedLine(Arguments &line)
Received a completed command line.
PCLIStandard(const char *prompt=NULL)
Create new command line interpreter for standard I/O.
Context(PCLI &cli)
Construct new command line interpreter context.
PString m_username
Definition: cli.h:544
bool IsProcessingCommand() const
Indicate is currently processing a command.
Definition: cli.h:160
void SetCommandErrorPrefix(const PString &commandErrorPrefix)
Set error prefix for if Arguments::WriteError() called.
Definition: cli.h:515
PNotifier m_notifier
Definition: cli.h:557
const PString & GetUnknownCommandError() const
Get error message for if unknown command is entered.
Definition: cli.h:520
virtual bool Start(bool runInBackground=true)
Start a command line interpreter.
bool Start()
Start a command line interpreter thread.
virtual ~Context()
Destroy command line interpreter context.
const PString & GetUsername() const
Get username for log in validation.
Definition: cli.h:418
CommandMap_t m_commands
Definition: cli.h:562
BOOL PBoolean
Definition: object.h:102
virtual void RemoveContext(Context *context)
Remove the command line interpreter context.
bool m_requireEcho
Definition: cli.h:539
const PString & GetHelpOnHelp() const
Get help on help.
Definition: cli.h:459
const PString & GetCommandUsagePrefix() const
Get usage prefix for if Arguments::WriteUsage() called.
Definition: cli.h:500
virtual void GarbageCollection()
Remove any closed command line interpreter contexts.
Context for command line interpreter.
Definition: cli.h:64
void SetUsernamePrompt(const PString &prompt)
Set prompt used for login (if enabled).
Definition: cli.h:403
PString m_noHistoryError
Definition: cli.h:551
bool HandleSingleThreadForAll()
bool m_singleThreadForAll
Definition: cli.h:669
virtual bool Start(bool runInBackground=true)
Start a command line interpreter.
State
Definition: cli.h:172
void SetCommandUsagePrefix(const PString &commandUsagePrefix)
Set usage prefix for if Arguments::WriteUsage() called.
Definition: cli.h:505
bool StartContext(PChannel *channel, bool autoDelete=true, bool runInBackground=true)
Open a command line interpreter context.
std::map< PSocket *, Context * > ContextMap_t
Definition: cli.h:674
void SetNoHistoryError(const PString &noHistoryError)
Set error message for if there is no history.
Definition: cli.h:495
PString m_usage
Definition: cli.h:217
PDECLARE_NOTIFIER(PThread, PCLISocket, ThreadMain)
virtual PTCPSocket * CreateSocket()
const PString & GetPassword() const
Get password for log in validation.
Definition: cli.h:428
Abstract class defining I/O channel semantics.
Definition: channel.h:107
PCLI(const char *prompt=NULL)
Contracut a new command line interpreter.
void SetPasswordPrompt(const PString &prompt)
Set prompt used for password (if enabled).
Definition: cli.h:413
PString m_editCharacters
Definition: cli.h:540
void Broadcast(const PString &message) const
Set a string to all command line interpreter contexts.
PString m_unknownCommandError
Definition: cli.h:554
const PString & GetNoHistoryError() const
Get error message for if there is no history.
Definition: cli.h:490
Command Line Interpreter over standard input/output.
Definition: cli.h:572
virtual bool ProcessInput(int ch)
Process a character read from the channel.
virtual bool Start(bool runInBackground=true)
Start a command line interpreter.
void SetNewLine(const PString &newLine)
Set new line string output at the end of every line.
Definition: cli.h:363
PDECLARE_NOTIFIER(PThread, Context, ThreadMain)
PString m_commandUsagePrefix
Definition: cli.h:552
The character string class.
Definition: pstring.h:108
const PCaselessString & GetRepeatCommand() const
Get the command to be used to repeat the last executed command.
Definition: cli.h:470
PString m_usage
Definition: cli.h:559
void SetPassword(const PString &password)
Set password for log in validation.
Definition: cli.h:433
const PString & GetUsernamePrompt() const
Get prompt used for login (if enabled).
Definition: cli.h:398
Context & WriteError(const PString &error=PString::Empty())
Write an error to the CLI output channel.
A socket that uses the TCP transport on the Internet Protocol.
Definition: tcpsock.h:44
Context & WriteUsage()
Write to the CLI output channel the usage for the current command.
void SetRepeatCommand(const PCaselessString &repeatCommand)
Set the command to be used to repeat the last executed command.
Definition: cli.h:475
PString m_enteredUsername
Definition: cli.h:178
static PString Empty()
Return an empty string.
ContextMap_t m_contextBySocket
Definition: cli.h:675
Context & m_context
Definition: cli.h:215
This class allows the parsing of a set of program arguments.
Definition: args.h:45
PCLI::Context * StartForeground()
Initialise a foreground context and return it.
enum PCLI::Context::State m_state
const PCaselessString & GetHistoryCommand() const
Get command that will list/execute command history.
Definition: cli.h:480
PCaselessString m_repeatCommand
Definition: cli.h:549
PString m_help
Definition: cli.h:558
WORD GetPort() const
Get the port we are listing on.
Definition: cli.h:660
PString m_commandLine
Definition: cli.h:167
virtual PBoolean Write(const void *buf, PINDEX len)
Low level write to the channel.
bool m_ignoreNextEOL
Definition: cli.h:168
void SetUnknownCommandError(const PString &unknownCommandError)
Set error message for if unknown command is entered.
Definition: cli.h:525
bool GetRequireEcho() const
Get flag for echo is required for entered characters.
Definition: cli.h:368
This class defines a thread of execution in the system.
Definition: thread.h:66
This is a list collection class of PString objects.
Definition: pstring.h:2184
std::map< PString, InternalCommand > CommandMap_t
Definition: cli.h:561
PCLITelnet(WORD port=0, const char *prompt=NULL, bool singleThreadForAll=false)
PCaselessString m_helpCommand
Definition: cli.h:547
bool SetCommand(const char *command, const PNotifier &notifier, const char *help=NULL, const char *usage=NULL)
Register a new command to be interpreted.
PCLISocket(WORD port=0, const char *prompt=NULL, bool singleThreadForAll=false)
ContextList_t m_contextList
Definition: cli.h:565
void Stop()
Stop command line interpreter context.
bool HandleIncoming()
virtual Context * CreateContext()
Create a new context.
virtual void Stop()
Stop and clean up command line interpreters.
PCLI & m_cli
Definition: cli.h:166
Command Line Interpreter over TCP sockets.
Definition: cli.h:603
PThread * m_thread
Definition: cli.h:170
Command Line Interpreter over Telnet sockets.
Definition: cli.h:683
virtual Context * AddContext(Context *context=NULL)
Add a command line interpreter context to the system.
Synonym for PTimedMutex.
Arguments(Context &context, const PString &rawLine)
virtual void OnStart()
Call back frunction for when context is started.
const PString & GetCommandErrorPrefix() const
Get error prefix for if Arguments::WriteError() called.
Definition: cli.h:510
PString m_password
Definition: cli.h:545
void SetPrompt(const PString &prompt)
Set prompt used for command line interpreter.
Definition: cli.h:393
void SetHelpCommand(const PCaselessString &helpCommand)
Set command to be used to display help.
Definition: cli.h:453
PString m_commandErrorPrefix
Definition: cli.h:553
Definition: cli.h:173
void SetExitCommand(const PCaselessString &exitCommand)
Set command to be used to exit session.
Definition: cli.h:443
virtual PTCPSocket * CreateSocket()
Definition: cli.h:174
PString m_command
Definition: cli.h:216
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
Command Line Interpreter class.
Definition: cli.h:56
const PString & GetPasswordPrompt() const
Get prompt used for password (if enabled).
Definition: cli.h:408
virtual Context * StartForeground()
Initialise a foreground context and return it.
virtual void OnCompletedLine()
Call back for a command line was completed and ENTER pressed.
virtual void RemoveContext(Context *context)
Remove the command line interpreter context.
WORD GetPort() const
Get the port the TCP socket channel object instance is using.
void SetRequireEcho(bool requireEcho)
Set flag for echo is required for entered characters.
Definition: cli.h:373
bool Listen(WORD port=0)
Start listening socket.
virtual bool OnLogIn(const PString &username, const PString &password)
Received a login name/pasword to be verified.
PCLI & GetCLI() const
Get the CLI.
Definition: cli.h:156