URL_GetURL (changes)

Showing changes from revision #10 to #11: Added | Removed | Changed

URL_Fetcher

» SWI Calls

» URL_GetData

URL_GetURL

(SWI &83E01)

Instigate data transfer from / to a resource server.

Interrupts

Interrupt state is undefined.

Re-entrancy

SWI is not re-entrant.

Use

This SWI is used to instigate a transfer of data to or from (mainly from) a resource server. When this SWI is called, the URL module checks the per-session and global proxy settings, looking for a match (see SWI URL_SetProxy for details on setting proxies and proxy conflict resolution). If no proxy is to be used, then URL looks for a protocol module which is capable of handling the URL specified by R3. If a proxy setting is found, then a pointer to the proxy URL is placed in R7, R0:31 is forced to value 1, and URL looks for a protocol module which is capable of handling the specified proxy URL. In both cases, if a suitable module cannot be located, the URL module generates an error. If a protocol module capable of handling the URL is found, then all client registers are passed onto the protocol module via the Protocol_GetData SWI call with the exceptions stated above for proxy handling. On exit, R0 holds the status code returned by the protocol module.

The extra data pointed to by R4 on entry is method and protocol specific. For example, in HTTP, the data comprises HTTP headers and, if appropriate, an entity body. Protocol modules should use this style wherever possible. Note that these headers do not include lines such as an HTTP Request-Line (ie. the “GET / HTTP/1.1” part. For example, when posting data to an HTTP URL as the result of a form submission on a web page, the web browser would supply a Content-Type header, Content-Length header, potentially some kind of encoding header, a blank line and then the entity body.

The User Agent string pointed to by R6 if R0:0 is set, is in indication to the underlying protocol module of how the module should identify itself to remote systems. This controls the User-Agent header for the HTTP protocol module, for example. The protocol module is free to define its default identifier as it pleases, however, following the format of the HTTP User-Agent is recommended where possible and appropriate to the protocol. Modules may choose to ignore or amend any User-Agent string. For example, the AcornHTTP module will suffix the client’s User-Agent with its own version number, resulting in complete identifiers such as:

where the client only specified “Acorn Browse/2.06”.

The AcornHTTP module provides a mechanism for the temporary registration of additional methods for use with HTTP or HTTPS. See HTTP_RegisterMethod.

Applications for new permanent method codes should be made to ROOL Allocations. The range 128-254 is reserved for private non-distributed modules. Method numbers 0 and 255 are reserved and must not be used.

Notes

The outgoing request may be augmented by the underlying protocol module. For example, AcornHTTP maintains a global cookie store and will transmit to the server any relevant cookies automatically, unless R0 bit 30 is set.