QNX Technical Articles

Date of this edition: September 16, 2008

Target OS: QNX^® Neutrino^® 6.3.0 or later

Host OS: Microsoft Windows XP SP1 or SP2, 2000 SP4, NT SP6a; Sun Solaris 7, 8, or 9; QNX^® Neutrino^® 6.3.0 or later; Linux Red Hat 8, 9, or Enterprise WS 3 or 4

---

For information on installing this TDK, see the installation note. For the most up-to-date version of these release notes, log into your myQNX account, and then go to the Download Center area of www.qnx.com.

---

Contents

• What's in this TDK?
  • Binary component
  • Source component
• Known issues
• Documentation
• Technical support

---

Throughout this document, you may see reference numbers associated with particular issues, changes, etc. When corresponding with our Technical Support staff about a given issue, please quote the relevant reference number. You might also find the reference numbers useful for tracking issues as they become fixed.

---

What's in this TDK?

The Web Browser TDK lets you customize the Voyager embedded browser's user interface for use with the Voyager HTML 3.2 user agent or the Voyager 2 HTML 4 user agent with ACCESS NetFront technology. This TDK contains a binary component and a source component.

Binary component

The binary part contains the NetFront webserver for all the target processors (x86, ARMLE, MIPSLE, PPCBE, and SHLE). It's intended to be run on a target system with QNX Neutrino 6.3.0. The location of the binary files is:

• $QNX_TARGET/armle/usr/photon/bin/netfront
• $QNX_TARGET/mipsle/usr/photon/bin/netfront
• $QNX_TARGET/ppcbe/usr/photon/bin/netfront
• $QNX_TARGET/shle/usr/photon/bin/netfront
• $QNX_TARGET/x86/usr/photon/bin/netfront

After installing the NetFront binary on your target system, you need to add it to a webserver profile, usually to the online profile:

1. Edit the global file, /etc/photon/webservers, or the user file, $HOME/.ph/webservers (if you have one).
2. Search for the online line and change it to this:

   online = netfront,NetfrontServer
     

   In this line, netfront is the name of the binary (the PATH environment variable must contain its directory) and NetfrontServer is the connection name used to connect to the server.

For more information about webserver profiles, see the documentation for the PtWebClient in the Photon Widget Reference.

Source component

The source component is a source archive (zip file) that contains the source code for the PtWeb library, the Voyager browser, the Voyager compact browser (voyager_compact), and a custom embedded browser (wp-web).

After you've installed the source, you can find the associated archive in $QNX_TARGET/usr/src/archives/qnx/tdk-browser-src.zip.

If you have QNX Momentics PE, you can compile the source using the IDE or the command-line tools; if you have SE, you have to use the command-line tools.

The PtWeb library is the link between a browser client (e.g. the Voyager client or wp-web) and the browser server (e.g. netfront). Both the client and the server require this library.

The Voyager client, voyager_compact, and wp-web are PhAB applications, so you can load them into the Photon Application Builder and customize the user interface of the clients. All the clients use the PtWebClient widget's resources and callbacks to interact with the webserver. For more information, see the Photon Widget Reference.

Compiling with the IDE

1. Start the IDE.
2. Select File-->Import and select QNX Source Package.
3. Select the tdk-browser-src.zip source package, then follow the instructions on the screen.

After importing the source package, you can build the projects that it contains.

Compiling with the command-line tools

Here's how to compile the source from the command line:

1. Decompress the archive:
   • On Windows, use Winzip.
   • On Linux, Solaris, and QNX Neutrino, type:

     unzip -d dirname $QNX_TARGET/usr/src/archives/qnx/tdk-browser-src.zip
         

     where dirname is the directory where you'd like to put the source files.

2. On Windows, start a cmd shell in which to run the commands below.
3. Go to the directory where you saved the source:

   cd dirname
     

4. Type make to build the software. You'll find the results of the build in the dirname/install directory.

Known issues

