Safeguarding the past, present and future of RISC OS for everyone

AcornHTTP

Programmer's Reference Manuals

» List of modules

» AcornHTTP

The AcornHTTP module is the protocol module for handling HTTP requests which sits behind the URL_Fetcher module. It also provides handling for HTTPS requests, relying on AcornSSL for the encryption.

The module also provides facilities for managing cookies in a global cookie store. The presence of SetCookie in the response header is indicated by setting bit 16 of R0 on return from URL_ReadData. Clients can then work through the incoming cookie queue using HTTP_EnumerateCookies and choose whether to add each one to the global store in memory or to discard by using HTTP_ConsumeCookie. Cookies can also be added directly to the global store using HTTP_AddCookie. Once a cookie has been added to the store, it will remain until it expires, and the appropriate Cookie headers will be added to any request made through URL_GetURL automatically. Incoming cookies which have been queued but which have not been added to the store are not included in outgoing requests.

An environment variable, Browse$AcceptAllCookies, can be set to cause all incoming cookies to be added to the store. If the value is “off” or the variable is unset, then the cookies are queued for evaluation.

On initialisation the module will read any saved cookies from <Choices$Write>.WWW.AcornHTTP.Cookies if it exists, or the file named in Browse$CookieFile as a fallback. The module writes persistent cookies to <Choices$Write>.WWW.AcornHTTP.Cookies whenever an individual cookie is accepted into the store through HTTP_ConsumeCookie or whenever cookies are read on an incoming response if Browse$AcceptAllCookies is set. The cookie file is also written on calls to HTTP_AddCookie, but as that call cannot currently create persistent cookies the file will only change if a cookie is caused to be removed from the store, by reaching its expiry point or being replaced by the newly-added cookie.

The format of the written cookie file is one of two formats, both also compatible with Fresco, an early RISC OS web browser. If Browse$CookieFileFormat is set to 1, the format used is similar to the Set-Cookie response header. Normally the module defaults to format version 2, a tab-separated value file, despite the history file describing this as having “no apparent logic”.