[futurebasic] Re: Launching a URL

Message: < previous - next > : Reply : Subscribe : Cleanse
Home   : August 2001 : Group Archive : Group : All Groups

From: Ken Shmidheiser <k.shmidheiser@...>
Date: Wed, 8 Aug 2001 02:32:29 -0400
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.