(Prev Next) Part of UserLand's MIDAS Website. Wednesday, August 27, 1997.

URL Standard Apple Event Suite

The spec that connects emailers, news readers, FTP clients and web browsers on the Macintosh, at the simplest level.

November 15, 1994

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
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)
Result type: 'shor' (typeShortInteger)

Servers must support this event to conform to the standard, although support for the destination file parameter is optional.

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.

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.

For ftp URLs, if the path in the URL resolves to a directory, display the directory contents in a window. If the path resolves to a file, save the file to disk. Remember that a URL may end with a slash.

For ftp URLs, you may do further processing after getting a file and saving it to disk. E.g., do decoding and decompressing either internally or via additional helpers, display decoded picture files, etc.

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

This standard was designed by John Hardin, Peter Lewis, Steve Dorner, Farhad Anklesarian, Aleksandar Totic, and other Mac TCP/IP developers. It was edited by John Norstad <URL:mailto:j-norstad@nwu.edu>.

This page was last built with Frontier on a Macintosh on Wednesday, August 27, 1997 at 7:40:42 PM. Thanks for checking it out! Dave