Plug-in For Hosting ActiveX Controls

Introduction

To complement the ActiveX control there is plug-in project that shares many of the same files. This allows browsers and environments that support the Netscape Plug-in Architecture to display ActiveX controls. These include:

There have been previous plug-ins for Netscape Navigator/Communicator that host ActiveX controls but most such as the NCompass plug-in are defunct.

This is the first open source implementation and also one of the lightest and fastest as well because it uses ATL rather than MFC.

Should I use ActiveX or XPConnect?

This plug-in is not part of the Mozilla distribution and even if it were it would be disabled by default. It is extremely, hell-freezing-overly, unlikely that Mozilla is ever going to support ActiveX by default. This plug-in is designed for custom, legacy and intranet solutions and nothing else. 

If you want scripting in Mozilla then the use of XPConnect via the NPAPI is the only recommended method and strongly encouraged - it's actually a lot more powerful and tightly coupled to Mozilla (e.g. complete and full access to the DOM, cross platform support etc.). Go here for more info. The ActiveX plug-in will always be a poor second best.

Different build modes

The plug-in may be built in a number of different ways to support different Mozilla and Netscape browsers.

It is possible to build the plug-in with both LiveConnect & XPConnect enabled, but COM connect must be built by itself. 

Please don't bug me about sending you entire builds of Mozilla with COM connect enabled - I don't have the time or resources to send out 10mb builds on demand. The source is there if you want to try it yourself!

Get the source

See the instructions on the mozilla.org website on how to get the source. You can also see the code online.

Build it

First you need to build Mozilla so follow the instructions here to get a working environment and then read on. 

For COM Connect

Enabling this mode is easy, just add --enable-activex-scripting to your mozconfig file, e.g.

ac_add_options --enable-activex-scripting

Build Mozilla as normal and COM connect, the npmozax.dll plug-in and nsAxSecurityPolicy.js component should be built as part of the process. By default ActiveX is completely locked down, so read the section below on security to learn how to configure it.

As noted, COM connect is an explicit build mode and results in a plug-in that will only work with that specific build and is not backwards compatible.

Otherwise...

As the plug-in is not built by default you must do the following:

  1. cd mozilla\embedding\browser\activex\src

  2. Edit Makefile & Makefile.in with notepad and add plug-in to the DIRS line

  3. Edit plugin\Makefile.in in notepad and read the "Makefile settings" section below to see what to change.

  4. Type "make"

This creates a plug-in named npmozax.dll that you should copy to the plugins/ folder of Netscape Communicator 4.x, Mozilla or Netscape 6.x. If you enabled XPConnect or LiveConnect are enabled you must also copy those files too.

You should be able to run your browser and verify that the plug-in is there by choosing "Help|About Plug-ins" from the menu. To test it, try loading a page containing an ActiveX control such as this one.

Note 1: The Mozilla milestone and Netscape 6.x releases do not contain the plug-in support.

Note 2: The 1.0 branch still uses DevStudio nmake so you must edit makefile.win instead of Makefile.in on that branch.

Makefile settings

The Makefile contains various settings to enable or disable XPConnect and LiveConnect support. If you want to disable both, ensure 

Enabling XPConnect

XPConnect is the scripting technology found in Mozilla 1.0 and later. Ensure this line is uncommented.

MOZ_ACTIVEX_PLUGIN_XPCONNECT = 1

If MOZ_ACTIVEX_PLUGIN_XPCONNECT is not specified, the plug-in will build without XPConnect support.

When uncommented, the plug-in will build with XPConnect support. The nsIMozAxPlugin.idl provides the scripting interface through which the control may be scripted. 

The nsIMozAxPlugin.xpt will be built from the IDL file and should be copied to plugins/ along with the npmozax.dll file.

Enabling LiveConnect 

LiveConnect is the scripting technology used in Netscape 4.x and below. It is a little more involved to enable than XPConnect since you need to install the Netscape Plug-in SDK for a special java stub generator and a Java SDK to compile MozAxPlugin.java into a class file. First off ensure this line is uncommented:

MOZ_ACTIVEX_PLUGIN_LIVECONNECT = 1

