]> scm.dxcluster.org Git - spider.git/blob - cmd/Notes.txt
add UPGRADE.mojo
[spider.git] / cmd / Notes.txt
1 Programming Notes
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, $line) = @_;' 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   my ($self, $line) = @_;
52   @args = split /\s+/, $line;
53   $call = $self->call;
54   $user = $self->user;
55
56 * $args is the rest of the line after the command (as a string).
57
58 * You are responsible for maintaining user security. If you have a command
59   that does something a normal system shouldn't be allowed to do or see, 
60   there is $self->priv (using the above example) which gives you the running
61   privilege level of the channel. USE IT!
62
63 * The normal privilege levels are:-
64     0 - user privilege.
65     1 - remote user user privilege
66     5 - sysop privilege.
67     8 - maximum recommended remote sysop privilege
68     9 - console privilege.
69
70   The sysop privilege is for things that you are prepared for remote
71   sysops and clusters to do or see.
72
73   A console privilege can only be executed locally (at least if you have
74   correctly installed the client program in inetd or ax25d).
75
76   The set/priv command can only be executed by a console privileged 
77   session.
78
79 * You must return a list with a 0 or 1 as the first element. 1 means
80   success and 0 means fail. Each element of the list which follows is 
81   assumed to be one line for output. Don't put \n characters at the end
82   of an element (the client will put the correct one in if required 
83   [but see below]).
84
85 * As this is perl and it is very easy to alter stuff to get it correct,
86   I would like to see some intelligent argument processing, e.g. if 
87   you can have one callsign, you can have several. Interpret your
88   arguments; so for example:-
89
90     set/qra jo02lq       - sets your own locator to JO02LQ
91     set/qra g1tlh jo02lq - sets G1TLH's locator (if you are allowed)
92
93   or
94
95     show/qra in92jo      - displays the bearing and distance to 
96                            IN92JO using your lat/long or locator
97     show/qra jn56in in92jo  - bearing and distance between two
98                               locators
99
100 * It is important that you remember when you have tie hashes using MLDBM
101   et al. If you do a DXUser::get($call) you will get a different (older)
102   thing than the one in $self->$user. This is almost certainly NOT what
103   you want if want to modify a user that is currently connected.
104
105 * If you want to debug something, start the cluster.pl up thus:-
106     
107     perl -d cluster.pl
108     dbg> r
109
110   Then you can go into debug mode at anytime by using the command :-
111  
112     debug
113
114   or you can put the line:-
115
116     $DB::single = 1;
117
118   in an appropriate place in a command. This will only have an effect
119   if you are running in perl debug mode.
120
121 * Anything you output with a > as the last character is taken to mean
122   that this is a prompt and will not have a \r or \n appended to it.
123
124 * help files can also be placed in the appropriate place. These files 
125   have exactly the same naming conventions as commands except that they
126   have a '.hlp' appended to the command name rather than a '.pl'. All 
127   in the help file are sent to the user except those starting with a '#'
128   character.
129
130 * PLEASE add your new commands to the Commands_*.hlp file so that 
131   people know about and how to use them!