Using nsIXULAppInfo

  • Revision slug: Using_nsIXULAppInfo
  • Revision title: Using nsIXULAppInfo
  • Revision id: 351927
  • Created:
  • Creator: mnoorenberghe
  • Is current revision? Yes
  • Comment Fixed id for xpcshell section

Revision Content

 

Starting with Mozilla/XULRunner 1.8, there now is a way to find out which application, application version, and Gecko version your code is running on.

This is useful, for example, for extensions that support several Mozilla-based applications or several versions of a single application. This is not useful for scripts on webpages, which should continue using the navigator object when it's not possible to rely on feature-detection.

nsIXULAppInfo interface

To distinguish between different Mozilla-based applications, use the frozen nsIXULAppInfo interface. The following sections provide a few examples of using nsIXULAppInfo from JavaScript.

Note that while Firefox 1.5, Thunderbird 1.5, and XULRunner 1.8-based applications support nsIXULAppInfo, older applications, such as Firefox and Thunderbird 1.0, do not support it. You'll need to have additional code for those older versions.

Getting nsIXULAppInfo

To get a component implementing nsIXULAppInfo use this code:

var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);

(For explanation see this Creating XPCOM article.)

Getting application information

After you obtained the app info component, you can read its properties to get the application's ID, human-readable name, version, platform version, etc. For complete list of nsIXULAppInfo's properties, please see nsIXULAppInfo interface description.

ID

You can tell which application you're running under using the nsIXULAppInfo.ID property.

const FIREFOX_ID = "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}";
const THUNDERBIRD_ID = "{3550f703-e582-4d05-9a08-453d09bdfdc6}";
const SEAMONKEY_ID = "{92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}";
var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);
if(appInfo.ID == FIREFOX_ID) {
  // running under Firefox
} else if(appInfo.ID == THUNDERBIRD_ID) {
  // running under Thunderbird
} else if(appInfo.ID == SEAMONKEY_ID) {
  // running under SeaMonkey
} else {
  // another app
}

Note: you could also use nsIXULAppInfo.name, which is a human-readable name for the application, such as "Firefox", "Thunderbird" or "SeaMonkey", but who knows, maybe they'll rename it again!

Version

Sometimes you need to know the version of the application your code is running under. For example, one of unfrozen functions you're relying on was changed.

Note: nsIXULAppInfo provides information about the application and the platform, be careful to use the right one, especially when dealing with XULRunner-based applications.

In such cases, you probably want to check nsIXULAppInfo.version and/or nsIXULAppInfo.appBuildID. The latter is useful if you're trying to support nightly development builds of the application, and the former can be useful if you only support official releases, and to distinguish between branch and trunk builds.

Example 1: checking Firefox version

// assuming we're running under Firefox
var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);
var versionChecker = Components.classes["@mozilla.org/xpcom/version-comparator;1"]
                               .getService(Components.interfaces.nsIVersionComparator);
if(versionChecker.compare(appInfo.version, "1.5") >= 0) {
  // running under Firefox 1.5 or later
}

See {{ interface("nsIVersionComparator") }} for details

Example 2: dealing with nightlies

var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);
if(appInfo.appBuildID >= "2005093006") {
  // running on a build after 2005093006
}

You shouldn't rely on build IDs for releases, as build ID might be different for custom build or a localized version of an application.

Platform version

nsIXULAppInfo provides version information about both the XUL application (such as Firefox) and the platform (i.e. Gecko or XULRunner). For example, in Firefox 1.5 beta 2 application version is 1.4.1 and platform version is 1.8b5. Be careful to use the information you need, especially when dealing with XULRunner-based applications.

Obtaining platform version information is done like this:

var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);
var platformVer = appInfo.platformVersion;
var platformBuildID = appInfo.platformBuildID;

Getting nsIXULAppInfo in xpcshell tests

In Firefox 21, a testing module was added that provides access to app info during the execution of xpcshell tests. See Bug 809920, and in summary:

// Work around the fact that xpcshell doesn't have a proper app-info XPCOM object.
Cu.import("resource://testing-common/AppInfo.jsm");
updateAppInfo();

Older versions

As stated above, older Mozilla 1.7-based applications do not support nsIXULAppInfo. You'll have to write additional code if you choose to support those versions.

For example, Firefox and Thunderbird 1.0 stored their ID in the app.id preference (and their version in app.version), so you could use code like this to find out what application you're running under:

