cmd/Notes.txt

   1 Programming Notes ($Id$)
   2
   3 * Every command that can used on the command line lives in either this
   4   directory ('cmd') or in a local version ('local_cmd'). You are cajoled or
   5   ordered not to and generally discouraged from altering the commands in
   6   the 'cmd' directory. You can put local copies in the 'local_cmd' directory
   7   and they will override the standard ones.
   8
   9 * If you want to play, do it in the 'local_cmd' directory. It's very easy and
  10   reasonably safe. You can override a command whilst the cluster is running.
  11   Compilation errors will simply give you error messages, it won't stop the
  12   cluster running - this only happens if you mess with the internals to the
  13   extent that it gets confused...
  14
  15 * A command is a piece of perl, it is simply a small snippet of program
  16   that is dynamically loaded into the cluster on invocation from the
  17   command line. The last modification time is used to determine whether to
  18   reload it.
  19
  20 * New (or altered) commands are available for test the moment you save them.
  21
  22 * A command is placed into the appropriate directory with a '.pl' appended
  23   to the end. So the 'show/qra' command lives in 'cmd/show/qra.pl' (or a
  24   local version would be in 'local_cmd/show/qra.pl'.
  25
  26 * For the security conscious, potentially dubious characters (i.e. not
  27   [A-Za-z0-9_/]) are converted to their hex equivalents. This will almost
  28   certainly mean that the user will get an error message (unless you have
  29   your secret squirrel hat on and have deliberately put such commands up
  30   [in 'local_cmd' of course]).
  31
  32 * The snippets of program you put here are wrapped in an eval { } and
  33   are subroutines derived from the DXChannel class. They effectively
  34   the following declaration :-
  35
  36   sub Emb_<cmdname>($self, $args)
  37   {
  38      ...
  39      your code here
  40      ...
  41   }
  42
  43 * slash characters are replaced by '_' so the equivalent name for 'show/qth'
  44   is 'Emb_show_qth'.
  45
  46 * you would normally do a 'my $self = shift;' as the first thing. There
  47   are a complete set of accessors for DXUser, DXCommandmode and DXChannel
  48   classes and these are the recommended way of getting at these classes.
  49   A fairly standard start might be:-
  50
  51   $self = shift;
  52   $call = $self->call;
  53   $user = $self->user;
  54
  55 * $args is the rest of the line after the command (as a string).
  56
  57 * You are responsible for maintaining user security. If you have a command
  58   that does something a normal system shouldn't be allowed to do or see,
  59   there is $self->priv (using the above example) which gives you the running
  60   privilege level of the channel. USE IT!
  61
  62 * The normal privilege levels are:-
  63     0 - user privilege.
  64     5 - sysop privilege.
  65     9 - console privilege.
  66
  67   The sysop privilege is for things that you are prepared for remote
  68   sysops and clusters to do or see.
  69
  70   A console privilege can only be executed locally (at least if you have
  71   correctly installed the client program in inetd or ax25d).
  72
  73   The set/priv command can only be executed by a console privileged
  74   session.
  75
  76 * You must return a list with a 0 or 1 as the first element. 1 means
  77   success and 0 means fail. Each element of the list which follows is
  78   assumed to be one line for output. Don't put \n characters at the end
  79   of an element (the client will put the correct one in if required
  80   [but see below]).
  81
  82 * Anything you output with a > as the last character is taken to mean
  83   that this is a prompt and will not have a \r or \n appended to it.
  84
  85 * help files can also be placed in the appropriate place. These files
  86   have exactly the same naming conventions as commands except that they
  87   have a '.hlp' appended to the command name rather than a '.pl'. All
  88   in the help file are sent to the user except those starting with a '#'
  89   character.