The First Install Problem

This is an old working document; see en/Gecko_Plugin_API_Reference/Plug-in_Development_Overview for current information.

Problem Definition

The First Install Problem is the name given to the conditions arising when a plugin or embeddable software installs itself on a system first, before any other Gecko-based browser. If this happens, Gecko-based browsers often won't be able to discover the plugin, and will prompt the user to download the plugin again if the affiliated MIME type is encountered on the Web. Unless Gecko does a pre-emptive scan upon startup for desirable plugins that are not in the browser's plugins directory first, the best way to solve this problem is to encourage plugin vendors to leave DLLs (and XPT files, if applicable) in a location that Gecko can discover at runtime. This document presents a consistent way to do that.

Proposed Solution

On Mac OS X, the System's Plugins Folder will probably suffice as an install location in which browsers installed later can find their plugins. On Linux, a per-profile installation of plugins seems unavoidable. This document presents Windows solutions for plugin vendors. The solution suggests that plugin vendors ought to leave DLLs on a Windows desktop whether or not a Netscape Gecko browser is detected, and then write keys in the Windows registry giving future Netscape Gecko browsers the path where the plugin resides and meta-information about how to load the plugin. This document supplements the key parsing methodology suggested for installers. The solution is to encourage plugin vendors to write registry keys to the Win32 System Registry, like the example application.

This document proposes a meta-information model in the Win32 Registry similar to the one used by Microsoft's HKEY_CLASSES_ROOT\CLSID\ where a new ActiveX control (OCX) on the system presents its UUID as a registry key (identifying the ActiveX control) as well as information about where to find the OCX (e.g. under the InprocServer32 subkey). For Mozilla-based browsers, this system would be on a per-module basis, and instead of a UUID, we'll use a URI nomenclature that gives us the desired uniqueness. This URI nomenclature is called a Plugin Identifier (PLID) and is described on a separate page. The following write-up describes how a plugin installer can write keys to the Win32 System Registry to enable Gecko-based browsers to discover the plugin at runtime.

  1. Write a key under HKEY_LOCAL_MACHINE\Software\MozillaPlugins\ which is a vendor-determined PLID. If the HKEY_LOCAL_MACHINE\Software\MozillaPlugins key doesn't exist, create it, and write the vendor-determined PLID for each module that the vendor wishes to install. Example: A piece of software called MyApplication might create HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.0.1/ where the PLID is something the corporation that makes MyApplication (MyCompany Inc.) determines. Note that MyApplication consists of one DLL (which is an NPAPI plugin handling a given mimetype -- say application/x-myapp) and one XPT file, for scriptable interfaces.
  2. Caveat Emptor: If the key cannot be created under HKEY_LOCAL_MACHINE, create it as HKEY_CURRENT_USER\Software\MozillaPlugins\ under HKEY_CURRENT_USER. On Windows XP and Windows 2000, in order to write to the registry, sometimes the software may need Administrator privileges. Thus, some installers may need to write to the HKEY_CURRENT_USER key; this doesn't require Administrator privileges. Traditionally, HKEY_CURRENT_USER is a copy of everything in HKEY_LOCAL_MACHINE. At present plugins registered using the HKEY_CURRENT_USER\Software\MozillaPlugins\ tree are ignored by Firefox (bug 293062) but this is fixed in trunk builds (bug 293062).
  3. Add the following Values to the newly created key -- some are String Values (REG_SZ), and some are actually subkeys. String Values take the form StringValue=ValueData, and subkeys contain their own String Values and Value data.
    • "Path" -- String Value -- this would be the absolute path to the plugin module. This is the path to the actual DLL. (Note that the file name must still begin with "np", just as it must when the file is loaded from the .\plugins directory.)
      Example: 
      [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.01]
Path=C:\MyCompany\MyApplication\Netscape\npmyapp.dll
    • "XPTPath" -- String Value -- absolute path to xpt module required for scripting plug-in, if applicable
      Example: 
      [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.01]
XPTPath=C:\MyCompany\MyApplication\Netscape\npmyapp.xpt
    • "GeckoVersion" -- This is the optional mention of the minimal Gecko Version that the browser is compatible with.
      Example: 
      [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.01]
