PTLib  Version 2.10.11
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 
202  Context & WriteError(
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(
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;
562  CommandMap_t m_commands;
563 
564  typedef std::list<Context *> ContextList_t;
565  ContextList_t m_contextList;
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);
665  bool HandleSingleThreadForAll();
666  bool HandleIncoming();
667  virtual PTCPSocket * CreateSocket();
668 
670 
673 
674  typedef std::map<PSocket *, Context *> ContextMap_t;
675  ContextMap_t m_contextBySocket;
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
const PCaselessString & GetExitCommand() const
Get command to be used to exit session.
Definition: cli.h:438
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
PCLI & GetCLI() const
Get the CLI.
Definition: cli.h:156
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.
const PString & GetPrompt() const
Get prompt used for command line interpreter.
Definition: cli.h:388
PMutex m_contextMutex
Definition: cli.h:566
Context & GetContext() const
Get the CLI context supplying the command line arguments.
Definition: cli.h:211
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>
const PString & GetUsernamePrompt() const
Get prompt used for login (if enabled).
Definition: cli.h:398
PCaselessString m_historyCommand
Definition: cli.h:550
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.
virtual Context * AddContext(Context *context=NULL)
Add a command line interpreter context to the system.
const PString & GetHelpOnHelp() const
Get help on help.
Definition: cli.h:459
virtual bool WritePrompt()
Write prompt (depending on state) to channel.
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
bool GetRequireEcho() const
Get flag for echo is required for entered characters.
Definition: cli.h:368
virtual void OnReceivedLine(Arguments &line)
Received a completed command line.
Context(PCLI &cli)
Construct new command line interpreter context.
PString m_username
Definition: cli.h:544
void SetCommandErrorPrefix(const PString &commandErrorPrefix)
Set error prefix for if Arguments::WriteError() called.
Definition: cli.h:515
PNotifier m_notifier
Definition: cli.h:557
PChannel * readChannel
Channel for read operations.
Definition: indchan.h:301
const PString & GetUnknownCommandError() const
Get error message for if unknown command is entered.
Definition: cli.h:520
bool Start()
Start a command line interpreter thread.
virtual ~Context()
Destroy command line interpreter context.
CommandMap_t m_commands
Definition: cli.h:562
const PString & GetCommandErrorPrefix() const
Get error prefix for if Arguments::WriteError() called.
Definition: cli.h:510
BOOL PBoolean
Definition: object.h:102
WORD GetPort() const
Get the port we are listing on.
Definition: cli.h:660
bool m_requireEcho
Definition: cli.h:539
PChannel * writeChannel
Channel for write operations.
Definition: indchan.h:307
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 m_singleThreadForAll
Definition: cli.h:669
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.
const PString & GetPassword() const
Get password for log in validation.
Definition: cli.h:428
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
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
PString m_unknownCommandError
Definition: cli.h:554
Command Line Interpreter over standard input/output.
Definition: cli.h:572
virtual bool ProcessInput(int ch)
Process a character read from the channel.
const PString & GetNoHistoryError() const
Get error message for if there is no history.
Definition: cli.h:490
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
PString m_usage
Definition: cli.h:559
void SetPassword(const PString &password)
Set password for log in validation.
Definition: cli.h:433
A socket that uses the TCP transport on the Internet Protocol.
Definition: tcpsock.h:44
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
const PString & GetEditCharacters() const
Get characters used for editing (backspace/delete) command lines.
Definition: cli.h:378
enum PCLI::Context::State m_state
PCaselessString m_repeatCommand
Definition: cli.h:549
const PString & GetNewLine() const
Get new line string output at the end of every line.
Definition: cli.h:358
PString m_help
Definition: cli.h:558
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
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
bool IsProcessingCommand() const
Indicate is currently processing a command.
Definition: cli.h:160
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.
ContextList_t m_contextList
Definition: cli.h:565
void Stop()
Stop command line interpreter context.
virtual Context * CreateContext()
Create a new context.
const PString & GetPasswordPrompt() const
Get prompt used for password (if enabled).
Definition: cli.h:408
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
Synonym for PTimedMutex.
const PString & GetCommandUsagePrefix() const
Get usage prefix for if Arguments::WriteUsage() called.
Definition: cli.h:500
virtual void OnStart()
Call back frunction for when context is started.
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
const PCaselessString & GetHelpCommand() const
Get command to be used to display help.
Definition: cli.h:448
void SetExitCommand(const PCaselessString &exitCommand)
Set command to be used to exit session.
Definition: cli.h:443
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
virtual Context * StartForeground()
Initialise a foreground context and return it.
virtual void OnCompletedLine()
Call back for a command line was completed and ENTER pressed.
void Broadcast(const PString &message) const
Set a string to all command line interpreter contexts.
const PCaselessString & GetRepeatCommand() const
Get the command to be used to repeat the last executed command.
Definition: cli.h:470
virtual void RemoveContext(Context *context)
Remove the command line interpreter context.
const PCaselessString & GetHistoryCommand() const
Get command that will list/execute command history.
Definition: cli.h:480
const PString & GetUsername() const
Get username for log in validation.
Definition: cli.h:418
void SetRequireEcho(bool requireEcho)
Set flag for echo is required for entered characters.
Definition: cli.h:373
virtual bool OnLogIn(const PString &username, const PString &password)
Received a login name/pasword to be verified.