Instigate data transfer from / to a resource server.
Entry | |||
---|---|---|---|
R0 | Flags: | ||
Bit 0 => | R6 is valid | ||
Bit 1 => | R5 holds length of data in R4 specified buffer, otherwise a single NUL terminated string in buffer | ||
Bits 29..2 | reserved (0) | ||
Bit 30 => | Prevent AcornHTTP fetcher from adding cookies to the request. | ||
Bits 31 | reserved (0) | ||
R1 | Session identifier | ||
R2 | Bits 7..0 => | Method | |
Bits 15..8 | Method dependent | ||
Bits 31..16 | Reserved (0) | ||
R3 | URL – The resource that we are requesting including the protocol, e.g. “http://www.bbc.co.uk” |
||
R4 | Data block: Data to send in addition to the URL. Validity is protocol and method dependent. |
||
R5 | If R0:1 is set, length of data in block pointed to by R4. If R0:0 is clear, then 0=return body only, 1=return header only, 2=return both. |
||
R6 | User Agent: Pointer to string to use as “User Agent” identifier in request header if R0:0 is set. A NULL pointer or NULL string implies use default identifier – see below. |
Exit | ||
---|---|---|
R0 | Protocol status (as defined for URL_Status) | |
All other registers preserved |
Interrupt state is undefined.
SWI is not re-entrant.
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:
User-Agent: Acorn Browse/2.06 AcornHTTP/0.82where the client only specified “Acorn Browse/2.06”.
Table of method numbers | |||
FTP | HTTP and others | Comment | |
---|---|---|---|
1 | RETR/LIST | GET | “Get this object” operation |
2 | n/a | HEAD | “Get entity headers” operation |
3 | n/a | OPTIONS | “Get server options” operation |
4 | n/a | POST | “HTTP POST” operation |
5 | n/a | TRACE | “HTTP TRACE” operation |
6 | n/a | n/a | Reserved – do not use |
7 | n/a | n/a | Reserved – do not use |
8 | STOR | PUT | “Store this object” operation |
9 | MKD | n/a | “Create directory” operation |
10 | RMD | n/a | “Remove directory” operation |
11 | RNFR/RNTO | n/a | “Rename object” operation |
12 | DELE | DELETE | “Delete object” operation |
13 | STOU | n/a | “Store object unique” operation |
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.
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.