The updaters module will retrieve documents from a location specified by a URL provided by the application. After download, the file can then be processed and actions taken based on the data. Multiple downloads can be organized using AutoFetch_Manager, which can also be customized.
Currently the only format directly supported is on based on XML. When received, the document's digital signature will be (optionally) verified, and the file parsed as an XMLFragement. The parsing is then handed over to the implementation.
API documentation generated by Doxygen contains all necessary information for the external APIs.
The module currently have 3 classes:
Organizes the fundamental API and the application specific finished message posting. It does not handle any URLs directly
Usage:
Specify the message to be posted (Will be posted with Id() of the element as par1 when PostFinished is called, par 2 is a application specific result code).
Application specific function to start the operation. Return OpStatus::OK if operations has started, but not finished; OpRecStatus::FINISHED if the operation completely finished, and an error status if there was an error.
Called by implementation when finished with the result code to be posted back to the caller. After this call IsFinished() will return TRUE
Return TRUE if the operation is finished. Can be used to poll elements
Can organize multiple fetch elements and send an application specific message when all are finished. Which message(s) to listen for from the elements have to be configured by the application; the class assumes any message with an ID in the list is a finished message
Usage:
The constructor is initialized with the Message code posted by the manager when all currently loading updaters are finished (the message have no parameters).The owner/application MUST register the callbacks for the messages to listen for.
Downloads a URL and then passes it on to the application specific processing.
Usage:
The object is initialized with the URL of the resource to be loaded and the message to post when finished
Application specific function that processes the file called if the loading is successful. The loaded url is passed as an argument
Downloads a URL and processes the file as an XML document, and can verify digital signatures that follows a specific prefix. Once the XML is parsed the processing is handed over to the implementations.
Usage:
The object is initialized with the URL of the XML document to be loaded and the message to post when finished
Application specific function that processes the file. The "parser" member is initialized when this functionis called and can be used to process the XML document.
Helper functions
Application specific function that verifies the signature on the file.
The default implementation is configured using this API (applications overrding the default should not use this):
This function specifies whether or not the loading document should be verifies, and if so, which public key and algorithm to use. The default is to use the rootstore module's public key and SHA-256.
By default the verification function uses (cstring-style)"<?xml version=\"1.0\" encoding=\"utf-8\" ?>\n<!--" as a prefix before the signature followed by a CRLF and the signed content (which must include the comment end tag).
API documentation generated by Doxygen contains information about the internal organization of the module.
The module is fairly small, about 5KB. It implements basic functionality imported by other modules as a foundation for their functionality, while most of the actual functionality is implemented in, and imported, from other modules, primarily url, xml, and libcrypto.
In OOM situations the current operation is aborted and a failure notice is given to the action's owner, either by message or OpStatus return value. Very few functions LEAVE.
An OOM condition is raised when detected in the module itself
Currently OOM is handled locally by aborting the operation. In some operations, when it is possible, the caller is informed of the status
Much of the module is message callback based, and these functions are not able to report OOM situations directly to the documents or UI. In these cases the current operation will be terminated, and errormessages sent.
There is no static heap memory use. A number of operations, like processing the XML file (read and parse) will keep the entire document in memory for the duration of the operation. For large XML documents that MAY lead to OOM situation, and applications that may encounter such large files should use handlers that are designed for such sizes.
Minimal. Most operations are done in heap allocated memory.
None
Caching is managed by URLs. Memory is only used during actual operations and released immediately after use.
Controlled by applications. Classes clean up their own memory use.
None.
Not possible, except as already available thorugh URL and possibly XML
Selftests using libssl's automatic rootstore update and EV ability, and the pubsuffix module's tests.
Selftests
Classes are tailored for specific operations, AutoFetch_Element to provide the basic API, AutoFetch_Manager to manage multiple loads, XML_Updater to handle digitally signed XML documents. Specific implementations in subclasses are needed to actually do something.
Should the URL handling in XML Updater be moved down into the FetchElement? Or does the current arrangement make better sense? Alternatively, should XML updater be broken into two separate classes