function getAppID() {
  var id;
  if("@mozilla.org/xre/app-info;1" in Components.classes) {
    // running under Mozilla 1.8 or later
    id = Components.classes["@mozilla.org/xre/app-info;1"]
                   .getService(Components.interfaces.nsIXULAppInfo).ID;
  } else {
    try {
      id = Components.classes["@mozilla.org/preferences-service;1"]
                     .getService(Components.interfaces.nsIPrefBranch)
                     .getCharPref("app.id");
    } catch(e) {
      // very old version
      dump(e);
    }
  }
  return id;
}
alert(getAppID());

See also

  • MXR: {{ Source("xpcom/system/nsIXULAppInfo.idl", "nsIXULAppInfo.idl") }}

{{ languages( { "fr": "fr/Utilisation_de_nsIXULAppInfo", "pl": "pl/Zastosowanie_nsIXULAppInfo" } ) }}

Revision Source

<p>&nbsp;</p>
<p>Starting with Mozilla/<a href="/en/XULRunner" title="en/XULRunner">XULRunner</a> 1.8, there now is a way to find out which application, application version, and <a href="/en/Gecko" title="en/Gecko">Gecko</a> version your code is running on.</p>
<p>This is useful, for example, for <a href="/en/Extensions" title="en/Extensions">extensions</a> that support several Mozilla-based applications or several versions of a single application. This is <strong>not</strong> useful for scripts on webpages, which should continue using the <a href="/en/DOM/window.navigator" title="en/DOM/window.navigator">navigator object</a> when it's not possible to rely on feature-detection.</p>
<h2 id="nsIXULAppInfo_interface" name="nsIXULAppInfo_interface"><code>nsIXULAppInfo</code> interface</h2>
<p>To distinguish between different Mozilla-based applications, use the frozen <a href="/en/XPCOM_Interface_Reference/nsIXULAppInfo" title="en/nsIXULAppInfo">nsIXULAppInfo</a> interface. The following sections provide a few examples of using <code>nsIXULAppInfo</code> from JavaScript.</p>
<p>Note that while Firefox 1.5, Thunderbird 1.5, and <a href="/en/XULRunner" title="en/XULRunner">XULRunner</a> 1.8-based applications support <code>nsIXULAppInfo</code>, older applications, such as Firefox and Thunderbird 1.0, do not support it. You'll need to have <a href="#old">additional code for those older versions</a>.</p>
<h3 id="Getting_nsIXULAppInfo" name="Getting_nsIXULAppInfo">Getting <code>nsIXULAppInfo</code></h3>
<p>To get a component implementing <code>nsIXULAppInfo</code> use this code:</p>
<pre class="brush: js">
var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);
</pre>
<p>(For explanation see <a class="external" href="/en/Creating_XPCOM_Components" title="https://developer.mozilla.org/en/Creating_XPCOM_Components">this Creating XPCOM article</a>.)</p>
<h3 id="Getting_application_information" name="Getting_application_information">Getting application information</h3>
<p>After you obtained the app info component, you can read its properties to get the application's ID, human-readable name, version, platform version, etc. For complete list of <code>nsIXULAppInfo</code>'s properties, please see <a href="/en/XPCOM_Interface_Reference/nsIXULAppInfo" title="en/nsIXULAppInfo">nsIXULAppInfo</a> interface description.</p>
<h4 id="ID" name="ID">ID</h4>
<p>You can tell which application you're running under using the <code>nsIXULAppInfo.ID</code> property.</p>
<pre class="brush: js">
const FIREFOX_ID = "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}";
const THUNDERBIRD_ID = "{3550f703-e582-4d05-9a08-453d09bdfdc6}";
const SEAMONKEY_ID&nbsp;=&nbsp;"{92650c4d-4b8e-4d2a-b7eb-24ecf4f6b63a}";
var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);
if(appInfo.ID == FIREFOX_ID) {
  // running under Firefox
} else if(appInfo.ID == THUNDERBIRD_ID) {
  // running under Thunderbird
} else if(appInfo.ID == SEAMONKEY_ID) {
  // running under SeaMonkey
} else {
  // another app
}
</pre>
<p>Note: you could also use <code>nsIXULAppInfo.name</code>, which is a human-readable name for the application, such as "Firefox", "Thunderbird" or "SeaMonkey", but who knows, maybe they'll rename it again!</p>
<h4 id="Version" name="Version">Version</h4>
<p>Sometimes you need to know the version of the application your code is running under. For example, one of unfrozen functions you're relying on was changed.</p>
<p><strong>Note: <code>nsIXULAppInfo</code> provides information about the <em>application</em> and the <em>platform</em>, be careful to use the right one, especially when dealing with XULRunner-based applications.</strong></p>
<p>In such cases, you probably want to check <code>nsIXULAppInfo.version</code> and/or <code>nsIXULAppInfo.appBuildID</code>. The latter is useful if you're trying to support nightly development builds of the application, and the former can be useful if you only support official releases, and to distinguish between branch and trunk builds.</p>
<p><strong>Example 1: checking Firefox version</strong></p>
<pre class="brush: js">
// assuming we're running under Firefox
var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);
var versionChecker = Components.classes["@mozilla.org/xpcom/version-comparator;1"]
                               .getService(Components.interfaces.nsIVersionComparator);
