FYI: "Canonicalized URL's" are defined near the end of this document:
Ken
URL Standard Apple Event Suite
==============================
| July 20, 1998
Introduction
------------
"Uniform Resource Locators" (URLs) are a standard notation on the
Internet for
identifying the locations of files and other resources.
Mac TCP/IP networking programs often make use of each other as
"helper programs".
To make it easier to do this, some of the Mac Internet software
developers have
designed a simple standard for Apple events which programs can send
each other to
ask them to open URLs.
The Suite
---------
Suite name: URL Suite
Suite description: Standard suite for Uniform Resource Locators
Suite code: 'GURL'
The geturl Event
----------------
geturl: Get a URL and display it in a window or save it to a file
geturl string -- the URL
[to <file>] -- destination file
| [attaching <list>] -- files to attach to mailto URLs
Result: small integer -- result code
Event class: 'GURL'
Event id: 'GURL'
Direct object parameter type: 'TEXT' (typeChar)
Optional destination file parameter:
keyword: 'dest'
type: 'fss ' (typeFSS)
| Optional attaching parameter:
| keyword: 'Atch'
| type: 'list' (typeAEList)
Result type: 'shor' (typeShortInteger)
Servers must support this event to conform to the standard,
although support for
| the destination file and attaching parameters is optional.
| If the attaching parameter is specified, it must be coercible to an
FSSpec or an
| AEList, each of elements must be coercible to an FSSpec.
If the destination file parameter is missing, and the referenced object is
displayable, display it in a window (an existing window or a new window,
whichever is most appropriate for your application).
If the destination file parameter is missing, and the referenced
object is not
displayable, but can be saved to a file, and if your application
has a default
download directory, save the object to that directory. If you don't have a
default download directory, present a standard file dialog only if user
interaction is allowed. Use the AEInteractWithUser function to handle user
interaction options properly.
If the destination file parameter is present, get the referenced
object and write
it to the file. Create the file if it is missing, or replace it if it already
exists.
| The attaching parameter is only significant for mailto and ftp URLs
and must be
| ignored for all other URL schemes.
For a mailto URL, open a mail message window addressed to the email
address in
the URL. The destination file parameter has no meaning for a mailto
URL, and must
| be ignored if it is specified. If the attaching parameter is specified, the
| server should attach the specified file system objects to the newly
created message.
| Servers may restrict the possible types of file system objects that
are attached,
| but must return an error if they reject one or more of the objects.
| The behaviour for ftp URLs depends on the presence of the attaching
parameter.
| If there is no attaching parameter, the server must use the FTP protocol
| to get the specified file and save it to disk (if the path of the
URL resolves
| to a file) or display the contents of the specified directory in a
window (if the
| path of the URL resolves to a directory).
Remember that a URL may end with a slash.
| When getting ftp URLs, you may do further processing after getting a file and
| saving it to disk, for example, do decoding and decompressing
either internally
or via additional helpers, display decoded picture files, etc.
| If the attaching parameter is specified for an ftp URL, the server
must upload the
| file system objects specified in the attaching parameter to the
path specified in
| the URL. The path must resolve to a directory. Transfer attributes --
| like user name, password and transfer mode -- must either be
gleaned from the URL
| or be established from some defaults.
The fetchurl Event
------------------
fetchurl: Get a URL and return it as the event result
fetchurl string -- the URL
Result: the referenced object, usually text
Event class: 'GURL'
Event id: 'FURL'
Direct object parameter type: 'TEXT' (typeChar)
Result type: usually 'TEXT' (typeChar)
Support for this event is optional.
When you get this event, fetch the referenced object and return it
as the event
result with its most natural type. For ftp URLs which resolve to directories,
return the directory listing as type 'TEXT'. For ftp URLs which
resolve to files,
return the file contents. This might be MacBinary or BinHex or
readable text or
whatever. For http URLs, return the HTML document as 'TEXT'. For
news and nntp
URLs, return the full referenced news article (header and body) as 'TEXT'. In
general, for displayable objects which you would display in a text
window in the
geturl event, return the text you would have displayed as the
function result in
the fetchurl event.
Do not display the referenced object in a window or save it to a file.
This event has no meaning for mailto URLs. Return -50 (paramErr) in
this case.
Error Handling
--------------
For the geturl event, return OS error codes as the event result.
For the fetchurl
event, use the keyErrorNumber parameter to return non-zero OS error codes.
If you cannot recognize a scheme keyword, or if you detect some other syntax
error in the URL string, return -50 (paramErr).
If you cannot locate the referenced object (e.g., a news article
does not exist
on the server, or a referenced FTP file does not exist on the
referenced host),
return -43 (fnfErr).
For other errors which are not OS errors but are rather specific to your
application, return an error number in the range 101-19999 as the
function result
for geturl or using the keyErrorNumber parameter for fetchurl.
Additional Requirements
-----------------------
Servers must support the following formats for the URL string:
(1) scheme:... (the "canonical form")
(2) <scheme:...>
(3) URL:scheme:...
(4) <URL:scheme:...>
In addition, servers may accept various "slack" formats (e.g.,
"host:path" for
ftp, "<message-id>" for news, "user@host" for mailto, etc.). This is not
required, however, and clients are strongly encouraged to canonicalize URL's
whenever possible.
Based on the principle that you should be "conservative in what you send, and
liberal in what you accept", clients should use the "canonical"
form number (1)
above whenever possible. Servers, however, must be prepared to
handle all forms
(1) through (4).
Servers may reject schemes which they can't handle directly (return the error
code paramErr), or they may instead pass such URLs on to other helpers.
Servers must be prepared to accept these events as the initial
event supplied to
the application at launch time, or later after the application is already
running. Do not assume that the first event is an 'oapp' or 'odoc' or 'pdoc'
event - it might be a 'GURL' or 'FURL' event.
When processing the events, do not use the modifier keys to change
the behavior
of the event handling. For example, do not test the Option key to determine
whether or not to present a standard file dialog.
Servers must be launchable in the background. Do not assume that
you start out in
the foreground.
Authors and Version History
---------------------------
| Version 1.0 (Nov 1994) of this standard was designed by John
Hardin, Peter N Lewis,
Steve Dorner, Farhad Anklesarian, Aleksandar Totic, and other Mac
TCP/IP developers.
It was edited by John Norstad <URL:mailto:j-norstad@...>.
| Version 1.1 of this standard was designed by Yan Arrouye, Dan
Crevier, Steve Dorner,
| Peter N Lewis, James W. Matthews, and Quinn "The Eskimo!". It was edited by
| Quinn "The Eskimo!" <URL:mailto:quinn@...>.
|
| Changes since version 1.0 are marked with change bars. The core
change is the
| optional attaching parameter to the geturl event for mailto and ftp URLs.