[Table - 3 rows and 1 column] [Row 1, column 1] [Image] [Row 2, column 1] Acorn URI Handler Functional Specification [Row 3, column 1] [Image] Document Status [Table - 13 rows and 2 columns] [Row 1, column 1] Distribution:   [Row 1, column 2] General Release [Row 2, column 1] Title:   [Row 2, column 2] URI Handler Functional Specification [Row 3, column 1] Drawing Number:   [Row 3, column 2] 1215,215/FS [Row 4, column 1] Issue:   [Row 4, column 2] 1 [Row 5, column 1] Author(s):   [Row 5, column 2] Carl Elkins [Row 6, column 1]   [Row 6, column 2] Stewart Brodie [Row 7, column 1]   [Row 7, column 2] Kevin Bracey [Row 8, column 1]   [Row 8, column 2] Simon Middleton [Row 9, column 1]   [Row 9, column 2] Ben Laughton [Row 10, column 1]   [Row 10, column 2] Andrew Hodgkinson [Row 11, column 1] Date:   [Row 11, column 2] 02/03/98 [Row 12, column 1] Change Number:   [Row 12, column 2] N/A [Row 13, column 1] Last Issue:   [Row 13, column 2] N/A Contents i. Document Status [Ref 1] ii. Issue History [Ref 2] iii. Overview [Ref 3] iv. Deliverable 'product' [Ref 4] v. Programmer's Interface [Ref 5] 1. URI SWIs [Ref 6] A. URI_Version (&4E380) [Ref 7] B. URI_Dispatch (&4E381) [Ref 8] C. URI_RequestURI (&4E382) [Ref 9] D. URI_InvalidateURI (&4E383) [Ref 10] 2. URI Service calls [Ref 11] A. Reason 0: Service_URI_Started [Ref 12] (URI handler started) B. Reason 1: Service_URI_Dying [Ref 13] (URI handler dying) C. Reason 2: Service_URI_Process [Ref 14] (check or process URI) D. Reason 3: Service_URI_ReturnResult [Ref 15] (return result of dispatch) 3. WIMP messages [Ref 16] A. Message &4E380: URI_MStarted [Ref 17] (URI handler started) B. Message &4E381: URI_MDying [Ref 18] (URI handler dying) C. Message &4E382: URI_MProcess [Ref 19] (check or process URI) D. Message &4E383: URI_MReturnResult [Ref 20] (return result of dispatch) E. Message &4E384: URI_MProcessAck [Ref 21] (acknowledge URI_MProcess) 4. * Commands [Ref 22] A. *Desktop_AcornURI [Ref 23] (starts the URI handler) B. *URIinfo [Ref 24] (display information about the URI handler) C. *URIdispatch [Ref 25] (try to launch a URI) 5. URI Handler errors [Ref 26] A. Defined errors [Ref 27] B. Error generators [Ref 28] 6. Use of the URI filetype [Ref 29] 7. Use of URI environment variables [Ref 30] vi. Performance targets [Ref 31] Issue history This document first appeared as 1307,260/FS and went through issues 1 to 8, with 8 being published outside of Acorn. The document number was later changed to 1215,215/FS. [Table - 16 rows and 3 columns] [Row 1, column 1] 1307,260/FS [Row 1, column 3] (Developers and, by issue 8, general release) [Row 2, column 1] 1 [Row 2, column 2] 13/12/96 [Row 2, column 3] Original Version [Row 3, column 1] 2 [Row 3, column 2] 21/12/96 [Row 3, column 3] Added 'handles' concept after discussions with S.Brodie [Row 4, column 1] 3 [Row 4, column 2] 22/02/97 [Row 4, column 3] Corrected omission of URI handle from Message_ReturnResult, clarified responsibility for invalidation of URIs [Row 5, column 1] 4 [Row 5, column 2] 21/04/97 [Row 5, column 3] Added URI_MProcessAck message and *command documentation and updated URI filetype section [Row 6, column 1] 5 [Row 6, column 2] 13/06/97 [Row 6, column 3] Service calls given flags, so 'Check' service call removed. R0 return of URI_Dispatch now a bitfield, not a return value. Added Service_MReturnResult. Desktop_URI renamed to Desktop_AcornURIto match the actual module task name. URI file contents specified; includes a version number linked to the module version, so this specifies a version 5 file. [Row 7, column 1] 6 [Row 7, column 2] 20/06/97 [Row 7, column 3] Following review of draft 5, some minor wording changes here and there; performance targets and development test strategy sections added [Row 8, column 1] 7 [Row 8, column 2] 21/06/97 [Row 8, column 3] Reworded away from future tense to form an externally releasable specification [Row 9, column 1] 8 [Row 9, column 2] 10/12/97 [Row 9, column 3] A couple of implied future tense references missed in Draft 7, now corrected; some minor rewording associated with this [Row 10, column 1]   [Row 10, column 2] 11/12/97 [Row 10, column 3] No longer draft; settled on WIMP rather than Wimp; couple of minor typos corrected [Row 11, column 1]   [Row 11, column 2] 05/01/98 [Row 11, column 3] Few more typos fixed ('21', '23', 'URI_ProcessAck' and 'URIProcessAck' instead of 'R2', '32', 'URI_MProcessAck' and again 'URI_MProcessAck' respectively) [Row 12, column 1]   [Row 12, column 2] 05/02/98 [Row 12, column 3] Minor tweaks to fit in with the rest of the Acorn Internet site (now uses a small style sheet like everything else, site map [Ref 32] link added, and so-on). No changes to the content of the specification [Row 13, column 1]   [Row 13, column 2] 19/02/98 [Row 13, column 3] A few HTML style changes to make some of the section headings a bit clearer; no content change [Row 14, column 1]   [Row 14, column 2] 23/02/98 [Row 14, column 3] Colours changed to blue; now back to green again [Row 15, column 1] 1215,215/FS [Row 15, column 3] (General release) [Row 16, column 1] 1 [Row 16, column 2] 02/03/98 [Row 16, column 3] Document number now 1215,215/FS. Updated history, and navigation links in the page footer now include the specifications section; no other content changes Overview This document addresses the recognised lack of existing RISC OS specifications that describe a standard method for different applications to communicate URIs (of which URLs are an example) between themselves; for example, to provide for an address book requesting that a Web browser display someone's home page. The first part of this requirement addressed is the provision of a mechanism for applications to pass URIs between themselves in a uniform manner. To date, several third party developers have independently solved this problem in a variety of different ways, as there was no centrally published, universally available standard for developers to work to. This is such a standard. This 'central resource broker' will be extended in the future to provide mechanisms to enable more efficient handling of URIs. For example, data may be passed to an appropriate application based on the type of data as opposed to simply the method specified for retrieval of the data, as is often the case with URLs. This too will be via a service interface to the central broker. Deliverable 'product' This document describes the API created to fulfil the above stated requirement, and relates to existing software providing the underlying functionality. The software takes the form of a RISC OS relocatable module, entitled 'AcornURI'. This is a generic, OS-level software component that could as equally sit beneath a text editor which was aware of the form of URIs as sit beneath a Web browser or mail / news reader. Distributed alongside the module are four sprite definitions for URI files. The module is suitable for RISC OS 3.10 upwards, and should be stored in !System.310.Modules.Network as 'URI'. An archive containing the module, sprites, a text version of this specification and a brief ReadMe describing the component versions can be downloaded here [Ref 33] (SparkFS format). Programmer's interface The application programmer's interface to the services provided by the Acorn URI handler is detailed in the following sections. This interface will be enhanced in the future, as outlined in the overview, to provide a more comprehensive set of services; so it's worth emphasising that only those details and features of the interface specified in the following sections should be considered to be supported. Any behaviour which is not specified below should be considered to be an implementation feature of a particular version of the software, and as such liable to change, alteration or omission without notice. The following have been allocated for the use of the Acorn URI handler: [Table - 7 rows and 2 columns] [Row 1, column 1] Module name [Row 1, column 2] URI [Row 2, column 1] SWI prefix [Row 2, column 2] URI [Row 3, column 1] SWI chunk [Row 3, column 2] &4E380 [Row 4, column 1] WIMP message chunk [Row 4, column 2] &4E380 [Row 5, column 1] Error code chunk [Row 5, column 2] &810A00 [Row 6, column 1] Service Call [Row 6, column 2] &A7 [Row 7, column 1] FileType [Row 7, column 2] &F91 All environment variables containing the string _URI_ (i.e. matching *_URI_*) URI 'handles' are utilised to identify a specific URI request when communicating with the URI handler; tasks may assume nothing about these handle values, other than that they identify a particular URI to the handler for the period of their validity. URI SWIs [Table - 1 row and 1 column] [Row 1, column 1] URI_Version (&4E380) On entry [Table - 2 rows and 3 columns] [Row 1, column 1] R0 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0-31  [Row 2, column 3] reserved (0) On exit [Table - 1 row and 1 column] [Row 1, column 1] R0 = current version * 100 Interrupts Undefined Re-entrancy Undefined Use This SWI is used to inquire of the URI handler module's version number, and should be used to check for a suitable version being present before using the facilities provided. The number returned is of the form (major version * 100) + minor version. [Table - 1 row and 1 column] [Row 1, column 1] URI_Dispatch (&4E381) On entry [Table - 7 rows and 3 columns] [Row 1, column 1] R0 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0 [Row 2, column 3] inform caller of result (=>R2 valid) [Row 3, column 1]   [Row 3, column 2] 1 [Row 3, column 3] check only, don't process (R0:0 must be set) [Row 4, column 1]   [Row 4, column 2] 2 [Row 4, column 3] don't attempt external process startup [Row 5, column 1]   [Row 5, column 2] 3-31  [Row 5, column 3] reserved (0) [Row 6, column 1] R1 = pointer to 0 terminated URI string [Row 7, column 1] R2 = 0, or source task handle if bit R0:0 is set and the caller is a WIMP task On exit [Table - 6 rows and 3 columns] [Row 1, column 1] R0 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0 [Row 2, column 3] request rejected, URI won't be dispatched [Row 3, column 1]   [Row 3, column 2] 1-31  [Row 3, column 3] reserved (0) [Row 4, column 1] R2 = task handle of URI handler [Row 5, column 1] R3 = handle of this URI (request identifier) [Row 6, column 1] All other registers preserved. Interrupts Undefined Re-entrancy SWI is not re-entrant Use This SWI is used by an application to pass a URI string to the handler for dispatch, or checking for the presence of a potential servicer. Dispatch provides for optional requesting of a success/failure indication (R0:0 set) via a WIMP message (URI_MReturnResult) or service call reason code (Service_URI_ReturnResult) - necessary since the dispatch of the URI occurs asynchronously. If R0:0 is set, module clients must signal that a URI_MReturnResult message is not necessary by setting R2 to 0. In this case, only the service call will be sent out. Conversely, WIMP task clients must specify a valid task handle in R2 - in this case, only the WIMP message will be sent out. When requesting a check only (R0:1 set), it is an error not to set R0:0 and fill in R2 as described above. The URI will be copied to the URI handler's workspace, optionally transformed (future enhancement, such as canonicalisation), then relocatable modules will be offered the chance to handle the URI via service call &A7 with an appropriate reason code (Service_URI_Process); if the service call is unclaimed, then a User_Message_Recorded WIMP message will be broadcasted (URI_MProcess), offering other tasks the chance of handling the URI; if neither of these mechanisms elicits a response, then the request will be deemed to have failed (in so far as active tasks are concerned). If R0:2 is clear, then the 'fallback' position of checking a subset of the environment variables will be used to attempt to start a suitable task to handle the URI. The handle ceases to be valid at this point if notification has not been requested, irrespective of whether or not the URI has processed. If R0:0 is set, the originating task will be informed of the results of the dispatch process (via a User_Message_Recorded WIMP message URI_MReturnResult if R2 contains a valid task handle, or service call Service_URI_ReturnResult if R2 is zero). If the message is not acknowledged or service call claimed, the handle will cease to be valid; otherwise, the originating task becomes responsible for indicating that it no longer needs the URI by calling SWI URI_InvalidateURI. [Table - 1 row and 1 column] [Row 1, column 1] URI_RequestURI (&4E382) On entry [Table - 5 rows and 3 columns] [Row 1, column 1] R0 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0-31  [Row 2, column 3] reserved (0) [Row 3, column 1] R1 = pointer to buffer to hold URI or 0 to read required size [Row 4, column 1] R2 = length of buffer or unused (if R1 = 0) [Row 5, column 1] R3 = URI handle On exit [Table - 2 rows and 1 column] [Row 1, column 1] R2 = offset into buffer of terminating null, or size of buffer required (if R1 = 0 on entry) [Row 2, column 1] All other registers preserved. Interrupts Undefined Re-entrancy SWI is not re-entrant Use This SWI is used to inquire what size of buffer is required to hold the specified URI (if R1 is zero on entry), or to pass details of a buffer into which your task desires the URI to be copied. If this is successful, then R2 should be equal to the size of the buffer: if the buffer specified on entry is not large enough, then R2 will be returned negative (indicating the number of unreturned characters), and the string returned in the buffer will still be zero-terminated i.e. buffersize-1 characters of the string are returned. [Table - 1 row and 1 column] [Row 1, column 1] URI_InvalidateURI (&4E383) On entry [Table - 3 rows and 3 columns] [Row 1, column 1] R0 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0-31  [Row 2, column 3] reserved (0) [Row 3, column 1] R3 = URI handle On exit [Table - 1 row and 1 column] [Row 1, column 1] All registers preserved. Interrupts Undefined Re-entrancy SWI is not re-entrant Use This SWI is used to mark the specified URI as being invalid. URI service calls Service call &A7 has been allocated for the use of the URI handler; the following sub-reason codes are defined for the use of external applications. All other service call reason codes are reserved: a module may assume nothing about these, and should always ignore unrecognised reason codes - never claim such service calls. A deliberate degree of similarly exists between the WIMP messages and the service calls, since both provide essentially the same functionality; clearly, messages will be convenient in environments where service calls are not and vice versa, hence the duplication of functionality between the two. [Table - 2 rows and 1 column] [Row 1, column 1] Reason 0: Service_URI_Started [Row 2, column 1] URI handler started On entry [Table - 4 rows and 3 columns] [Row 1, column 1] R0 = 0 (reason code) [Row 2, column 1] R1 = &A7 (service call) [Row 3, column 1] R2 = flags:  [Row 3, column 2] bit [Row 3, column 3] meaning if set [Row 4, column 1]   [Row 4, column 2] 0-31  [Row 4, column 3] reserved (0) On exit [Table - 1 row and 1 column] [Row 1, column 1] All registers must be preserved - the call must be passed on. Use This service call indicates that the URI handler has started. It is intended for more specific use defined in future versions of this specification. [Table - 2 rows and 1 column] [Row 1, column 1] Reason 1: Service_URI_Dying [Row 2, column 1] URI handler dying On entry [Table - 4 rows and 3 columns] [Row 1, column 1] R0 = 1 (reason code) [Row 2, column 1] R1 = &A7 (service call) [Row 3, column 1] R2 = flags:  [Row 3, column 2] bit [Row 3, column 3] meaning if set [Row 4, column 1]   [Row 4, column 2] 0-31  [Row 4, column 3] reserved (0) On exit [Table - 1 row and 1 column] [Row 1, column 1] All registers must be preserved - the call must be passed on. Use This service call indicates that the URI handler is dying. It is intended for more specific use defined in future versions of this specification. [Table - 2 rows and 1 column] [Row 1, column 1] Reason 2: Service_URI_Process [Row 2, column 1] Process or check URI On entry [Table - 7 rows and 3 columns] [Row 1, column 1] R0 = 2 (reason code) [Row 2, column 1] R1 = &A7 (service call) [Row 3, column 1] R2 = flags:  [Row 3, column 2] bit [Row 3, column 3] meaning if set [Row 4, column 1]   [Row 4, column 2] 0 [Row 4, column 3] check URI only, do not process [Row 5, column 1]   [Row 5, column 2] 1-31  [Row 5, column 3] reserved (0) [Row 6, column 1] R3 = pointer to URI string (readonly access) [Row 7, column 1] R4 = handle of this URI On exit [Table - 1 row and 1 column] [Row 1, column 1] R1 preserved or 0 to claim All other registers preserved Use This service call indicates that the URI handler has been requested to dispatch the given URI for either processing (R2:0 clear), or just checking (R2:0 set). The URI string is held in the URI handler's workspace; this buffer must not be written to - if it is, behaviour is undefined. It is intended that modules should inspect the string at the given address, and if they decide they can process the given URI, claim the service call. If R2:0 is set, this is all that is required. However, if R2:0 is clear, i.e. process URI, then a call to SWI URI_RequestURI to obtain a local copy to work with must be made; this step may NOT be omitted, since the internal buffer is not guaranteed to remain valid after return from the service handler. If a module cannot process the given URI, it must pass the call on with all registers preserved to allow the remainder of the dispatch mechanism to function. [Table - 2 rows and 1 column] [Row 1, column 1] Reason 3: Service_URI_ReturnResult [Row 2, column 1] Return result of a dispatch On entry [Table - 7 rows and 3 columns] [Row 1, column 1] R0 = 3 (reason code) [Row 2, column 1] R1 = &A7 (service call) [Row 3, column 1] R2 = flags:  [Row 3, column 2] bit [Row 3, column 3] meaning if set [Row 4, column 1]   [Row 4, column 2] 0 [Row 4, column 3] 0 => URI was claimed for processing 1 => URI was not claimed for processing [Row 5, column 1]   [Row 5, column 2] 1-31  [Row 5, column 3] reserved (0) [Row 6, column 1] R3 = undefined (reserved (0)) [Row 7, column 1] R4 = handle of this URI Use This service call is used by the URI handler to return result status information to a requesting module. The module requests the service call when it calls the URI_Dispatch SWI; it must set R0:0 and R2=0 on entry. Such modules must remember the URI handle returned in R3 by this SWI or they cannot later determine if the service call was meant for them or another client; any client setting R0:0 on entry to URI_Dispatch must see if it recognises the URI handle in R4, and if so, claim the service call. If it does not recognise the handle, it must not claim the service call. Any clients which never set R0:0 on entry to URI_Dispatch can ignore the service call. Only success or failure is indicated, though this is likely to be enhanced in future. WIMP messages [Table - 2 rows and 1 column] [Row 1, column 1] Message &4E380: URI_MStarted [Row 2, column 1] URI handler started Poll block [Table - 3 rows and 3 columns] [Row 1, column 1] R1+20 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0-31  [Row 2, column 3] reserved (0) [Row 3, column 1] R1+24... undefined (reserved) Use This message is broadcast (User_Message) to indicate that the URI handler has started up. It must not be acknowledged - information only. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4E381: URI_MDying [Row 2, column 1] URI handler dying Poll block [Table - 3 rows and 3 columns] [Row 1, column 1] R1+20 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0-31  [Row 2, column 3] reserved (0) [Row 3, column 1] R1+24... undefined (reserved) Use This message is broadcast (User_Message) to indicate that the URI handler is shutting down. It must not be acknowledged - information only. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4E382: URI_MProcess [Row 2, column 1] Process or check URI Poll block [Table - 6 rows and 3 columns] [Row 1, column 1] R1+20 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0 [Row 2, column 3] check URI only, do not process [Row 3, column 1]   [Row 3, column 2] 0-31  [Row 3, column 3] reserved (0) [Row 4, column 1] R1+24 = pointer to URI string (URI internal buffer) [Row 5, column 1] R1+28 = URI handle [Row 6, column 1] R1+32... undefined (reserved) Use This message is broadcast (User_Message_Recorded) to indicate that the URI handler has been requested to dispatch the given URI for processing, or check if any task can process the URI. The URI string is held in the URI module's workspace; this buffer must not be written to - if it is, behaviour is undefined. It is intended that applications which can process URIs should inspect the string at the given address to determine if they can process the URI. If R0 bit 0 is clear, you must then call SWI URI_RequestURI to obtain a copy to work with - this step may not be omitted, since the buffer given is not guaranteed to remain unaltered. If an application is able to check or process the given URI, then it should acknowledge the broadcast by sending a URI_MProcessAck message to the URI handler, thus preventing it being passed on to other applications, otherwise it must not acknowledge the message. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4E383: URI_MReturnResult [Row 2, column 1] Return result of a dispatch Poll block [Table - 5 rows and 3 columns] [Row 1, column 1] R1+20 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0  [Row 2, column 3] 0 => URI was claimed for processing 1 => URI was not claimed for processing [Row 3, column 1]   [Row 3, column 2] 1-31  [Row 3, column 3] reserved (0) [Row 4, column 1] R1+24 = URI handle [Row 5, column 1] R1+28... undefined (reserved) Use This message is used by the URI handler to return result status information to a requesting task. Only success or failure is indicated, though this is likely to be enhanced in future. [Table - 2 rows and 1 column] [Row 1, column 1] Message &4E384: URI_MProcessAck [Row 2, column 1] Acknowledge URI_MProcess Poll block [Table - 6 rows and 3 columns] [Row 1, column 1] R1+20 = flags:  [Row 1, column 2] bit [Row 1, column 3] meaning if set [Row 2, column 1]   [Row 2, column 2] 0  [Row 2, column 3] Check URI only, do not process [Row 3, column 1]   [Row 3, column 2] 1-31  [Row 3, column 3] reserved (0) [Row 4, column 1] R1+24 = pointer to URI string (URI internal buffer) [Row 5, column 1] R1+28 = URI handle [Row 6, column 1] R1+32... undefined (reserved) Use This message is used by clients of the URI handler to indicate to the URI handler that they can claim or process a given URI, thus preventing it being passed on to other applications. Claimants just change the message type to &4E384 (URI_MProcessAck) and copy the supplied my_ref field into your_ref, then send the message back to its originator (ie. the URI handler). * Commands *Desktop_AcornURI Starts the URI handler Syntax *Desktop_AcornURI Parameters None Use *Desktop_AcornURI starts the Acorn URI handler. Do not use *Desktop_AcornURI, use *Desktop instead. Help text Do not use *Desktop_AcornURI, use *Desktop instead. Syntax: *Desktop_AcornURI Example *Desktop_AcornURI Use *Desktop to start AcornURI Related commands None Related SWIs None Related vectors None *URIinfo Display information about the URI handler Syntax *URIinfo Parameters None Use *URIinfo produces status information from the Acorn URI handler Help text URIinfo produces status information from the Acorn URI handler. Syntax: *URIinfo Example *URIinfo URI_taskhandle: 4b4016d8 URI chain start: 021cc844 URI handle: 022b60d4 (action:00020000) 'http://www.acorn.com/' Related commands None Related SWIs None Related vectors None *URIdispatch Try to launch a URI Syntax *URIdispatch Parameters uri: the uri to be launched Use *URIdispatch tries to lauch a given URI. No indication is given of whether or not the launch succeeded. Help text URIdispatch tries to launch a URI. Syntax: *URIdispatch Example *URIdispatch http://www.acorn.com/ Related commands None Related SWIs URI_Dispatch Related vectors None URI handler errors The URI handler has a error chunk base of &810a00. Currently defined errors are: [Table - 5 rows and 3 columns] [Row 1, column 1] Name [Row 1, column 2] Number [Row 1, column 3] Cause [Row 2, column 1] Error_URI_NoMemory [Row 2, column 2] Base + 1 [Row 2, column 3] There is not enough memory to complete an operation. [Row 3, column 1] Error_URI_BadURI [Row 3, column 2] Base + 2 [Row 3, column 3] An empty URI string is supplied (e.g. to URI_DispatchURI). [Row 4, column 1] Error_URI_BadHandle [Row 4, column 2] Base + 3 [Row 4, column 3] A bad URI handle has been supplied. [Row 5, column 1] Error_URI_BadFile [Row 5, column 2] Base + 4 [Row 5, column 3] Reported when there is an error accessing a URI file. Generators of the errors are as follows: [Table - 5 rows and 2 columns] [Row 1, column 1] Generator [Row 1, column 2] Returns [Row 2, column 1] URI_DispatchURI [Row 2, column 2] Error_URI_NoMemory Error_URI_BadURI [Row 3, column 1] URI_RequestURI [Row 3, column 2] Error_URI_BadHandle [Row 4, column 1] URI_InvalidateURI [Row 4, column 2] Error_URI_BadHandle [Row 5, column 1] *URIDispatch [Row 5, column 2] Error_URI_NoMemory Finally, the WIMP task may generate (through a standard WIMP error box) Error_URI_NoMemory and Error_URI_BadFile. Use of the URI filetype URI files have the filetype &F91, with the text equivalent 'URI'. The URI handler will deal with such files appropriately when the file is double-clicked upon (currenly, it dispatches the URI inside the file - see the file format description below). Applications must not set an Alias$@RunType variable for the URI filetype, nor must they deal with DataOpen messages for this filetype. Applications may respond to DataLoad messages for the filetype as they see fit. Suitable sprites exist (four; medium and high resolution file sprites, small and large variants). These are the only sprite definitions acceptable for use in this context. The sprites should always be distributed alongside the module. URI files consist of a series of lines of characters. Lines are ended by any number of control code characters (ASCII code less than 32) or the end of the file. All lines in a file do not have to end in the same way provided each individual line ends in a valid manner. Other white space is not ignored, hence a single space character (ASCII code 32) followed by ASCII code 9 does count as a line containing a single space followed by a line end marker. URI files support comments. Comment lines start with a '#' (ASCII 35) and end in the same way as all other lines. Comment lines are not counted; any file reader that happened to keep track of the line number it was on should not increment the counter for a comment line. A URI file may contain any number of comment lines, but automatic file generators are encouraged to keep comments to a bare minimum to keep file sizes down. Generator code must never create special comment lines which mean something to accompanying reader code - comment lines are always skipped by the reader code and never parsed, beyond identifying them as comments. The line ending type of a URI file is not fixed as a specific control code or sequence of control codes (e.g. CR+LF) to allow simple generation from a variety of sources, including manual authoring. Given this latter possibility, it is important to stress that unlike, say, HTML, the URI file format is rigorously defined and must be adhered to. Incorrectly formed files are not guaranteed to work correctly with either the Acorn URI handler or applications which support it. That said, the use of ASCII code 13 followed by ASCII code 10 (CR+LF) to end lines is strongly encouraged as this is a common line ending type supported by many different editors on many platforms. ASCII code 9 (tab) could also be used to give the file a better visual appearence in the editor - it is still an end of line as far as the file reader is concerned. This convention provides the potential for greater convenience for the end-user, but must NOT be assumed in file reading code! Currently defined formats: [Table - 5 rows and 3 columns] [Row 1, column 1] Supporting URI module version [Row 1, column 2] Line number [Row 1, column 3] Contents [Row 2, column 1] (None at present) [Row 2, column 2] 1 [Row 2, column 3] 'URI' - this must be present before any comments or other information. [Row 3, column 1]   [Row 3, column 2] 2 [Row 3, column 3] Text equivalent of the earliest module version number (as returned by URI_Version) that would fully understand the file contents; e.g. '5' for v0.05 (any number of preceeding '0's are also valid). So if lines were added to this file format to produce a version 6 file, this implies that URI v0.06 is required to understand those extra lines, even though v0.05 would still understand lines 1 to 4. The first general release version of the URI handler will adopt a version number of 1.00, so the first URI files will start with '100' in this line. [Row 4, column 1]   [Row 4, column 2] 3 [Row 4, column 3] A fully specified URI; v0.05 of the URI handler does not attempt to canonicalise URIs, though future versions may. If this line contains only one character with ASCII code 42 ('*'), the file does not contain a URI and should be ignored (this is to allow future file formats to hold non-fully specified URIs on later lines that could be canonicalised by the URI module, without breaking legacy file reading code). Lines 1 to 3 are required in a minimal URI file. Any other lines may or may not appear. [Row 5, column 1]   [Row 5, column 2] 4 [Row 5, column 3] A title string to associate with the URI. Again, if this line contains only one character with ASCII code 42 ('*'), the file does not contain a title string. Processors wishing to display title information alongside a URI may well use the URI itself instead, in this case. You can find some examples of URI files in a SparkFS format archive here [Ref 34]. Future file formats will be backwards compatible with this one, so clients should only check the version number of the file to know what sort of contents to expect. So for example, if a version 100 aware application encounters a later version file, it can assume that the first 4 lines of the file are as described for the version 100 file; though there may be other lines which clearly it cannot understand, and must ignore. For example, the file format rationale may be easier to understand given the possibility of a future format - version 101, say - which allowed non-fully specified URIs in line 5 which can be canonicalised, and a preferred external process to start in line 6. The file could look like this: -Start of file- URI 6 * Acorn Group PLC www.acorn.com .!Run -End of file- Use of URI environment variables Currently defined variables are of the form: Alias$Open_URI_ for example, Alias$Open_URI_http .!Run Alias$Open_URI_ftp .!Run If a variable such as the above is defined, then the task it names will be run. If this is successful, the URI will be redispatched in the normal way, so the task has the opportunity of dealing with it. A comma separated list of handlers may be specified, so applications must always add to the contents of the variables. At present, only the first item in the list is used, though this may change in future versions. For compatability with existing applications, the URI handler will support a similar scheme of system variables defined by ANT Ltd. Details of these are at the time of writing freely available on the ANT web site. [Ref 35] Performance targets Final code size of version 1.00 should be about 26K. Quiescent memory usage should be no more than 512 bytes. When active, the main storage requirement for each URI being processed is storage of the URI itself. This is, then, indeterminate, but unlikely to be more than 2K (not that the URI handler will have any such hard coded limits). An additional overhead of no more than 128 bytes per URI is also required. home [Ref 36] - manual [Ref 37] - downloads [Ref 38] - f.a.q [Ref 39] - feedback [Ref 40] hints and tips [Ref 41] - specifications [Ref 42] - other sites [Ref 43] - site map [Ref 44] [Table - 1 row and 2 columns] [Row 1, column 1] Last updated 23 March 1998 — Site comments? EMail webmaster@acorn.com [Ref 45] © Acorn Computers Limited, 1997 [Ref 46] [Row 1, column 2] [Valid HTML 4.0] [Ref 47] ============================================================================== References in this document: 1. http://www.acorn.com/browser/uri/funcspec.html#dost 2. http://www.acorn.com/browser/uri/funcspec.html#ishi 3. http://www.acorn.com/browser/uri/funcspec.html#over 4. http://www.acorn.com/browser/uri/funcspec.html#depr 5. http://www.acorn.com/browser/uri/funcspec.html#prin 6. http://www.acorn.com/browser/uri/funcspec.html#ursw 7. http://www.acorn.com/browser/uri/funcspec.html#swi4e380 8. http://www.acorn.com/browser/uri/funcspec.html#swi4e381 9. http://www.acorn.com/browser/uri/funcspec.html#swi4e382 10. http://www.acorn.com/browser/uri/funcspec.html#swi4e383 11. http://www.acorn.com/browser/uri/funcspec.html#urse 12. http://www.acorn.com/browser/uri/funcspec.html#reason0 13. http://www.acorn.com/browser/uri/funcspec.html#reason1 14. http://www.acorn.com/browser/uri/funcspec.html#reason2 15. http://www.acorn.com/browser/uri/funcspec.html#reason3 16. http://www.acorn.com/browser/uri/funcspec.html#wime 17. http://www.acorn.com/browser/uri/funcspec.html#mes4e380 18. http://www.acorn.com/browser/uri/funcspec.html#mes4e381 19. http://www.acorn.com/browser/uri/funcspec.html#mes4e382 20. http://www.acorn.com/browser/uri/funcspec.html#mes4e383 21. http://www.acorn.com/browser/uri/funcspec.html#mes4e384 22. http://www.acorn.com/browser/uri/funcspec.html#stco 23. http://www.acorn.com/browser/uri/funcspec.html#desktop_acornuri 24. http://www.acorn.com/browser/uri/funcspec.html#uriinfo 25. http://www.acorn.com/browser/uri/funcspec.html#uridispatch 26. http://www.acorn.com/browser/uri/funcspec.html#urhe 27. http://www.acorn.com/browser/uri/funcspec.html#deer 28. http://www.acorn.com/browser/uri/funcspec.html#erge 29. http://www.acorn.com/browser/uri/funcspec.html#usfi 30. http://www.acorn.com/browser/uri/funcspec.html#usen 31. http://www.acorn.com/browser/uri/funcspec.html#peta 32. http://www.acorn.com/browser/map.html 33. http://www.acorn.com/browser/uri/URI.arc 34. http://www.acorn.com/browser/uri/Examples.arc 35. http://www.ant.co.uk/ 36. http://www.acorn.com/browser/ 37. http://www.acorn.com/browser/Manuals/Cover.html 38. http://www.acorn.com/browser/download.html 39. http://www.acorn.com/browser/faq.html 40. http://www.acorn.com/browser/bugform.html 41. http://www.acorn.com/browser/hints.html 42. http://www.acorn.com/browser/specs.html 43. http://www.acorn.com/browser/links.html 44. http://www.acorn.com/browser/map.html 45. mailto:webmaster@acorn.com 46. http://www.acorn.com/acorn/copyright.html 47. http://validator.w3.org/