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 ] -- destination file | [attaching ] -- 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) (3) URL:scheme:... (4) In addition, servers may accept various "slack" formats (e.g., "host:path" for ftp, "" 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 . | 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!" . | | 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.