Acorn URI Handler Functional Specification ========================================== Document Status --------------- Distribution: General Developer Community Title: URI Handler Functional Specification Drawing Number: unassigned/FS Issue: DRAFT 2 ***live*** Author(s): Carl Elkins Tom Hughes Kevin Bracey Date: 12/12/96 Change Number: N/A Last Issue: N/A Contents -------- Acorn URI Handler Functional Specification Document Status Contents Issue History Overview Deliverable 'product' Programmer's Interface URI SWIs URI_Version (&4E380) URI_Dispatch (&4E381) URI_RequestURI (&4E382) URI_InvalidateURI (&4E383) URI Service calls Reason 0 - URI handler started Reason 0 - URI handler started Reason 1 - URI handler dying Reason 2/3 - Request to check/process URI WIMP messages Message &4E380 - URI handler started Message &4E381 - URI handler dying Message &4E382 - Request to check/process URI Message &4E383 - URI return result Use of the URI filetype Use of URI environment variables Usage of the Acorn URI handler Issue History ------------- 1 13/12/96 Original Version 2 21/12/96 Added 'handles' concept after discussions with S.Brodie. Overview -------- The purpose of this document is to address the recognised deficiency in the failure of existing RISC OS specifications to provide a standard method for different applications to communicate URIs (of which URLs are an example) between themselves; for example, to provide for a field in an address book program requesting that a Web browser display someone's home page. The first part of this requirement to be 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, but there is no centrally published, universally available standard for developers to work to. This 'central resource broker' will be extended in the future to provide mechanisms to enable more efficient handling of URIs, enabling, for example, data to 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' --------------------- The intention of this project is to deliver the specification of a suitable API to fulfil the above stated requirement, along with such software as is required to implement the underlying functionality to enable the use of this API. In the short term, this software will take the form of a RISC OS relocatable module, though this may be enhanced and supplemented as the authors see fit. 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 project 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: anything 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 Module name URI SWI prefix URI SWI chunk &4E380 WIMP message chunk &4E380 Error code chunk &810A00 Service Call &A7 FileType &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 -------- The following SWIs are provided for external applications' use : all other URI SWIs are reserved. URI_Version (&4E380) On Entry R0 = flags: bit meaning if set 0-31 reserved (0) On Exit 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. URI_Dispatch (&4E381) On Entry R0 = flags: bit meaning if set 0 inform caller of result (=>R2 valid) 1 check only, don't process (R0:0 must be set) 2 don't attempt external process startup 3-31 reserved (0) R1 = pointer to 0 terminated URI string R2 = source task handle (if bit R0:0 is set) On Exit R0 = flags: 0 => request accepted, all other values reserved R2 = task handle of URI handler R3 = handle of this URI (request identifier) 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 via a WIMP message ™ necessary since the dispatch of the URI occurs asynchronously. When requesting a check only (R0:1 set), it is an error not to set R0:0 and provide a valid task handle in R2. The URI will be copied to the URI handler's workspace, optionally transformed (future enhancements, such as canonicalisation, may be added), then relocatable modules will be offered the chance to handle the URI via service call &A7 ; if the service call is unclaimed, then a WIMP message will be broadcast (User_Message_Recorded), 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 (insofar 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. If requested, the originating task will be informed of the results of this process (via User_Message); if the URI has been processed, then the handle will cease to be valid. The handle also ceases to be valid at this point if notification has not been requested, irrespective of whether or not the URI has been processed. URI_RequestURI (&4E382) On Entry R0 = flags: bit meaning 0-31 reserved (0) R1 = pointer to buffer to hold URI or 0 to read required size R2 = length of buffer or unused (if R1 = 0) R3 = URI handle On Exit R2 = offset into buffer of terminating null, or size of buffer required (if R1 = 0 on entry) 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. In this case, the URI will not be deemed to have been processed. URI_InvalidateURI (&4E383) On Entry R0 = flags: bit meaning 0-31 reserved (0) R3 = URI handle On Exit 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. Reason 0 - URI handler started On Entry R0 = 0 reason code R1 = &A7 service call On Exit 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. Reason 1 - URI handler dying On Entry R0 = 1 reason code R1 = &A7 service call On Exit 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. Reason 2/3 - Request to check/process URI On Entry R0 = 2 or 3 (reason code) R1 = &A7 (service call) R2 = pointer to URI string (read-only access) R3 = handle of this URI On Exit 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 potential processing (R0=2), or processing (R0=3). 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 which can process URIs should inspect the string at the given address, and if they can process the given URI, they should claim the service call: this is all that's required if R0=2 on entry. If R0=3 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 should pass the call on with all registers preserved to allow the remainder of the dispatch mechanism to function. WIMP messages ------------- As might be expected, the URI handler communicates with other WIMP tasks via the WIMP message mechanism. The following message action codes are defined for use by external applications, with all other codes being reserved. Message &4E380 - URI handler started Poll block R1+20 = flags: bit meaning 0-31 reserved (0) 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 - it is issued for information only. Message &4E381 - URI handler dying Poll Block R1+20 = flags: bit meaning 0-31 reserved (0) 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 - it is issued for information only. Message &4E382 - Request to check/process URI Poll Block R1+20 = flags: bit meaning if set 0 check URI only, do not process 1-31 reserved (0) R1+24 = pointer to URI string (URI internal buffer) R1+28 = URI handle 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 given URI. If R0 bit 0 is clear, you should 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 after the call returns. If an application is able to process the given URI, then it should acknowledge the broadcast, thus preventing its being passed on to other applications, otherwise it must not acknowledge the message. Message &4E383 - URI return result Poll Block R1+20 = flags: bit meaning 0 0 => URI was claimed for processing 1 => URI was not claimed for processing 1-31 reserved (0) R1+24... undefined (reserved) Use This message is used by the URI handler to return result status information to a requesting task. Currently, only success or failure is indicated, though this is likely to be enhanced in a future version of the specification. Use of the URI filetype ----------------------- The use of the URI filetype is currently not defined by this specification, though the addition of this section is of high priority: it remains reserved, therefore, until a future issue of the specification. Suitable sprites will be provided at an appropriate time to represent the filetype; these will be the only sprite definitions acceptable for use in this context. Use of URI environment variables -------------------------------- The use of environment variables by the URI handler is currently undefined, though this will be defined in a future issue of the specification : all such environment variables remain reserved, therefore. Usage of the Acorn URI handler ------------------------------ This section will contain a discussion of the anticipated modes of usage of the Acorn URI handler module; it is intended to provide guidance for application's programmers who wish to make use of the services provided by the URI handler.