Proxying FilerAction messages
-----------------------------

FilerAction under Select variants of RISC OS now provides the ability to
'proxy' requests for other users. This can be used to replace the
functionality of the standard FilerAction utility with another, user
supplied, application. The major use of this is to provide a means for
user provision of an updated 'Find' utility. However, this functionality
might also be used to provide an automatic waste-basket facility, or 
a more graphical count utility.

In this mode, FilerAction becomes a 'proxy' for the extended tools. Known
messages sent to the FilerAction task will be passed to their opposite
(usually this means that messages from the Filer go to FilerAction as a
proxy, and from there on to the extended tool). The reason that this -
somewhat indirect - method is used, is to provide support for older
applications. Applications unaware of the existance of the new tools will
be able to benefit from the new operation of FilerAction, and the method
of launching such tools remains backwards compatible for all clients.

To provide a tool that replaces the functionality of FilerAction you must
first set a system variable to inform it of the existence of that tool.
Generally, this will take the form :

  *Set Alias$@FilerAction_<operation> /<Obey$Dir>.!Run

Operation is one of :

  Copy       Copy a number of objects from one directory to another
  Rename     Move a number of objects from one directory to another
             by trying a rename first then doing a copy/delete if that
             fails
  Delete     Delete a number of objects in a particular directory
  Access     Set the access of a number of objects to a given value
  SetType    Set the file type of a number of objects to a given value
  Count      Count the file sizes of the selected objects
  Move       Move a number of objects from one directory by copying
             them then deleting the source
  CopyLocal  Copy a single object to a different name in the same directory
  Stamp      Stamp the selected objects with the time when they get stamped
  Find       Find an object with a given name.

These mirror the operations that FilerAction currently provides. Additional
operations will be given similarly descriptive names.

The extended tool will be launched using this command, and you should be
prepared to either support multiple invocations by starting new
applications, or by receiving multiple requests and servicing them.

Before issuing the command, FilerAction will broadcast a Message_FilerAction
(&405). Tools which are able to service the request should reply to this
message. Any tool unable to service the request (because it does not handle
that form of request, or because it is busy with another request) should
ignore the message. If the message is replied to, FilerAction will treat
that task as a client. If it bounces, FilerAction will issue the above
command to start the tool.

Once started, messages will be sent to the extended tool in exactly the
same manner as FilerAction receives them. This means that a
Message_FilerSelectedDirectory will arrive first, followed by multiple
Message_FilerAddSelection, and then finally a Message_FilerAction. The
recommended way of implementing this protocol is as follows :

parent_Task=-1
state=Idle

WHILE running
  receive message
  CASE message OF
    WHEN Message_FilerAction:
    
      CASE state OF
        WHEN Idle:
          IF messageblock.operationtype = one_we_understand THEN
            state=Starting
            parent_Task=messageblock.taskhandle
            SYS "Wimp_SendMessage",17,messageblock,parent_Task
          ELSE
            ignore it
          ENDIF
          
        WHEN Starting:
          state=Processing
          do whatever stuff we need to
      ENDCASE
      
    WHEN Message_FilerSelectionDirectory:
      IF state = Starting THEN
        remember the directory
      ENDIF
      
    WHEN Message_FilerAddSelection:
      IF state = Starting THEN
        process the names
      ENDIF
    
    WHEN Message_FilerControlAction:
      IF state = Processing THEN
        act upon control command; code 0 will always be handled for
        you, because FilerAction knows what you can do
      ENDIF
  ENDCASE
  
  IF finished_processing THEN
    state=Idle
    either:
      quit normally
    or:
      send message_TaskShutdown (&400C3) to parent_Task
  ENDIF
ENDWHILE

Implementing the protocol defined in the PRMs for FilerAction clients is
sufficient to get an initial implementation running. Adding the simple state
machine on top of this will protect against multiple tool invocations
getting confused.

You will need to handle PreQuit requests as you would in a normal
application, as FilerAction cannot do this for you.


Possible extended tools
-----------------------

There is only limited scope for extended tools, but of some of the things
that might be implemented are :

  * Delete handler which attempts to relocate files to a temporary location
    for later recovery.
  * Graphical count, displaying the distribution of filetypes - figures, bar
    chart, pie chart, synthesised music based on frequency distribution...
    whatever takes your fancy.
  * Accumulating 'Find' tool, displaying results in a throwback-like window.
  * Graphical copy tool, with lots of flying documents and silly animations

