<Component_Name>
Scope of the document
This is the high-level architecture description of the MicroB Browser Application for the ITOS2008 "product" based on the Maemo Platform.
Intended audience
This document is for anyone interested in the MicroB Browser. Readers need to have some knowledge of software design techniques.
It is expected that no one will read this document.
Overview of the Browser subsystem
Usability studies have shown that browsing is one of the most popular and most important use cases for this device line. Therefore, the platform needs to provide a good browsing experience for the end user.
The Browser will be a HTML/XHTML User-Agent, supporting the standard common Web content types with functionally equivalent to a desktop browser as of the time of this document's original authoring. When necessary it will provide a means to adapt Web content for the medium screen size of the platform.
It will have internationalization & localization support both for the Browser UI and for the input methods.
Browser_SWR and Browser_UI contain a full listing of the Browser requirements.
The Browser Subsystem (collectively referenced as Browser) includes the Web browser application, the Web browser engine, Bookmark Manager and extra software modules, including optional plug-ins.
The browser.garage.maemo.org team is responsible for the overall design and implementation of the Browser.
Notation
This document contains package and class diagrams using Unified Modeling Language (UML) notation to showing the dependencies between logical entities. This document also contains UML sequence diagrams to illustrate the behavior of the application. Other diagrams detailing component design of the browser do not use UML.
Table 1: UML Notation Symbols
<Component_Name>
<Package_Name>
<Interface_Name>
<ClassName>, which implements interface (API) <InterfaceName>. One class can implement more than one interface.
Package A depends on the Package B
Packages can have sub packages.
This chapter briefly presents the major dependencies, the public interfaces and the clients of the Browser subsystem. Subsequent chapters describe the internal structure of the Browser.
Software Context
{Note: this picture is old, the source for it is lost, and "Theeming" is misspelled. Application Framework should read "Desktop"}
Table 2: High-level system overview: Components
The hardware environment of ITOS2008 is beyond the scope of this document.
The architecture for this project assumes the existence of the following general items; however, the technical nature and details are irrelevant:
Top-level view to the Browser Subsystem
Browser Engine
Browser uses the Gecko browser engine developed by mozilla.org.
Gecko runs on multiple hardware and software platforms by design. As a result, it contains a couple of platform dependent modules: NSPR (NetScape Portability Runtime), XPTCall (Cross Platform Typelib Call and dispatch), a widget module (based on GTK2) and Cairo (a graphics engine). People may choose to embed Gecko on various systems; for UNIX platforms, the common embedding system is GtkMozEmbed (a Gtk style object).
Browser Engine Core
Gecko contains the Web browser functionality and is the largest part of the MicroB Engine. Gecko includes:
Portability Layers
A number of components abstract and insulate Gecko from various hardware and software platform details. A distinct group of Mozilla developers maintains NSPR, which provides consistent APIs and behaviors for network I/O, timers, threads, and file handling. Mozilla developers maintain XPTCall, which abstracts function dispatch. A third party maintains Cairo, which abstracts graphics routines.
Embedding component
One embedding method available for Gecko consumers on UNIX platforms is GtkMozEmbed1, which embeds all Engine Core functionality into the Engine Widget, which is instantiated and called by the Browser Application. Browser Engine Components
Gecko_Arch contains a detailed description of the Gecko engine architecture. DevMo contains a detailed description of the Gecko engine functionality.
Document Browser_FTV explains techniques employed to improve usability while rendering on medium and small screens using Gecko.
Gecko Engine Components detailed
EAL design is out of the scope of this document. See Browser_EAL for more details.
Browser Application
Browser Application provides the UI to the Browser Engine. Additionally it provides services to other ITOS2008 applications and subsystems.
It does the following:
In addition to functionality listed above, Browser Application also provides a browser application services to other applications by implementing 'osso-browser-interface' API.
Browser_API and Browser_EAL contain (generally outdated) snapshots of the full API specification (in Doxygen format). The most up-to-date version can be generated from the Browser project svn repository <link:https://garage.maemo.org/svn/browser/browser-ui/trunk/browser-eal/> (anonymous read-only access is allowed).
The Engine Widget does the actual content rendering.
Refer to the document Browser_UI for complete Browser Application UI design specification.
Bookmark Manager
Bookmark Manager (BM) consists of the following components:
Bookmark Manager Engine
BM Engine is responsible for managing bookmark database and provides API to create/store, retrieve, delete, rename, copy, move, and export bookmarks and bookmark folders and also to import bookmark trees in HTML format.
BM Engine API can be generated by Doxygen utility from the Browser SVN repository.
Bookmarks are stored in XBEL format XBEL but can be imported from/exported to other browsers in HTML format, which provides interoperability with all major desktop browsers.
BM Engine is a shared library.
Bookmark Manager UI
Bookmark Manager UI is a front-end for the Bookmark Manager Engine. It is a stand-alone application, which dynamically links to the BM Engine shared library. BM UI is based on widgets provided by the Desktop.
The Browser_UI document details BM functionality.
Browser Plug-ins
Gecko implements the Netscape plug-in API and, therefore, can use any plug-in implementing this standard API available for the platform on which the engine runs.
Netscape Plug-in API specifies windowed and windowless plug-ins.
Gecko's implementation of the Netscape Plug-in API supports windowed plug-ins, but the window passed to the plug-in from Gecko is embedded into an XEmbed instead of a Motif window.
Some browsers and plug-ins have support for windowless plug-ins, but not Gecko on UNIX like operating systems.
Macromedia Flash plug-in (provided by the Multimedia project in cooperation with Adobe) is used by the Browser to render Flash content.
The Browser Team provides a Default Plug-in that handles audio and video content (the Multimedia project should be responsible for maintaining it).
Someone could add a Java plug-in as the source is available.
Refer to the document NPAPI for the Netscape plug-in API specification.
Browser activation and control
Application Framework can send D-BUS messages to launch the Browser, instruct it to load a specified URL, reduce its memory consumption, or quit.
The Browser API document Browser_API and Application Framework Design and API document Desktop_Design contain the corresponding APIs.
Providing Browser services to other applications
The Browser provides services to the other applications via D-BUS, including opening a new browser window and loading a URL into an existed browser window.
Browser_API contains the complete API description and specification for D-BUS messages.
Requesting services from other applications
Browser Application requires some services from Email, Media Player and Help.
Requesting services from the Email Application
Browser uses Email application D-BUS API Email_API for "send URL via email", for "send file via email" and to add mailto: URLs to the contacts list.
Requesting services from the Media Player Application
Browser uses Media Player to:
Browser interacts with Media Player via D-BUS API, provided by Media Player MP_API.
Requesting services from the Image Viewer Application
If the Browser does not support an image format and the user tries to load it directly, the open / save dialog Display images from the Web page, open would trigger the Image Viewer....
Requesting services from the Help Application
Browser and Bookmark Manager can activate Help application from the main application menu or from the context sensitive menu via D-BUS API provided by the Help application. Since the help content is not context sensitive, there is only a single API call for Help activation. See HELP_Arc for the additional info*
Plug-in for Task Navigator
Task Navigator, among other items, will display the list of Browser bookmarks. The list will interactive; the user will be able to view the content associated with a bookmark by activating the corresponding bookmark item in the Task Navigator's list.
The Task navigator Bookmark plug-in (TN BM plug-in) provides the "interactive bookmark list in the Task navigator" functionality. Application Framework delivered initial plug-in implementation (including UI elements). Browser project has implemented the business logic for the plug-in.
TN BM plug-in uses the same bookmark file as Bookmark Manager to build its TN menu. When users selects a bookmark, the TN BM plug-in launches the browser (if it is not active already) or brings the browser window to the foreground (if browser was active in the background) and instructs it to load the bookmark URL into the active browser window.
See TN_Plug-in for more details about TN BM plug-in API.
Plug-in for Global Search
Because Global Search GS_Design requires plug-ins developed by each application project to provide content search support, the Browser Team provides a plug-in for searching bookmark content.
Plug-in behavioral overview
Illustrates browser and plug-in collaboration. It depicts three main stages of browser-plug-in interaction:
MIME type handling
When the user asks the Browser Engine to load a file that it cannot handle internally, it will show the user a dialog (as defined in the Browser UI specification). The Default Plug-in is used when a web page specifies <embed> or <object> and the content is not handled by any other registered with the browser (that's why it's called the default plug-in...). The Default Plug-in generally renders a clickable box with an icon hint indicating whether the content is audio or video. If the user triggers the Default Plug-in instance (e.g., by tapping or by tapping and holding) then it will call functions in the Browser UI. The Browser UI calls osso_mime_handler (which presumably internally checks with GConf) to see if there is a registered MIME handler for the specified content. MIME handlers are external applications; if the UI finds a handler then it invokes it and feeds the content to it. Otherwise, the default plug-in replaces the object with a placeholder that would allow the user to save it.
Unrecognized protocol handling
This is some strange description of what probably happens for unrecognized protocols, and has absolutely nothing to do with MIME Handlers. We have no idea what a Recognizer is and are ignoring it.
Platform robustness
Components of the Browser UI Subsystem developed in-house follow Linux/Debian and OSSO internal coding conventions and try to use standard interfaces and libraries where possible.
The preceding paragraph is a joke; the editor could not afford to simply remove it.
D-BUS
The Browser UI Subsystem uses the D-BUS message bus to provide a messaging service to other subsystems in the Maemo platform. Features of D-BUS are beyond the scope of this document.
Test and Service
Theoretically, a Device State Management system (DSM) specification might list requirements that would affect the Browser Subsystem. Such as how software running on the ITOS 2008 platform should behave under special circumstances, such as when the system is in offline mode. The ITOS 2008 platform has a number of modes only two of which would seem relevant to a typical user-land application, namely "Normal Mode" and "Offline Mode". Obviously, Offline mode imposes certain restrictions on the Browser Subsystem, however they're generally the subject of User Interface specifications or other Subsystems and as such are not described in this document.
There are additional requirements from the Desktop regarding state saving and application control. Desktop might request an application lower its memory usage, save its state, to be ready for shutdown, or to quit immediately without any state saving. Browser and Bookmark Manager will try to address all requirements from Desktop and DSM. However, Browser does not support saving state.
Event logging
Applications for ITOS 2008 should use Linux syslog for logging. Someone might claim that this system is flexible, but that claim is beyond the scope of this document. Gecko supports NSPR logging which is controllable via NSPR_LOG_MODULES and NSPR_LOG_FILE, see NSPR documentation for information about the syntax for these environment variables, and see mozilla.org documentation for information about specific NSPR logging modules.
According to the Code Conventions document, every software component logging an event should provide its name and version number as a part of the message. Browser software will try to honor this requirement.
Debian packages, delivered by the Browser project
Shows a general overview of packages for the Browser Subsystem, it was never accurate as there are a dozens of packages between osso-browser-ui and the engine microb-engine. It is unknown as to which tool generated this chart. Anyone needing to understand the relations between binary or source packages can use a cross reference to examine the browser debian/control files or use apt-cache rdepends.
The Browser_Comp document contains detailed information about Browser Subsystem software components and their dependencies.
Packages delivered by other projects for the Browser
The Browser UI skin and Bookmark Manager UI skins are contained in the general skin package osso-icons-default, provided by Desktop. For Gecko, graphics will come from the same general skin package; however, the skin designers will need to make additional graphics to satisfy requirements of the Gecko engine.
Package Dependencies Graphs
The following graphics are out of date. Drawing the hundred or so boxes that would be required will be a big waste of time with no possible benefit.
Simplified High-Level Dependencies Graph
Simplified Browser UI Dependencies Graph
Simplified Bookmark Manager Dependencies Graph
Simplified Task Navigator Bookmark Plug-in Dependencies Graph
Simplified Bookmark Search Plug-in Dependencies Graph
Development responsibilities
Browser Subsystem development responsibilities
Linux, zlib, libpng, libjpeg, and Gtk are Core software packages.
Different Nokia teams develop each of:
Browser Project team is responsible for ...
Browser Project team is responsible for the module testing and smoketesting the packages it produces.
According to the Browser test Plan (Browser_Test document), comprehensive Browser Subsystem testing is delegated to another party.
Responsibilities for testing the ITOS platform are beyond the scope of this document, presumably when ITOS includes the Browser subsystem then they responsible party must test the Browser subsystem too.
The following portions of bugs.maemo.org pertain to the Browser subsystem (note: the terminology in this document uses the standard Bugzilla terminology):
See Browser_Comp for more detailed information about Browser components and their licenses.