If MOZ_ACTIVEX_PLUGIN_LIVECONNECT is not specified, the plug-in will build without LiveConnect support.

Next install the Netscape Plug-in SDK and an old Sun JDK and note the paths where you installed them. You need a pre Java 1.3 JDK to ensure the class file is compiled correctly, I recommend JDK 1.02 as it's what I use and is a comparatively small download.

Now set these variables in the Makefile, making sure to specify paths with forward slashes:

PLUGINSDK = <path to netscape plugin sdk, e.g. c:/pluginsdk>
SDK_JAVADIR = <path to jdk, e.g. c:/jdk1.02>

The Makefile should then be set to compile the plug-in with LiveConnect support. The MozAxPlugin.class file will be built and should be copied to plugins/ along with the npmozax.dll file.

Download the precompiled Plug-in

Pick the plugin that matches your browser.

IMPORTANT! Do not download the plugin if it does not exactly correspond with your browser version. If you ignore this advice, you may now have a broken browser. If you discover this to be the case or just get sick of the plugin, delete npmozax.dll from your plugins\ dir to fix it.

Browser Links
Firefox 1.5
Test version. Does not work in any other version of Firefox or Mozilla		 Click here or download the .xpi (GPG signature)
Firefox 1.0.7
Does not work in any other version of Firefox or Mozilla		 Click here or download the .xpi (GPG signature)
Firefox 1.0.6
Does not work in any other version of Firefox or Mozilla		 Click here or download the .xpi (GPG signature)
Firefox 1.0.4
Does not work in any other version of Firefox or Mozilla		 Click here or download the .xpi (GPG signature)
Firefox 1.0.3
Does not work in any other version of Firefox or Mozilla

This is a respin of the existing plugin.
Click here or download the .xpi (GPG signature)

This is the original version of the 1.0.3 plugin
Click to download the .xpi (GPG signature)

What is the difference between the respin and the original? The binaries are identical however I have changed the activex.js policy file in the respin so that it only hosts the Windows Media Player control Going forward I only want the plugin to host controls for which no native NPAPI plugin already exists.
Firefox 1.0.2, Firefox 1.0.1 No plugin available
Firefox 1.0
Does not work in any other version of Firefox		 Click here or download the .xpi (GPG signature)
Mozilla 1.7
Does not work in Firefox 0.9 / 0.9.1		 Click here or download the .xpi (GPG signature)
Mozilla 1.6 Click here or download the .xpi (GPG signature)
Mozilla 1.5 & Firebird 0.7

Click here or download the .xpi  (GPG signature)

IMPORTANT NOTE: Scripting support is broken.
Mozilla 1.4 & Firebird 0.6 / 0.6.1 Click here or download the .xpi
Netscape 7.1 & Netscape 7.2 Netscape 7.1 & 7.2 ship with the ActiveX plugin by default. It is restricted to only hosting the the Windows Media Player control. You can play with the settings in its defaults/pref/activex.js file to enable support for other controls.
Older browsers See below

Once installed, restart your browser and you should now be able to insert OBJECT tags into pages, download and install controls and do most of the other things you would expect.

Demo pages

Some notes

A brief description of some things you should be aware of

Other browsers

Here is an older precompiled snapshot to try out for other platforms. It contains XPConnect and LiveConnect support.

To install it:

  1. If you have Mozilla or NS 7.0 you may click to install it otherwise download it to disk (note this server might serve it as text/plain in which case shift click to save it straight to disk). This is an XPInstall file (a zip file with an .xpi extension). 
  2. If you downloaded the file, manually unzip the contents and copy npmozax.dll, nsIMozAxPlugin.xpt and MozAxPlugin.class into your plug-ins folder, e.g. "c:\program files\Netscape\Program\plugins".
  3. If necessary copy the msvcrt.dll & msvcp60.dll to your windows system folder (system32 for 2000/XP/NT systems)
  4. Restart Mozilla/Netscape and verify that the plug-in has been detected by browsing to the URL about:plugins. The Mozilla plug-in should be listed.
  5. Try testing the plug-in here with the Microsoft calendar control.

