                            MailCheck v1.15
                            

                    by Reuben Thomas (rrt@sc3d.org)
                    Web page: http://sc3d.org/rrt/


MailCheck checks whether a user on a remote system has unread email and
displays the result in an iconbar icon, which is updated periodically. It can
start a login, either manually, or automatically when a user receives mail.
Multiple users are handled. MailCheck also provides a simple interface to the
command-line finger program.


Copyright and Disclaimer


MailCheck is distributed under the GNU Public License version 2, or, at your
option, any later version. A copy is available from my web page (address
above), as is the source code.

THIS PROGRAM IS PROVIDED AS IS, WITH NO WARRANTY. USE IS AT THE USER'S RISK.


Quick start


Look at the !Configure file, and at Scripts.Example.


Is it for me?


As is hopefully obvious, MailCheck is only any use if you have a machine
connected to the Internet, and if you receive email on a different machine.
If your mail is delivered to your computer (which will almost certainly be
the case if you have a domestic dial-up connection) then this program is Not
For You.


Installation


MailCheck requires SharedBLib work (available from the same site; see the top
of this file).

You also need a resolver module: either Acorn/ANT's Resolver or any resolver
module that supports Resolver_GetHost.

Whatever you use, it should be started by your Internet suite, as MailCheck
can't load it automatically.


Configuration


Before you use MailCheck, you must configure it by editing the !Configure
file inside the !MailCheck application. You must configure:

1. How often in minutes it will check for mail, or 0 to disable automatic
checks.

2. The automatic login policy: a single character that determines whether
MailCheck will automatically start a login when a check is positive. It may
be:

    N - "N"ever start a login
    I - Start a login if mail was checked "I"nteractively, i.e.
        by clicking on the MailCheck icon or by changing the
        current user.
    A - "A"lways start a login. To avoid coming back to your
        computer and finding the screen covered in logins,
        MailCheck will only start a login when new mail first
        arrives, unless the user made the check themselves.

3. Whether it will beep when mail arrives ("Y" or "N").

4. Whether it will revert to the default user on each automatic check. This
can be useful if the default user is the main user of the other computer, and
the other users just check mail on it ("Y" or "N").

5. Whether the box will become thin whenever a user logs in or is logged in
("Y" or "N"). This is a matter of taste: do you want the program to assume
you're checking your mail, or do you want it to verify it next time it checks
for you?

6. How many users there are.

7. The users' details. Each user must have an entry of the form:

    name,id,host,port,verbose,cue,command

"name"      is the name that will appear on the icon bar, and must be no more
            than four characters so as to fit under the pillar box icon. I
            use initials.

"id"        is the user id of the account which will be checked for mail.

"host"      is the name of the machine on which the user's account is held.

"port"      is the port number on which the finger request should be made.
            Unless you know otherwise, you should leave this blank, and the
            default port will be used. A different setting can be used for
            some simple alternative finger-like services, which will
            probably require "verbose" (the next option) to be set to N.

"verbose"   determines whether a verbose mode finger (/W flag) is needed.
            It may be Y or N, and should be set to Y unless you know
            otherwise.

"cue"       is a string which the output of finger contains when the user has
            new mail.

            You what?
            
            MailCheck works by fingering the current user and scanning the
            output for a particular text string. On most systems fingering a
            user will tell you if they have new mail; on my system a line
            starting "Most recent mail..." is added to finger's output, so my
            cue is "recent mail" (spaces are allowed).
               To discover what cue to use, make sure the user in question
            has mail (by sending them some, for instance), then use
            MailCheck's finger facility (in "Verbose" mode) on that user to
            see how their mail status is reported. Note that you must first
            fill in the cue with a dummy value, as otherwise MailCheck will
            refuse to run. See below for how to use finger in MailCheck.

