AppleTalk Username/password strategy :
------------------------------------

(in the following text, "AT server" means an AppleTalk or AppleShare IP
server)

- Username & password icons of the "AppleTalk Login" window or any other
window are *NOT* used for enumerating all available AT servers on the net. 
As soon as the AT stack has initialised itself, the search for AT servers on
the net will begin.  The search will reveal all AppleTalk servers. 

Note that AppleShare IP servers with only IP support can not be found
automatically.  The user should fill in the necessairy details in the
AppleTalk mount box.  You have to use the Internet hostname as server name. 
You can't use its IP number.

- When you extract the available mounts of a given AT server (by double
clicking on the server's icon), the Username & password filled in the
'AppleTalk Login' window will be used.  If the Username is the empty string,
the AppleTalk guest account will be used to enumerate the mount points.

- The AT server is free to reveal only a subset of all its mount points
depending on the given username & password.  The AppleTalk guest account has
traditionally very few or even no mounts points available.

Implementation note : we store the username & password used in the mount
enumeration in each new created mount struct during that mount enumeration. 
So, each mount struct has at least an username & password which enables the
Acorn user to access that mount (1).  Note that this username & password is
not necessairy the one which the user want to use the really mount that mount
point, e.g. because the priviledges associated with the username are not
sufficent or too powerful.

- Each mount struct has also an (internal) indication if it needs an
additional mount/volume password for mounting (2).  If so, the AT module will
indicate this to OmniClient that it needs a new password.  It has not exactly
decided yet how the user will fill in this extra mount/volume password.  Most
probably it will be the concatenation of password associated with the
username and the extra mount/volume password separated by some character. 
Details will follow after I get some feedback about this topic.

Case studies :
------------

1. The user does not fill in the "AppleTalk Login" window.
---------------------------------------------------------

1.1. The server has no mount points available for AppleTalk 'guests'

OmniClient shows a mount box where the user needs to fill in the
directory path of the mount point, username and password.  If the user
doesn't know the directory path, he should fill in username & password in the
"AppleTalk Login" window first and will then see all mounts accessable for
that user (case 2.).

1.2. The server has one or more mount points available for AppleTalk
'guests'.

The user will see the mount point(s) in a separate window.  On double
clicking on one of those mount points, the user will mount it with the
priveledges used to enumerate the mount points.  So, in this case it still
will be the AT guest priveledges.  If this is not was the user wants, he
should either fill in username & password in the "AppleTalk Login" window
(case 2.) or open the "Mount 'AppleTalk' server" window and fill in the right
values (case 4.).

2. The user fills in an username and password in the "AppleTalk Login" window
but these are not correct for the server on which the user clicks afterwards.
--------------------------------------------------------------------------

An WimpReportError box will appear indicating this and after clicking 'Ok',
the "Mount 'AppleTalk' server" window will be presented.  Either the user
fills this window in (case 4.) or either the user corrects the entries in the
"AppleTalk Login" and re-double-clicks on the server icon (case 3.).

Note that case 2. will also happen when the user wants to mount AT mounts of
different servers each requiring different username & passwords.  I presume
this will only happen on rare occasions as you can save all mount info using
OmniClient's 'Save Mounts'.

3. The user fills in an username and password in the "AppleTalk Login" window
suited for the server he double clicks on afterwards.
--------------------------------------------------------------------------

He will then see a list of all available mounts accessable by given username.
This case is very similar to case 1.2. but now instead of using the guest
priveledges, he now uses the priveledges for the given username.

4. The user opens the "Mount 'AppleTalk' server" window and fills in all
necessairy fields.
--------------------------------------------------------------------------

If the user knows all the details upfront, this is probably the easiest way
to mount an AT volume.

How does the AppleTalk module implement this ?
--------------------------------------------

- (Omni 3 - Enumerate mounts on a server) When enumerating the mount points
of a given server, we store the used username & password in each *new* found
mount point.

- (Omni 0 - Mount) When we mount a given mount point and no username is
supplied (ie NULL ptr) we take the username & password already associated
with this mount (during mount enumeration) instead.  If there is an valid
username supplied, we use that (together with the password) and copy these
two strings in the mount struct.  *** Question : if we really want to mount a
mount point with 'guest' priveledges and we've mounted that mount with other
priveledges than AT guest, will this be possible (as 'guest' might be equal
to NULL ptr) ??? To be investigated.

- (Omni 8 - Get (inactive/not-connected) Mount Info) This will always return
that it does NOT need an username & password *when* the mount point doesn't
need an extra mount/volume password.

- (Omni 9 - Get (active/connected) Mount Info) The username will be extracted
from the username stored in the mount struct.

Footnotes :
---------

(1) Note that I use the word 'access' and not 'mount'.  This is because each
AT mount can have an *optional* additional mount/volume password.  I deal
with this later on in the text.

(2) Note that this extra mount password (or 'Volume password' in Apple
speak), will always be sent in ClearText format which means that this
password is easily readable for everyone looking at the network packets. 0
This is more an issue for the responsible person for the AT server than for
the client user of that server.

--
John Tytgat