As mentioned previously, please don't bug me about sending you entire builds of Mozilla with COM connect enabled - I don't have the time or resources to send out 10mb builds on demand. The source is there if you want to try it yourself! Besides you need to build the plug-in yourself in this mode due to the build specific dependencies and backwards incompatibilities it introduces.

How to use it

Whichever way the plug-in has been built, embedding a control in the page is the same.

The first way is with the <OBJECT> tag, specifying the mime type as "application/x-olebject", the dimensions, the object's classid and any properties you want the object to be initialised with.

For example:

<object type="application/x-oleobject"
    width="200" height="300" name="foo"
    classid="clsid:8E27C92B-1264-101C-8A2F-040224009C02">
  <param name="backcolor" name="16776960"/>
</object>

Or if you prefer, use the deprecated <EMBED> tag for compatibility with older Netscape browsers. Specify name/value pairs to pass to the control using  attributes beginning with "param_", e.g. "param_backcolor". The param_ part is automatically stripped so for this example the control would see a property called "backcolor", not "param_backcolor":

<embed type="application/x-oleobject" name="foo"
  align="baseline" border="0" width="200" height="300"
  clsid="{8E27C92B-1264-101C-8A2F-040224009C02}"
  param_backcolor="16776960">

Refer to the online plug-in SDK reference for more information.

Name/value pairs are passed through to the control as properties that the control can read via the IPersistPropertyBag mechanism.

This sample page uses this HTML to embed a cyan and a yellow ActiveX calendar control using the <EMBED> and <OBJECT> tags respectively.

Codebase

Note: Only supported in COM connect mode.

Use the 'codebase' attribute on an OBJECT tag to specify the location of the CAB / EXE file that may be downloaded to install the control. This attribute is of the same format as in IE:

<OBJECT codebase ="sLocation" ... >

Where sLocation is an URL which can be appended with a version string of the form #Version=a,b,c,d

a High-order word of the major version of the component available at the specified URL.

b Low-order word of the major version of the component available at the specified URL.

c High-order word of the minor version of the component available at the specified URL.

d Low-order word of the minor version of the component available at the specified URL.

For example:

<OBJECT id="Flash"
    codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=5,0,0,0">
</OBJECT>

Currently only absolute URLs are supported.

Also note that controls are downloaded and installed using a Win32 API call (CoGetClassObjectFromURL) which relies on the IE urlmon.dll library. Older versions of Windows, such as Windows 95 will not have this without first installing IE.

Scripting the plug-in

For COM Connect

Work in progress. This will not work in Mozilla 1.0.x or NS 7.x!

If Mozilla is explicitly built with COM connect support, the plug-in can script controls almost transparently - nearly the same as if the control were hosted in IE. For example:

<script>
  // For an object named 'foo'
  document.foo.DoSomething(20, "abc");
  var value = document.foo.MyProperty;
  document.foo.MyOtherProperty = 25;
<script>

Note the object is part of the document namespace, so you would have to say document.foo. This works in IE too so its possible to share code between the code. You can always use a variable to shorten it:

<script>
  var f = document.foo;
  f.DoSomethingElse();
  // etc.
</script>

Events

Mozilla as also gained support for the <script for="" event=""> notation for handling events and the plug-in will call these methods in response to events fired by the control..

<script for="foo" event="MenuSelection(item,value")>
  if (item == "stopMusic")
    document.foo.stop();
  else
    // etc.
</script>

Other event handling notations such as the 'automagic' Object::Event notation are not supported, e.g.:

<OBJECT id="Player" ...> ... </OBJECT>
<SCRIPT>
  function Player::PlayStateChange(newState)
  {
    // Javascript error! Do not use this form
  }
</SCRIPT>

For LiveConnect & XPConnect

The plug-in provides the mean to script the hosted control but it is a little clumsy since it is not transparent. You must make calls on the control via these methods:

  1. invoke
  2. setProperty
  3. getProperty

If you are familiar with the defunct NCompass ActiveX control plug-in then the above should look familiar. The LiveConnect interface is very similar partly because of the limitations imposed by LiveConnect. Documentation for the NCompass plug-in providing some useful background info can be found here courtesy of the Wayback Machine.