GeckoVersion=0.9.4.2
      suggesting compliance with CompuServe's deployment of a build of Gecko known as 0.9.4.2. Note that this means that at a minimum, the plugin vendor is ensuring compatibility with 0.9.4.2 browsers.
    • "ProductName" -- This is the String Value name of the actual product.
      Example: 
      [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.01]
ProductName=MyApplication Player 5
    • "Version" -- This is the versioning scheme of the above Product.
      Example: 
      [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.01]
Version=5.01
    • MimeTypes -- This is a subkey and contains individual mimetypes as further subkeys.
      HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.01/MimeTypes/someMimeTypeSubkey/
      • The MimeTypes subkey contains further subkeys based on an application's actual mimetypes.
        Examples: 
        [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.01\MimeTypes\application/x-myapp]

        There can be more than one such subkey, depending on how many mimetypes an application wishes to handle (or advertise that it handles).

      • The mimetypes subkeys contain the following string (REG_SZ) value:
        • "Description" -- This is the actual description of the mimetype, very much as it appears in the DLL (e.g. the same mimetype description that apears when you type "about:plugins" as a URL in Mozilla's location bar.
          Example: 
          [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\]\@mycompany.com/MyApplication,version=5.01\MimeTypes\application/x-myapp]
Description=MyApplication   Plugin for App Files
        • "Suffixes" -- This will be a semi-colon concatenated list of supported suffixes. This information is also stored under the Suffixes subkey (see below), but that key doesn't link suffixes to a particular mimetype.
          Example: 
          [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\]\@mycompany.com/MyApplication,version=5.01\MimeTypes\application/x-myapp]
Suffixes=app
    • Suffixes -- a subkey containing string values (REG_SZ) representing all the suffixes (3 digit extensions) supported by this module.
      Example: 
      [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\]\@mycompany.com/MyApplication,version=5.01\Suffixes]

      Inside this subkey, string values might look like:
      app
      typ
      avi
      Note that these string values (REG_SZ) don't actually have values affiliated with them.

    • "Description" -- string value describing the module (distinct from the "Description" in the MimeTypes subkey).
      Example: 
      [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.01]
Description=Scriptable MyApplication Player Version 5
    • "Vendor" -- string refering to company name
      Example: 
      [HKEY_LOCAL_MACHINE\Software\MozillaPlugins\@mycompany.com/MyApplication,version=5.01]
Vendor=MyCompany   Inc.

The example registry key shows the suggested "key creation" at work for an example application called Scobe Scrubobat (which doesn't really exist!).

Future Directions: Using OBJECT Tag with classid: Incidental Benefit

Embedders such as CompuServe (who now embed Gecko in lieu of IE as the default browser) can determine on their own the mechanisms to parse the Win32 registry for PLIDs. The Bugzilla bug open on Mozilla and Netscape 6.x is bug 44973.

If every major plugin vendor complies with the writing of plugin directory information into the registry along with a PLID, we can then use the OBJECT tag to invoke plugins based on their "classid" (their respective PLID, which is a URI, which works well with the W3C spec). For example, in our case, a prospective invocation might look like:

  <object classid="@mycompany.com/MyApplication,version=5.01"
          data="myfile.typ" codebase="http://myurl.com/myplugin/myplugin.xpi"
          type="application/x-myapp"></object>

The use of both "type" and "classid" attributes here offers the following user benefit:

  • IF there is another mimetype handler for application/x-myapp, ONLY MyApplication gets invoked. The resolution of a mimetype handler is no longer arbitrary.
  • IF the "data" file myfile.typ doesn't contain enough resource information to load the correct mimetype handling component (DLL), specifying "type" is an additional mechanism.
  • Unlike UUIDs, PLIDs are human readable, and not lengthy "garbled" strings.

(It should be noted that the "classid" attribute discussion here is a potential future direction; it doesn't yet work, at least as of Firefox 3.6.8. The recommended <object> attribute to set is still either "type" or "data".)

Advantage: We now no longer have ambiguity in determining which plugin handles what mimetype, because now the plugin has been invoked using the classid attribute of the OBJECT tag, which is in compliance with the HTML 4.01 specification for use of the OBJECT tag.

(Original proposal by Arun K. Ranganathan <aruner@netscape.com>)