We are planning to deprecate the use by Firefox add-ons of the techniques described in this document.
Don't use these techniques to develop new add-ons. Use WebExtensions instead.
If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions instead.
Add-ons developed using these techniques might not work with multiprocess Firefox (e10s), which is already the default in Firefox Nightly and Firefox Developer Edition, and will soon be the default in Beta and Release versions of Firefox. We have documentation on making your add-ons multiprocess-compatible, but it will be more future-proof for you to migrate to WebExtensions.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
Sometimes you need your code to send a message to other parts of your code. For example, you might want to notify that a task is completed, and then several different actions must be performed. You could do that by calling all those functions directly, but XPCOM offers you a better and cleaner way to achieve that using observers and the observer service.
An observer is an object that is responsible to observe (wait for) notifications and then to carry out subsequent actions. To create an observer, you need to implement the nsIObserver interface. The interface has only one method observe() which takes three parameters. The first parameter (subject) can be any XPCOM object, the second parameter is a notification topic, and the final parameter is a string that further describes the notification.
This example code shows you what an implementation of the nsIObserver interface looks like:
In order for this observer to work, you need to use the observer service that provides methods for you to add, remove, notify and enumerate observers.
Adding an observer to the observer service is simple, invoking the addObserver method with three parameters. The first parameter is an observer object, the second parameter is a notification topic, and the third parameter is a boolean which indicates whether the observer service should hold a weak reference to the observer. You should normally set the third parameter to false.
To remove an observer for a specific topic, you use the removeObserver method. The method takes the observer object and notification topic as parameters.
After you have registered some observers to listen to a notification topic, you can then use the notifyObservers method to send a notification to all of them. The method takes three parameters. The first parameter can be any XPCOM object to pass to those observers (can be null), the second parameter is the notification topic and the last parameter is an additional string to pass to those observers (can be null).
Non-chrome to chrome communication
Let's see the following example code on how to send out a notification from non-chrome code.
In the notifyTest method, the notifyObservers call is used to notify all registered observers about the notification topic "xulschoolhello-test-topic". The input parameter is an instance of nsISupportsString with some text and the last input parameter is a string "Hello".
In a chrome browser overlay file, we register an observer to listen to the notification topic "xulschoolhello-test-topic" when the window loads. Keep in mind that you have to remove observers that are not longer needed. Not doing so will result in memory leaks. Therefore, the registered observer is unregistered when the browser window is unloaded.
In the observe method the notification topic is verified because you can have one observer listening to several topics. You may notice that we explicitly set the interface of the aSubject object to nsISupportsString using the QueryInterface method. This is because the first parameter of the observe method is typed as nsISupports (the generic interface, as seen before), therefore its properties and methods cannot be accessed unless the correct interface is set to it.
When the notifyTest method is called, all observers registered with xulschoolhello-test-topic will get notified and display two alerts. If there are 2 Firefox windows open, the observer will be notified in both and the alerts will show up on both.
You can always listen for multiple notification topics using the same observer. Also, be careful not to add the same observer to a notification topic more than once, otherwise the same code in the observer will be run several times when a notification is sent.
Useful Firefox notifications
We have covered sending and receiving custom notification topics using observers and the observer service. In Firefox, there are many built-in observer topics that you can observe as well. The Observer Notifications page lists some useful topics and is definitely worth spending time studying it.
This tutorial was kindly donated to Mozilla by Appcoast.