if(versionChecker.compare(appInfo.version, "1.5") &gt;= 0) {
  // running under Firefox 1.5 or later
}
</pre>
<p>See {{ interface("nsIVersionComparator") }} for details</p>
<p><strong>Example 2: dealing with nightlies</strong></p>
<pre class="brush: js">
var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);
if(appInfo.appBuildID &gt;= "2005093006") {
  // running on a build after 2005093006
}
</pre>
<p>You shouldn't rely on build IDs for releases, as build ID might be different for custom build or a localized version of an application.</p>
<h4 id="Platform_version" name="Platform_version">Platform version</h4>
<p><code>nsIXULAppInfo</code> provides version information about both the XUL application (such as Firefox) and the platform (i.e. Gecko or XULRunner). For example, in Firefox 1.5 beta 2 application version is 1.4.1 and platform version is 1.8b5. Be careful to use the information you need, especially when dealing with XULRunner-based applications.</p>
<p>Obtaining platform version information is done like this:</p>
<pre class="brush: js">
var appInfo = Components.classes["@mozilla.org/xre/app-info;1"]
                        .getService(Components.interfaces.nsIXULAppInfo);
var platformVer = appInfo.platformVersion;
var platformBuildID = appInfo.platformBuildID;
</pre>
<h3 id="Getting_nsIXULAppInfo_in_xpcshell_tests">Getting <code>nsIXULAppInfo</code> in xpcshell tests</h3>
<p>In Firefox 21, a testing module was added that provides access to app info during the execution of xpcshell tests. See <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=809920" title="https://bugzilla.mozilla.org/show_bug.cgi?id=809920">Bug 809920</a>, and in summary:</p>
<pre class="brush: js">
// Work around the fact that xpcshell doesn't have a proper app-info XPCOM object.
Cu.import("resource://testing-common/AppInfo.jsm");
updateAppInfo();</pre>
<h2 id="Older_versions" name="Older_versions">Older versions</h2>
<p>As stated above, older Mozilla 1.7-based applications do not support <code>nsIXULAppInfo</code>. You'll have to write additional code if you choose to support those versions.</p>
<p>For example, Firefox and Thunderbird 1.0 stored their ID in the <code>app.id</code> preference (and their version in <code>app.version</code>), so you could use code like this to find out what application you're running under:</p>
<pre class="brush: js">
function getAppID() {
  var id;
  if("@mozilla.org/xre/app-info;1" in Components.classes) {
    // running under Mozilla 1.8 or later
    id = Components.classes["@mozilla.org/xre/app-info;1"]
                   .getService(Components.interfaces.nsIXULAppInfo).ID;
  } else {
    try {
      id = Components.classes["@mozilla.org/preferences-service;1"]
                     .getService(Components.interfaces.nsIPrefBranch)
                     .getCharPref("app.id");
    } catch(e) {
      // very old version
      dump(e);
    }
  }
  return id;
}
alert(getAppID());
</pre>
<h2 id="See_also" name="See_also">See also</h2>
<ul>
  <li>MXR: {{ Source("xpcom/system/nsIXULAppInfo.idl", "nsIXULAppInfo.idl") }}</li>
</ul>
<p>{{ languages( { "fr": "fr/Utilisation_de_nsIXULAppInfo", "pl": "pl/Zastosowanie_nsIXULAppInfo" } ) }}</p>
Revert to this revision