So for example, say you want to call a method Play on a hosted control in your plug-in named "foo". You'd write JS like this:

document.foo.invoke("Play");

If a method has arguments you'd supply them too, for example:

document.foo.invoke#("ShowVersion", 1, 0, 0, 5);

Note: In XPConnect replace # with the number of arguments, in this case 4. i.e. document.foo.invoke4("ShowVersion", etc.). The LiveConnect class file has overloaded versions of invoke() accepting different numbers of arguments.

To set a property:

document.foo.setProperty("Today", 25);

To get a property:

var today = document.foo.getProperty("Today");

The APIs for XPConnect and LiveConnect vary slightly. Please refer to the online version to determine the correct usage:

  1. XPConnect - nsIMozAxPlugin.idl
  2. LiveConnect - MozAxPlugin.java

Here is a sample page to try out scripting.

Supported data types

Scripting supports most simple data types and will marshal values back and forth between Java/JS/nsIVariant and their VARIANT equivalents. The following things will not work:

If in doubt refer to the marshaling routines to be found in XPConnect.cpp and LiveConnect.cpp in the plug-in implementation.

The XPConnect implementation relies on the nsIVariant object supported by Mozilla 1.0 and later. It probably won't work in earlier versions of Mozilla or Netscape.

Safe for scripting and control download issues

For COM Connect

Flags governing how controls may run are presently defined in nsAxSecurityPolicy.js which is installed in the components directory. At runtime this object will be asked what controls may be hosted. The complete list of flags is defined in nsIActiveXSecurityPolicy.idl.

Note: At the time of writing, the security policy allows controls to be downloaded and safe for scripting controls to be hosted and scripted. Future versions of the policy object are likely to completely disable all support by default and read their value from prefs. This code is currently commented out in the security policy object. Future versions may also allow per-site control of these settings, so that you could use a more relaxed setting for your local domain for example than for sites from the wild.

Safe for scripting

The plug-in tests if controls are safe for scripting in the usual ways:

  1. Tests if the control is said to implement the SafeForScripting category in the registry.
  2. Tests if the control provides an IObjectSafety interface indicating its IDispatch interface is safe for scripting by untrusted content.

Depending on the flags returned by the security policy object, controls not marked safe for scripting may not be hosted or scriptable.

Control Blacklisting and Whitelisting

The plug-in can be told to allow all controls by default or deny all controls by default and define specific exceptions to this policy on a per-domain or global basis. This is done by defining rules that the Gecko security manager uses to determine which controls may be hosted. The default policy and further documentation on defining these rules can be found in activex.js which is found in mozilla/dist/bin/defaults/pref in an ActiveX enabled build.

The plug-in also reads the Internet Explorer blacklist. IE has a big long list of controls which claim to be safe for scripting but aren't (including a lot of MS objects!). This list is defined in the "SOFTWARE\Microsoft\Internet Explorer\ActiveX Compatibility" registry key. Search MSDN for 'kill bit' for more information.

For LiveConnect & XPConnect

Behaviour is hardcoded. Only safe for scripting controls are hosted and scriptable. Controls are not downloaded or installed at present, though this might change.

Miscellaneous Notes

In COM connect mode, the plug-in provides a partial implementation of the IE environment for controls to call. For example, it should be possible to obtain IWebBrowser(2/App), IHTMLDocument2 and a few other methods through your site object. There is hardly any DOM support, just enough methods to obtain the user agent, current URL and a few other bits and pieces. I might be able to factor out the Mozilla control's DOM implementation and share the code with the plug-in. I have already done this with the IWebBrowser implementation so the plug-in already benefits from a reasonably complete implementation, e.g. Navigate/Navigate2 should work extremely well.

The plug-in identifier (PLID) used by the XPInstall script is hacked to workaround a bug in Mozilla 1.1.

There is no installer for Netscape 4.x and probably won't be unless someone donates a SmartUpdate script.

There is no support yet for hooking outgoing event sinks via LiveConnect or XPConnect. The plug-in does know when the control fires events but there needs to be a mechanism or callback to tell the browser about it.

Part of the effort to develop the plug-in and control has lead to the development of a bunch of handy generic classes:

Useful Links

Back to Main Page