MimeMap a.k.a. Welcome to the wierd and wonderful world of freeware
======= (Release 5)

A number of programs have recently been writing their own MIME handling code.
This is pointless. There is a saying about reinventing wheels which is
unfortunately untrue of computing. The reason for this is copyright. It's a
pain. "You can't distribute x from package y without paying sum z to a
numbered swiss bankaccount, and in any case you'll not get support for it
anyhow." The MimeMap module is one of these things. ANT own the copyright,
and therefore we can't distribute it in our programs.

So, we end up with people re-writing it (usually badly) every time they want
to use it. This isn't to say that MimeMap is written well, but it is the
'official' way of doing things. Hence, it is pointless.

So, after chatting with Joseph Heenan on IRC with him putting forward his
arguments against supporting MimeMap and me generally complaining because I'm
an awkward person, it was decided that until a freeware MimeMap module became
available, he would not support it.

A very reasonable argument.

So, now it exists, and there can be no arguments on that score.


Other rants on the same topic
-----------------------------
I like things being modular. Sometimes they may be badly thought out or
implemented, but modularity is a Good Thing. The MimeMap module is a Good
Thing by that token. The Resolver module is a Good Thing. However, the same
restrictions apply to it, so people insist on including large chunks of
Stewart Brodie's probably excellent resolver code in every application. Why
is this wrong ? Two reasons :
  1) It's duplicating code which is available elsewhere in the system (if the
     Resolver were freely available)
  2) It's no bloody good to BASIC programmers who just want a simple
     multitasking resolve.

And, as if that were not enough, the same thing happens with services. If you
use C you're really happy. You've got the lovelly 'getservent' call. But we
humble BASIC and assembler programmers have to re-write the whole thing every
time.

Actually that latter is untrue. It would be true, if I hadn't written the
IServices module which does just that. Along similar lines is the socket error
code lookup, and IServices includes that too.

Someday, we'll have a truely usable internet suite. I hope.


MimeMap interface
-----------------
Paraphrased from the ANT web site documentation :

MimeMap_Translate (&50B00)
=> R0 = input type
   R1 = input data
   R2 = output type
   R3 = output buffer, 128 bytes long
<= R3 = output buffer, or value

Converts one form of type to another.

Types available are :
  0   RISC OS type number (in r1/r3)
  1   RISC OS type name (pointed to by r1/r3)
  2   MIME type name (pointed to by r1/r3)
  3   Extension name (pointed to by r1/r3)
Other Reserved

Extension name may be preceeded by a dot, it will be ignored. When returning
extensions, only the first one is given. This is the published interface by
ANT.


*MimeMap [<filetype> | &<number> | <type>/<subtype> | .<extension> ]

Displays either a particular type, or the whole MimeMap database.


*ReadMimeMap

Forces a re-read of the MimeMap database. This should not be necessary unless
the database lives on a remote server or is modified remotely.


<Inet$MimeMappings>

This is the file used to read mappings from.


Deviance from ANTs MimeMap module
---------------------------------
Sorry, but a few things are different :

 * When you do *MimeMap, the textual representation of the type is given after
   the hex type.
 * The previously published MimeMap interface (&BCD00) is now obsolete and
   should never have been used by ANT. &50B00 is correct.
 * *ReadMimeMap and loading the module take place much faster
 * Memory usage is probably slightly higher, and my module is about 1k longer.
   That's my general laziness and reuse of libraries rather than writing things
   afresh. Sorry.
 * The MimeMap file is monitored for changes and as soon as a change is made
   it is re-read.
 * Error text from the modules is slightly different.
 * Parsing of the MimeMap file with respect to wildcards is slightly different.
   In practice this will make little difference I feel.
 * Passing invalid types to the module will not give address exceptions
 * Calling other SWIs than MimeMap_Translate will give 'MimeMap SWI not known'
   (ANT's treats all SWIs as the same).
 
Anything else that is different about the modules is purely my own fault,
please contact me (gerph@thevillage.ndirect.co.uk)


Other notes
-----------
* MimeMap should live as System:Modules.Network.MimeMap, or Inet:Rm.MimeMap.
* This module is version 0.10, which is the same as the version of MimeMap
  which I have. You should ensure that you are using 0.10 or later. Earlier
  versions of the ANT mapper are probably broken and should never be used.
* There is no excuse for not supporting MimeMap now as this module is freely
  available for distribution.
* You should never set or modify Inet$MimeMappings, unless that is the
  point of doing so. This is a user defined variable, which will be set
  when MimeMap loads if it is not already. It defaults to InetDBase:MimeMap


Ensuring the module
-------------------
If you use the MimeMap module in an application you should ensure it in the
!Run file of the application. The following template should suffice for most
purposes :

Set MimeMap$Path System:Modules.Network.,Inet:Rm.
RMEnsure MimeMap 0.10 RMLoad MimeMap:MimeMap
RMEnsure MimeMap 0.10 Error This application requires MimeMap version 0.10. Please contact your supplier
Unset MimeMap$Path


MimeMap file
------------
The MimeMap file, pointed to by Inet$MimeMappings has the following format :

* Lines starting with a # are comments, space or tab are comments and are
  ignored.
* Each line consists of up to four entities :
     Mime type/subtype pair
     RISC OS name
     RISC OS type number (in hex)
     List of extensions, whitespace seperated
  These are whitespace (tab or space) seperated. The Mimetype and RISC OS
  name are wildcard matched when a translation is requested, with * matching
  multiple characters, and # matching single characters. All textual
  comparisons are case insentitive. The type number may be specified as * to
  match any.
* Each extension should start with a period (.), but this is not required.
* It is usual to group by MIME type.
* Many to one mappings are possible on all fields, but bear in mind that
  the file is checked from top to bottom and terminates on the first match
  (wild or not).
* As stated above, order in the file /is/ important.

And example file is kindly supplied by Joseph Heenan and is covered by the
same licence as this package. An 'up to date' copy of this file can be
obtained from <http://www.ping.demon.co.uk/acorn.download.html>.


Thanks
------
Many thanks are due to Joseph Heenan, without whom this module would never
have come about and whose support and critisisms have made it what you see
now. It is also to Joseph Heenan that I owe thanks for writing the ModInst
program, specifically for this purpose.

Andrew Hodgkinson must be thanked for his very helpful comments on how
Browse deals with Mime-types and aid in understanding why FTP fetches were
dying because of MimeMap.


Licence
-------
    MimeMap - a free alternative to the ANT/Acorn mapper
    Copyright (C) 1998, Justin Fletcher
    
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA


History
-------
Release 1:
  Contained a misfeature which caused it to crash on RISC OS 3.1.
Release 2:
  RISC OS 3.1 failure has been tracked to the 'realloc()' routine returning
  -1 under some circumstances. The only time this may occur (by my reading
  of the documentation) is when the pointer passed to it was not allocated
  using calloc or malloc. Since it always has, I do not understand why it
  fails.
  Inet$MimeMappings variable is now set when the module loads /and/
  initialisation continues (used to exit anyhow).
Release 3:
  Release 2 failed to copy strings correctly into their destination buffers.
  This resulted in Browse crashing regularly.
Release 4:
  Provided a 'shortcut' for upcalls which we are not interested in. This
  prevents certain OLE based applications which use PipeFS as their transfer
  medium from running very slowly.
Release 5:
  If Inet$MimeMap is set to "" then it is now treated as unset. Somebody
  appears to have reported this on the Pluto list. Odd how it wasn't reported
  to me though.
