TOC?

Introduction

HTML and JavaScript have become the predominate rendering technologies on the web. Used for everything from web browsing to mobile phone applications. HTMLGfx attempts to bring HTML rendering technologies into the BOINC graphics and screensaver environment.

By providing precompiled binaries the barrier to entry is greatly reduced allowing projects to deploy customized graphics for their applications. All projects would need to supply is the HTML/CSS/JavaScript required to display something about what is going on with the currently executing job.

In theory, volunteers could even get in on the act and create graphics for whatever applications suit their interests and share them with the community. It is conceivable that projects may even hold yearly competitions to include a volunteers graphics bundle to be deployed with the project's application.

NOTE: HTMLGfx is only supported on Windows at this time.

References: Making graphics applications for BOINC

System Overview

HTMLGfx leverages existing operating system dependent libraries for rendering HTML. By leveraging the operating systems HTML renderer HTMLGfx will be able to support whatever the latest technologies the operating systems browser supports.

Design Considerations

General Constraints

Known security related issues:

• ​Same Origin Policy
• ​HTTP Access Control (CORS)

Known browser utilization issues (on Windows):

• ​Internet Explorer Browser Feature Emulation
  NOTE: Unless the registry is set-up, your application will act as Internet Explorer 7.0

Differences when compared to current wxWidgets wxWebView implementation (on Windows):

• Prevent new browser windows from being spawned by javascript.
  NOTE: Implements ​DWebBrowserEvents2
• Prevent JavaScript errors from displaying in a dialog.
  NOTE: Implements ​IOleCommandTarget
• Prevent ShowHelp/ShowMessage UI elements from being displayed.
  NOTE: Implements ​IDocHostShowUI
• Writes all HTML/JavaScript errors to standard log file.
  NOTE: Implements ​IDeveloperConsoleMessageReceiver

Goals and Guidelines

Top level goals are:

• Projects should only need to create HTML/CSS/JavaScript to have a fully functional graphics application.
• Projects should be able to use their favorite browser to debug their graphics application.

Detailed System Design

HTML Window

This component is responsible for creating the main frame window used for hosting the web browser control as well as creating the web browser control itself.

As part of the normal operations of the window, it should update which URL the web browser control is displaying as state changes are detected.

It supports whatever requirements are described for BOINC graphics applications.

Reference: Making graphics applications for BOINC

HTTP Server

This component serves up content from the slot directory running the application. It should only be bound to the loopback adapter and should not provide a default document nor a directory listing when queried. It should only serve up files that are contained within the slot directory structure.

HTTP Server RPCs

Embedded Static Content

The following files are embedded within the executable:

Namespace	Contents
/api/static/index.html	index.html
/api/static/boinc.png	boinc.png
/api/static/boinc.js	boinc.js

Retrieve init_data.xml

Returns the contents of the init_data.xml file.

Namespace:	/api/getInitData
Parameters:	None
Returns:	XmlDocument?

Retrieve graphics_status.xml

Returns the contents of the graphics_status.xml file and in addition the Vboxwrapper WebAPI and Remote Desktop port information.

Namespace:	/api/getGraphicsStatus
Parameters:	None
Returns:	XmlDocument?

Reset reread_init_data_file flag

Resets the internal flag notifying the HTML application it needs to read the init_data.xml file. This flag is published as part of the /api/getGraphicsStatus API.

Namespace:	/api/resetReadFlag
Parameters:	None
Returns:	XmlDocument?

Calling RPCs

Here is some prototype code for calling the described RPCs:

function createRequest {
    var xmlHttp = null;
    var XMLHttpFactories = [
        function () { return new XMLHttpRequest() },
        function () { return new ActiveXObject('Msxml2.XMLHTTP') },
        function () { return new ActiveXObject('Msxml3.XMLHTTP') },
        function () { return new ActiveXObject('Microsoft.XMLHTTP') }
    ];

    for (var i = 0; i < XMLHttpFactories.length; i++) {
        try {
            xmlHttp = XMLHttpFactories[i]();
        } catch (e) {
            continue;
        }
        break;
    }
    return xmlHttp;
}

function sendRequest(url) {
    var req = createRequest();
    var response = null;
    req.open('GET', url, false);
    req.send();
    response = req.responseXML;
    req = null;
    return response;
}

var xmlDocument = sendRequest('/api/getInitData');

State URL Selection Process

URL selection works by the following process:

    switch_to_url = default_url

    if ((status.abort_request or status.quit_request or status.no_heartbeat) and (exiting_url not empty))
        switch_to_url = exiting_url
    else if (status.suspended and (suspended_url not empty))
        switch_to_url = suspended_url
    else if (status.network_suspended and (network_suspended_url not empty))
        switch_to_url = network_suspended_url
    else if (running_url not empty)
        switch_to_url = running_url

    if ((is_vbox_job && webapi_port) && (switch_to_url is empty))
        switch_to_url  = "http://localhost:" + webapi_port + "/";

    if (switch_to_url is empty)
        switch_to_url  = "http://localhost:" + webserver_port + "/api/static/index.html";

Configuration File

The graphics description file has the logical name of boinc_graphics.xml (its physical name should include a version number and other info). It has following structure:

<boinc_graphics>
    [ <default_url>filename</default_url> ]
    [ <running_url>filename</running_url> ]
    [ <suspended_url>filename</suspended_url> ]
    [ <network_suspended_url>filename</network_suspended_url> ]
    [ <exiting_url>filename</exiting_url> ]
</boinc_graphics>

Optional elements:

default_url

document to display if no state specific URL is defined.

running_url

document to display while the task is running.

suspended_url

document to display while the task is suspended.

network_suspended_url

document to display while the network is suspended.

exiting_url

document to display before the task exits in 5 seconds or less.

Graphics Status File

It is read once a second and is generally managed via the worker applications via the boinc_write_graphics_status() BOINC API.

Reference: graphics_status.xml

Vboxwrapper WebAPI Port

Reference: vbox_webapi.xml

Vboxwrapper Remote Desktop Port

Reference: vbox_remote_desktop.xml

Example HTML Page

Here is a link to a working HTML page that is embedded within the HTMLGfx app in case the boinc_graphics.xml file is missing.

Reference: HTML Source Files

Debugging HTML Web Applications

Debugging potential graphics applications should be as simple as copying init_data.xml, boinc_graphics.xml, graphics_status.xml, and whatever application support files you'll need into a temporary directory and launching HTMLGfx with the '--debug' command line parameter.

All the files should appear in the same directory layout as they would be in when running under BOINC.

Using the port number described in the window title launch your desired browser and use a URL like this:

http://localhost:<port Number>/<desired HTML page>

Your browser should be able to download the HTML file and related support files. You should then be able to use your browsers built-in developer tools to figure out what went wrong.