• In Microsoft Windows, certain programs (e.g. Norton Ghost) add directories inside double quotation marks (e.g. ...;"c:\Program Files\Norton Ghost\";...) to your PATH environment variable. This causes the Cygwin spawn() function to fail, which in turn causes cp to fail when called by ln-w. (Ref# 20046)

  Workaround: Modify your PATH environment variable and remove any quotation marks.

• If you use a bash shell on Windows, compiling this TDK from the command line fails with the following error:

  /cygdrive/c/QNX630/host/win32/x86/usr/bin/ntoarm-ld: cannot find -lqnx
    

  (Ref# 22509)

  Workaround: Do one of the following:

  • Use a cmd shell instead of bash.

    Or:

  • If you wish to use the bash shell, unset the OSTYPE enviroment variable.
• When you compile the source for voyager_compact, you'll see many benign warnings about unused variables and so on. (Ref# 21328)
• On Linux, Solaris, and Windows platforms, the IDE reports warnings as errors in the Tasks view, but successfully creates the binaries. (Ref# 21285, 22511)

  Workaround: Ignore any error messages in the Tasks view that begin with warni followed immediately by a path.

• There are two files in the src/apps/web_sdk/voyager_compact/src directory with the same name, except for the case (Usemsg and usemsg). When you unzip the archive in Windows, you'll be asked if you wish to replace Usemsg. (Ref# 22554)

  Workaround: Replace the file; usemsg contains the correct usage message.

Be sure to check the QNX Momentics release notes for related issues.

Documentation

The functionality provided by this TDK is already described within the QNX Momentics documentation set, with some additional information provided below. For information on web browsers, see:

• netfront, voyager, and vserver entries below
• PtWebClient in the Photon Widget Reference.

  There is a new option for Pt_ARG_WEB_OPTION, "fDisableSelection" with possible values "TRUE" and "FALSE" (the default). When "TRUE", a user can't select HTML text in the netfront canvas.

netfront — Netfront web server

---

This utility is available only in the Web Browser Technology Development Kit (TDK).

---

Syntax:

netfront [-n servername] [-c configdir]

Runs on:

Neutrino

Options:

-n servername

Start netfront server with servername as the registered connector name. Use Pt_ARG_CLIENT_NAME to connect a PtWebClient to a netfront server with servername, or the -P option in voyager. The default value is NetfrontServer.

-c configdir

The directory for netfront to store internal configuration files. The default value is $HOME/.ph/netfront.

Description:

The netfront command starts the NetFront 3.1 server.

---

You must be running Photon to use netfront.

---

NetFront is a fully-featured rendering engine. It is optimized for embedded devices with a small foot-print, despite its many features and standards compliance.

Standards

NetFront v3.1 supports several Internet and wireless standards, including:

• HTML 4.01 and cHTML (iHTML)
• XHTML 1.1 (including XHTML Mobile Profile)
• CSS 1 (including CSS Mobile Profile) and CSS 2 (partial)
• HTTP 1.1
• SSL v3.0/TLS 1.0 (with 128-bit encryption)
• Dynamic HTML
• JavaScript 1.5 (ECMAScript)
• DOM 1 and DOM 2 (partial)
• WAP 2.0
• OMA DRM 1.0
• WAP Push
• WML 1.3

Features:

Smart-Fit Rendering

Smart-Fit Rendering renders a large web page for small-screen devices by reformatting the page in order to eliminate the horizontal scrollbar. You can switch between normal and Smart-Fit rendering dynamically.

Direct Connect

Direct Connect™ allows NetFront v3.1 to access and control hardware using JavaScript. This is an alternate to Live Connect, used in Microsoft's Pocket Internet Explorer. Using this technology, there is no need for a Java VM, making it ideally suited for small memory embedded devices. Security functions are also available to prevent unauthorized access.

Security

NetFront v3.1 includes support for Public Key Cryptography Standards (PKCS) 7, 10, 11, and 12. This means a browser can use client certificates for enterprise-grade security and access control.

Other technologies supported

Netfront 3.1 supports the MARQUEE tag, an extension introduced by Internet Explorer that allows you to display HTML content in a scrolling region on the page.

Netfront allows you to specify a magnifying factor that applies to the whole page (images, text, tables, controls, and so on). You can set the magnifying factor to <100% for a better fit on small screens, or you can set the magnifying factor to >100% to get a zoom effect. Independent of this, there is a text-magnifying factor that applies only to text.

Highly customizable

You can customize the Netfront 3.1 server through the Pt_ARG_WEB_OPTION resource of the PtWebClient widget. You can enable or disable most features at runtime, without restarting the browser.

For example, you can dynamically turn these features on or off:

Options related to CSS:

• Default style sheet is invalid.
• External file definition (LINK REL) style sheet is invalid.
• Import (@import) style sheet is invalid.
• <style> tag is invalid.
• style attribute is invalid.

Options related to SSL:

• Use SSL v2
• Use SSl v3
• Use TLS v1

Options related to JavaScript:

• Disable JavaScript altogether
• Validate/invalidate the external script file.
• Invalidate src attribute of <script> element. The external script isn't read.
• Invalidate a script in a newly generated window.

For more information on these options, see the NetFront-specific options section of PtWebClient.

Customizing controls

Netfront has the ability to change the look of its form controls. By default it uses the standard controls, but if the configuration file /usr/photon/config/netfront/controls.wgtp is present, it uses the controls in that file.

The Browser TDK package contains two picture module templates for this configuration file, installed in the /usr/photon/config/netfront: controls1.wgtp and controls2.wgtp.

You can copy either file to /usr/photon/config/netfront/controls.wgtp to use them as-is, or open them in PhAB to alter them.

To customize a template:

1. Open PhAB
2. Create a new application
3. Import one of the template picture modules
4. Customize the look of the controls
5. Save the application and copy the picture module from the application directory to /usr/photon/config/netfront/controls.wgtp.

The picture module templates contain the following widgets:

textarea

Multiline text controls

text

One line text controls

button, submit, and reset

Button controls

checkbox and radiobox

Checkbox and radio controls

list and combobox

Selection controls

inputfile

File input control

Plugins

Netfront supports the Netscape plugin API. This means that all the plugins that are available for voyager vserver run without any changes in netfront.

For more information, see http://www.access.co.jp/english/index.html.

voyager — Voyager browser

Syntax:

voyager [options]

Runs on:

Neutrino

Options:

-A

Run alone: don't connect to a currently running Voyager client, and don't allow other clients to connect to this client.

-C my_config

Load the startup configuration from the file identified by my_config. The default configuration file is ${HOME}/.ph/voyager/config.full.

-c

Run in compact mode: launch the compact server, and use text labels in the main toolbar.

-D options

Disable one or more of the following options:

• h — changing URLs in the Hotlist editor
• l — location bar
• m — menu bar
• o — opening a site from the File menu (and Ctrl-O)
• p — splash screen
• r — base window resizing
• s — status bar
• t — toolbar.

-e my_encoding

Use my_encoding as the startup encoding. The default encoding is "Western European (ISO 8859-1)".

-h height[%]

The height of the window, in pixels, or as a percentage of the screen height if % is specified.

-n ServerName

Specifies the connector name of the server to connect to. The connector name has to match the connector name that is used by the server. Both vserver and netfront have a -n option that allows you to tell them what connector name to register; see the documentation for the server you're using for more information.

---

The default connector name used by the Voyager client is specified in the online section of the webservers profile.

---

-N client_name

Register this name for this client. The default client_name is VoyagerClient.

-P my_server

Start the Voyager Server executable identified by my_server, if necessary. You must also specify the server connector name using the -n option.

---

When used with the -n ServerName option, Voyager first attempts to connect to the ServerName. If it isn't running, it spawns the server indicated by my_server, and tries to connect to it using the connector name specified by ServerName. The default server used by the Voyager client is specified in the online section of the webservers profile.

---

-Si|m

The initial state of the main window (iconified or maximized).

-s server_name

The name of the Photon server:

If server_name is:	This server is used:
node_path	node_path/dev/photon
fullpath	fullpath
relative_path	/dev/relative_path

-u URL

The URL to load on starting up.

-W

Don't open a new window when another client with a URL connects; reuse the current window.

-w width[%]

The width of the window, in pixels, or as a percentage of the screen width if % is specified.

-x position[%][r]

The x coordinate of the upper-left corner of the window, in pixels, or as a percentage of screen width if % is specified. If r is specified, the coordinate is relative to the current console.

-y position[%][r]

The y coordinate of the upper-left corner of the window, in pixels, or as a percentage of screen height if % is specified. If r is specified, the coordinate is relative to the current console.

Description:

This command starts the QNX Voyager browser. You need to be running Photon to use it.

The QNX Voyager browser is a client-server application. The client provides the GUI interface for the browser, and the server provides the rendering engine. You can configure the browser to use either the vserver or netfront servers — the features available in the browser are slightly different with each server. You can specify which server is used for different browsing situations, or profiles. See the Pt_ARG_WEB_SERVER resource of PtWebClient for a description of web server profiles.

Voyager launches a media player and the appropriate plugin when you select an HREF on a web page. This works for .mpg, .mpeg, .wav, .au, .aif, .mp3, .mp1, .mp2, .mpa, .mpv, and .m2v (Mpeg II video) files. A helper application downloads the file to /tmp and runs a media player on it.

---

You'll need to clean up your /tmp directory if you use a lot of video.

---

Voyager has embedded plugins for the media types listed above. If you create an HTML page as shown below with any of the above file types, Voyager handles it. Video embedded in the HTML page, and audio play in the background.

<html>
<body>
<embed src="l30sstd.mpv" width=400 height=300>
</embed>
some text some test <br>
<br>
<br>
some text some text
</body>
</html>

or:

<html>
<body>
<embed src="Slayers-Get_Along.mp3" >
</embed>
some text some test <br>
<br>
<br>
some text some text
</body>
</html>

or:

<html>
<body>
<embed src="cat.wav" >
</embed>
some text some test <br>
<br>
<br>
some text some text
</body>
</html>

Browsing with Voyager

You can perform these browsing tasks using Voyager:

Navigating

You can navigate web pages by using the following commands:

Examples:

Start with Japanese encoding, get configuration information from the file /setup/vconfig, disable the splash-screen and the toolbar, use the Voyager Server called new.server in /tmp:

voyager -e "Japanese (Shift JIS)" \ 
-C /setup/vconfig -D pt -P /tmp/new.server

Run at the initial position (10,10) with an initial dimension of 200×300:

voyager -x10 -y10 -h200 -w300

Start with the NetFront server:

voyager -n NetfrontServer

Files:

${HOME}/.ph/voyager/config.full

The default configuration file.

$HOME/.ph/webservers and /etc/photon/webservers

The server profiles, which specify the server for different browsing situations. See the Pt_ARG_WEB_SERVER resource of PtWebClient for a description of web server profiles.

Environment variables:

FLASHQUALITY

The resolution to use with Macromedia Flash. If this environment variable isn't set, high resolution is used. To use low resolution, set FLASHQUALITY to LOW: this uses less CPU.

Caveats:

You need hardware with an FPU for MPEG decoding because floating-point emulation is too slow. We don't currently support a fixed-point MPEG audio decoder.

You need to run the pipe manager in order for Voyager to perform a DNS lookup.

vserver — Voyager server

Syntax:

vserver [options]

Runs on:

Neutrino

Options:

-l

(“el”) Start up with low-memory options:

max_connections     =  3
Page_Cache_Size     =  0
Image_Cache_Size_KB = 512
view_source         = FALSE
enable_disk_cache   = FALSE
concurrent_decodes  = 1

-M nbytes

Let the Voyager server obtain nbytes on startup and use only that as its usable free memory (vserver will never ask the system for more memory).

-n ServerName

Start the Voyager server with ServerName as the registered connector name. Use the Pt_ARG_CLIENT_NAME resource to connect a PtWebClient to a Voyager server with ServerName.

The default server name is VoyagerServer.

-x

Start in server mode; vserver doesn't exit on the last close from a PtWebClient widget.

Description:

The vserver command starts the Voyager server.

---

You must be running Photon to use vserver.

---

The Voyager server currently supports HTML version 3.2.

If you're using PtWebClient to start vserver, you can specify options in the Pt_ARG_WEB_SERVER resource. For more information, see the Photon Widget Reference.

Caveats:

You need to run the pipe manager in order for Voyager to perform a DNS lookup.

Technical support

If you have any questions, comments, or problems with a QNX product, please contact Technical Support. For more information, see the How to Get Help chapter of the Welcome to QNX Momentics guide or visit our website, www.qnx.com.