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

Goals and Guidelines

Top level goals are:

• Projects should only need to create HTML/CSS/JavaScript to have a fully functional graphics application.

Development Methods

Use whatever framework/tools are required to build a customized browser-based application.

On Windows:

• Use Visual Studio
• Use Active Template Library

Detailed System Design

CHTMLBrowserWnd

This component is responsible for creating the main frame window used for hosting the web browser control via CHTMLBrowserHost.

As part of the normal operations of the window, it should update the URL the web browser control is displaying as state changes are detected. It should also publish updated information to the JavaScript interface.

It supports whatever requirements are described for BOINC graphics applications.

Reference: Making graphics applications for BOINC

CHTMLBrowserHost

This component hosts the web browser control and exposes whatever interfaces/callbacks the control requires for logging and display purposes. As part of its creation process it creates/exposes the JavaScript interface for CHTMLBrowserWnd to use.

CHTMLBrowserHostUI

This component acts as the JavaScript interoperability component. It should only support single threaded access.

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.

NOTE: Any file specified in the configuration file and any related support files will need to have the <copy_file/> directive included in the versions.xml file describing the application version.

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: boinc_graphics_status.xml

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 && api_port) && (switch_to_url is empty))
        switch_to_url  = "http://localhost:" + api_port + "/";

Vboxwrapper WebAPI Port

Reference: vbox_webapi.xml

Vboxwrapper Remote Desktop Port

Reference: vbox_remote_desktop.xml

JavaScript Extension on Windows

Currently HTMLGfx can pass information to the HTML DOM via the 'window.external' extension.

Methods

Name	Returns	Description
log(string)	void	Logs a message to stderrgfx.txt
debug(string)	void	Logs a message with a category of 'DEBUG' to stderrgfx.txt
info(string)	void	Logs a message with a category of 'INFO' to stderrgfx.txt
warn(string)	void	Logs a message with a category of 'WARNING' to stderrgfx.txt
error(string)	void	Logs a message with a category of 'ERROR' to stderrgfx.txt
isStateUpdated()	Boolean	Returns true if it is time to refresh all the state in the UI
resetStateUpdate(Boolean)	void	Resets the state update flag to the given value

Properties

Name	Data Type	Description
appName	string
appVersion	long
wuName	string
resName	string
teamName	string
userName	string
userCreditTotal	float
userCreditAverage	float
hostCreditTotal	float
hostCreditAverage	float
scrsaveMode	Boolean	Was the graphics application launched in screensaver mode
suspended	Boolean	Whether the task is currently suspended
networkSuspended	Boolean	Should the UI suspend Internet activity
exiting	Boolean	Should the UI prepare to exit
exitTimeout	float
cpuTime	float
elapsedTime	float
fractionDone	float
vboxJob	Boolean	Is this task a vboxwrapper task?
rdpPort	long
apiPort	long

Examples

Example of refreshing the state of various controls:

    refresh() {
        if (window.external.IsAppInitDataUpdated()) {
            window.external.SetAppInitDataUpdate(false);
            username = window.external.UserName;
            teamname = window.external.TeamName;
        }
        fractiondone = window.external.FractionDone;
    }

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: default_win.htm

Precompiled Binaries

On Windows:

• x64: htmlgfx_26153_windows_x86_64.zip
• x86: htmlgfx_26153_windows_intelx86.zip