"command"   is the command that will be run to start an automatic login. If
    	    it is left blank, an Open URL message (&4AF80) will be sent with
    	    the text "telnet://id@host". This is recognised by ANT's terminal
    	    program, and FreeTerm v1.31 and later. Alternatively, you can
    	    write a script and give its name as the command. This allows you
    	    for example to write a FreeTerm script which can not only log you
    	    in but give your password and start your mail reader. The command
    	    will probably be of the form "MailCheck:Scripts.foo" where "foo"
    	    is a script you have placed in the directory !MailCheck.Scripts.
    	    An example script for use with FreeTerm is stored there. Scripts
            could also be used to generate automatic logins for other
            terminal programs such as Acorn's VT220 that don't recognise the
            Open URL message. I'd be happy to receive examples of scripts
            for use with such programs.

The !Configure file itself shows you how and where to put these bits of
information.

  A tip about scripts
  

You may be thinking "this logging in and running commands is all very well,
but I don't want to leave a file containing my password lying around on my
hard disk". My solution is a program which constructs such files when I turn
the computer on after asking me for my passwords, and which deletes them
again when I switch off, but there is another trick: simply omit the lines

wait "assword:"
sendl "xxxxxxx"

in the script. When the script runs it will enter your user id and then wait
for you to enter your password; after that the script will continue.


Usage


  Checking for mail
  

The MailCheck icon is a (usually red) pillar box (that's English for
mailbox) with the current user's name underneath. When the user has new mail
it will bulge; if the check for mail cannot be made for some reason it will
be greyed out.

When MailCheck is run it immediately checks for mail for the default user,
which is the first listed in the !Configure file. [Note: this check is made
even if automatic checking is disabled, as it is assumed that people check
their mail when they turn their computer on.] You can change the current user
and check mail by selecting a user from the "Check" menu. Clicking Select on
the "Check" menu heading checks mail for the current user, as does clicking
Select on the icon.

While MailCheck is checking, which may take several seconds, the icon has a
question mark over it. If the check cannot be made, an error message to that
effect is displayed. These signals are suppressed during the automatic
periodic checks; this makes MailCheck less obtrusive, and prevents it locking
up the desktop, which can be irritating if you are not at the computer when
it does so.

  Logging in
  

You can log a user in without changing the current user by selecting a user
from the "Log in" menu. Clicking on the menu headings logs the current user
in, as does clicking Adjust on the iconbar icon. The pillar box will go thin
whenever the current user logs in or is logged in automatically.

  Fingering
  

Select "Finger..." from the main menu to bring up the Finger dialogue box.
You can enter a user to finger in the form "id@host" or use "@host" to list
all the users currently logged on to a host. The Verbose option chooses
whether full information will be displayed or just a summary (the latter is
recommended when using the "@host" form). You can finger configured users of
MailCheck by selecting them from the popup menu next to the Name box.

  Running MailCheck automatically
  

You can run MailCheck in your boot sequence, provided it is run after your
Internet stack is loaded. On RISC OS 3 and later you can achieve this by
saving a Desktop boot file while MailCheck is running, or on RISC OS 3.5 and
later, you can copy the !MailCheck application into !Boot.Choices.Boot.Tasks.
One thing to beware of is that if you also have FreeTerm in your boot
sequence it must run before MailCheck tries to start a FreeTerm login. This
can be fiddly.


Acknowledgements


Thanks to:

    Justin Fletcher for InetServices and EasySockets, a pair of useful and
    extremely easy to use modules.

    Chris Poole for answering questions about Internet programming.

    Ian Palmer and Tom Hughes for BLibII rel. IV, Tony Houghton for THHeap,
    Dick Alstein for TemplEd, Ragnar Hafsta for BasCrunch, Tony Howat and
    Merlin Hughes for FreeTerm, and the Zap developers for Zap.

    The anonymous artist of the original mailbox sprites, which came from
    Graham Allan's SLIPdial program; he can't remember whence they came.

    Lina Christopoulou and James Martin, my local testers, and Peter
    Killworth, the first off-site user to give feedback and bug reports,
    whose misunderstandings vastly improved the manual.

    Matthew Astley, for suggesting the "port" and "verbose" configuration
    options, and the optional beep when mail arrives.


Comments and bugs


I'd appreciate reports of bugs or problems and suggestions for improvement
(though I don't have much time for the last, and the program does what I want
now; it could easily be expanded to do many other things but to do them well
would need considerable work).

On the other hand, I welcome ideas for improvement of the documentation, and
ways of getting MailCheck to work with terminal programs not mentioned here.
