xpcom/ds/nsIObserver.idlScriptable
This interface is implemented by an object that wishes to observe notifications. These notifications are often, though not always, broadcast via the nsIObserverService.
Inherits from: nsISupports Last changed in Gecko 0.9.6

Method overview

void observe(in nsISupports aSubject, in string aTopic, in wstring aData);

Methods

observe()

This method will be called when there is a notification for the topic that the observer has been registered for.

If you expect multiple topics/subjects, the implementor is responsible for filtering.

You should not modify, add, remove, or enumerate notifications in the implementation of this method.

void observe(
  in nsISupports aSubject,
  in string aTopic,
  in wstring aData
);
Parameters
aSubject
In general reflects the object whose change or action is being observed.
aTopic
Indicates the specific change or action.
aData
An optional parameter or other auxiliary data further describing the change or action.

Remarks

The specific values and meanings of the parameters provided varies widely, though, according to where the observer was registered, and what topic is being observed.

A single nsIObserver implementation can observe multiple types of notification, and is responsible for dispatching its own behavior on the basis of the parameters for a given callback. In general, aTopic is the primary criterion for such dispatch; nsIObserver implementations should take care that they can handle being called with unknown values for aTopic.

The most common implementation of nsIObserverService is the XPCOM observer service. With this implementation, it's safe (and common practice) for an implementation of nsIObserver to remove itself as an observer during the Observe callback, or to add or remove other observers. Be careful, though, because other uses of nsIObserver may not support these operations correctly within Observe.

Example

The following code is an implementation of nsIObserver that is registered to receive notifications for the "myTopicID" topic. See Observer Notifications for a list of built-in topics possible.

Observing preferences works slightly differently. See Code snippets:Preferences - Using preference observers for an example.

function myObserver()
{
  this.register();
}
myObserver.prototype = {
  observe: function(subject, topic, data) {
     // Do your stuff here.
  },
  register: function() {
    var observerService = Components.classes["@mozilla.org/observer-service;1"]
                          .getService(Components.interfaces.nsIObserverService);
    observerService.addObserver(this, "myTopicID", false);
  },
  unregister: function() {
    var observerService = Components.classes["@mozilla.org/observer-service;1"]
                            .getService(Components.interfaces.nsIObserverService);
    observerService.removeObserver(this, "myTopicID");
  }
}

Instantiation - this should be fired once you're ready to start observing (for example a window's load event).

observer = new myObserver();

Destruction - this should be fired once you're done observing (for example a window's unload event). Failure to do so may result in memory leaks.

observer.unregister();

"Get Everything" - note that "*" is an acceptable value (be careful with this, because it observes many events, and can degrade performance). 

observer.register("*");

See also