Limitations of frame scripts

Frame scripts run with system privileges and have access to the Components object, enabling them to use XPCOM objects and JSMs. Many privileged APIs will just work in a content process. Anything that just manipulates data structures will just work. XHR and Workers will work. However, some APIs that work in the chrome process will not work in a frame script. This article lists the most important of these APIs.

File I/O

You should not write to or read from the disk from a frame script, in particular, the profile directory. Even if this is possible, you should not do it and may expect that it could stop working at any time. File I/O should all be done in the chrome process. For example:

nsIFileInputStream
nsIFileOutputStream
Constructing a File from a string or nsIFile (but File objects can be sent via message manager)
HTMLInputElement.mozSetFileNameArray (alternative: mozSetFileArray)
file: URIs, see bug 1187099
<...>

XUL and browser UI

Anything that tries to touch the browser UI or anything to do with XUL is likely not to work in the content process. For example:

nsIPromptService
nsIFilePicker
nsIXUL*
<need more examples>

Services

Some services will not work in frame scripts.

Services.search
Services.downloads

Chrome windows

Anything that needs to use Chrome windows will not work in the content process. For example:

nsISessionStore
nsIWindowMediator
<need more examples>

Places API

The Places API can't be used inside a frame script. For example:

Observers in the content process

As noted in Observers in the chrome process, most observers should be registered in the chrome process and will not work in the content process. The exceptions are:

These must be registered in the content process.

QI from content window to chrome window

There's a particular pattern often used to get from a content window to the associated chrome window. It looks something like this:

window.QueryInterface(Ci.nsIInterfaceRequestor)
                         .getInterface(Ci.nsIWebNavigation)
                         .QueryInterface(Ci.nsIDocShellTreeItem)
                         .rootTreeItem
                         .QueryInterface(Ci.nsIInterfaceRequestor)
                         .getInterface(Ci.nsIDOMWindow);

This will no longer work. In the content process, the root tree item is an nsITabChild, that cannot be converted to an nsIDOMWindow, so the second getInterface call here will fail.

If you want a chrome window: send a message from the content process using the message manager. The target property of the object passed into the message handler in the chrome process is the XUL <browser> receiving the message, and you can get the chrome window from that (I'm not sure how).

nsIAboutModule

By default, custom about: pages registered using nsIAboutModule are loaded in the chrome process. This means that you can't access their content from the content process (via XHR, for example).

There is a shim for this that makes the content of about: pages registered by the add-on transparently available in the content process.

To avoid the shim: If you need to access the content of your about page from the content process, you need to register the nsIAboutModule in the content process as well as the chrome process. By default, about: pages (except for a small whitelist) are loaded in the chrome process when browsed to from the AwesomeBar.

JavaScript code modules (JSMs)

In multiprocess Firefox, a JSM loaded into the content process does not share any state with the same JSM loaded into the chrome process. See the entry in the Limitations on chrome scripts page.