CDFSFiler module 3.00 Functional Specification
----------------------------------------------

Authors: T.G.Roddis, Mike Challis



Contents
--------

 2          Purpose
 4          Product Overview
 5          Concepts and Definitions
 5.2           Concepts
 6          User Interface
 6.1           Disc sharing behaviour
 6.1.1            Service_DiscDismounted
 7          Programmer Interfaces
 8          Standards
 9          Data Interchange Formats


2. Purpose
----------

This document describes the behaviour of CDFSFiler 3.00. CDFSFiler 3.00 is
the graphical user interface (filer) component module of the CD software
system. It is highly recommended that the reader is familiar with the CD
System Specification before continuing.

4. Product Overview
-------------------

CDFSFiler works with the Filer and CDFS to provide the standard RISC OS
directory viewers as an interface to the filing system presented on CD-ROMs.

5. Concepts and Definitions
---------------------------

5.2 Concepts
------------

CDFSFiler is responsible for maintaining icons representing CD-ROM drives on
the icon bar and for the associated Filer functionality. Like other filing
system specific Filer modules, CDFSFiler cooperates with the Filer by asking
for a display of the root directory when one of its icons is clicked.

CDFSFiler requires CDFS and the Filer in order to function.


6. User Interface
-----------------

When an iconbar icon is clicked on using select or adjust, CDFSFiler attempts
to canonicalise the corresponding drive number. If successful, the message
Message_FilerOpenDir is sent to the Filer, asking to open the root directory
on the drive whose number appears below the icon in the usual format (eg :0).
Otherwise, the cause is determined (possibly after reading the TOC by a
direct call to CDManager) and a suitable error message is displayed, such as:

  "Drive empty"                -  if there is no disc in the drive
  "Drive contains audio disc"  -  if the disc in the drive is an audio disc
  "Cannot recognise data format of disc in drive"
                               -  if the disc is not ISO-9660 compliant

When the menu button is clicked over an iconbar icon, a menu appears with the
following entries:

      Dismount        forget about a disc
      Share    =>     allow other machines on a network to access the disc
      Size     =>     show disc size

The 'Share =>' entry is ungreyed only if a version of ShareFS greater than or
equal to 2.00 is loaded; it leads to the Share submenu which is described in
detail in the following subsection.

The 'Size =>' entry leads to a transient dialogue box which shows the size of
the CD in the format supplied by OS_ConvertFileSize; this includes both data
and audio tracks.

All menus and associated dialogue boxes are defined in the Resource files
'NoShareFS', 'NotShared' and 'Shared' that accompany this specification.

CDFSFiler is just that, a filer; it does not handle non-filing system
functions. This is significantly different from the previous version which
handled some features of audio CDs and PhotoDiscs. 


6.1 Disc sharing behaviour
--------------------------

CDFSFiler supports the export of CD-ROMs to other machines on a network
using the facilities of ShareFS and FreeWay. 

The 'Share' submenu has two entries as follows:

      Unshare
      Share...

Before displaying the submenu, CDFSFiler calls ShareFS_EnumerateShares to
find out whether the root directory of the disc that is currently in the
drive is shared or not.

If the root directory of the disc currently in the drive is shared, 'Unshare'
is ungreyed and 'Share...' is greyed. Selecting 'Unshare' calls
ShareFS_StopShare to unshare the disc.

If the root directory of the disc currently in the drive is not shared,
'Unshare' is greyed and 'Share ...' is ungreyed. Selecting 'Share...'
displays a transient dialogue box with the following fields:

      Disc name: <a display field containing the disc's name>
      Share as:  <a writable field>

and these two action buttons:

      Cancel
      Share   <default action button>

The 'Share as' field contains at most 10 characters, and is initialised to
(the first ten characters of) the disc's name.

Clicking 'Cancel' cancels the dialogue: no changes are made.

Clicking 'Share' calls ShareFS_CreateShare to share the disc as shown.


6.1.1 Service_DiscDismounted
----------------------------

This service call is issued by CDFS whenever a disc is dismounted - either
explicitly, or as a result of being 'forgotten' by the filing system.

If the call refers to a CDFS disc, CDFSFiler calls ShareFS_EnumerateShares
to examine each current share in turn. Any which refer to directories on the
dismounted disc are unshared by calling ShareFS_StopShare.


7. Programmer Interfaces
------------------------

There is no programmer interface to CDFSFiler.



8. Standards
------------

CDFSFiler adheres to the behaviour laid out in chapter 41 of the PRMs - The
Filer.

It supports interactive help (responding to Message_HelpRequest).

It is internationalised.


9. Data Interchange Formats
---------------------------

No interpretation is placed on the data accessed using the CDFSFiler module.
In addition no interpretation is done of filenames, as CDFS carries out all
the translation necessary and FileSwitch truncates as is deemed necessary.