Difference between revisions of "Adding files to an extension's uninstallation"

Revision as of 21:37, 23 May 2007

Uninstall logs are no longer used or necessary since Firefox 1.5. See bug 286100 for more info.

The uninstall log

When an extension is installed, the Extension Manager creates a log of the files which comprise that extension. This log is used by the Extension Manager to cleanly uninstall an extension when requested by the user. Here's a real log created when the PasswordMaker extension is installed on a Windows OS:

add	C:\Documents and Settings\Eric Jung\Application Data\Mozilla\Firefox\Profiles\ifk9k760.dev9\extensions\
        {5872365e-67d1-4afd-9480-fd293bebd20d}\install.rdf
add	C:\Documents and Settings\Eric Jung\Application Data\Mozilla\Firefox\Profiles\ifk9k760.dev9\extensions\
        {5872365e-67d1-4afd-9480-fd293bebd20d}\defaults\passwordmakerdialog.ico
add	C:\Documents and Settings\Eric Jung\Application Data\Mozilla\Firefox\Profiles\ifk9k760.dev9\extensions\
        {5872365e-67d1-4afd-9480-fd293bebd20d}\defaults\passwordmakerdialog.xpm
add	C:\Documents and Settings\Eric Jung\Application Data\Mozilla\Firefox\Profiles\ifk9k760.dev9\extensions\
        {5872365e-67d1-4afd-9480-fd293bebd20d}\install.js
add	C:\Documents and Settings\Eric Jung\Application Data\Mozilla\Firefox\Profiles\ifk9k760.dev9\extensions\
        {5872365e-67d1-4afd-9480-fd293bebd20d}\chrome\passwdmaker.jar
register	profile	package	passwdmaker
register	profile	skin	classic/1.0

An extension's log is written to the file %Profile%/extensions/{GUID}/uninstall/Uninstall. Note the lack of an extension on the filename is not a typographical error.

"Add" entries

Each add entry in the log contains the full name and path of a file which was written to disk when this extension was installed. In the example above, the add entries have line breaks for clarity, but they are written without these line break in the real log file. The general format of an add entry is:

add\tpath\filename\n

where \t is a tab character and \n is a newline character.

When an extension is uninstalled, the Extension Manager reads the extension's log and subsequently deletes each file that has an add entry.

Adding entries to the uninstall log

If an extension creates file(s) during its lifetime, and the extension developer would like those file(s) automatically deleted when the extension is uninstalled, add entries must be written to the log for each file to be deleted. There is a feature request in BugZilla to provide a programmatic interface on the Extension Manager with which to manipulate the Uninstall log, but until that request is fulfilled, the following code can be used. It makes use of io.js variables and functions:

/**
 * Adds an "add" entry to this extension's Uninstall log.
 * The file argument can be created by DirIO.get() or FileIO.get()
 * in io.js. The guid argument is the GUID for your extension,
 * including braces and dashes; e.g, "{5872365E-67D1-4AFD-9480-FD293BEBD20D}"
 *  See usage example below.
 */
function addToUninstallList(file, guid) {
  // make sure the new file is in the extension uninstall list
  var uninstallFile = DirIO.get("ProfD"); // %Profile% dir
  uninstallFile.append("extensions");
  uninstallFile.append(guid);
  uninstallFile.append("uninstall");
  uninstallFile.append("Uninstall");
  var data = FileIO.read(uninstallFile);
  var r = new RegEx("^add\s.*" + file.path", "m");
  if (!data || r.test(data)) {
    // Uninstall file doesn't exist or filename is
    // already listed in it.
    return;
  }
  // Add new file to the Uninstall list.
  // Note we're not using the FileIO.path() function
  // because it returns an URL-encoded path (e.g., a space equals %20)
  var newLine = "add\t" + file.path + "\n";
  FileIO.write(uninstallFile, newLine, "a");
}

Sample use of the function:

// Write a file. If successful, update the Uninstall log
// so the file is automatically deleted when our extension
// is uninstalled by the user.  
var myfile = DirIO.get("ProfD"); // %Profile% dir
  myfile.append("extensions");
  myfile.append("{5872365E-67D1-4AFD-9480-FD293BEBD20D}");
  myfile.append("myfile.xml"); 
  if (FileIO.write(myfile, "<hello-world/>", "w")) {
    // Make sure the new file is in the extension uninstall list
    addToUninstallList(myfile, "{5872365E-67D1-4AFD-9480-FD293BEBD20D}");
  }

References

• Performing file IO
• io.js - the above code depends on variables and functions defined by this
• Enhanced Extension Installation and why Uninstall logs may eventually disappear