home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ARM Club 3
/
TheARMClub_PDCD3.iso
/
programs
/
comms_networking
/
mimemap
/
ReadMe
< prev
Wrap
Text File
|
1998-10-14
|
9KB
|
217 lines
MimeMap a.k.a. Welcome to the wierd and wonderful world of freeware
======= (Release 3)
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.