View source for PWCore

=PW Core=

==Summery==

PW Core is the core component of PluginWatcher, which resides at the plugin core of the Firefox browser. The intended purpose of PW Core is to time how long it takes plugins (such as Macromedia Flash, Windows Media Player, Acrobat Reader etc...) to execute their calls and then report the runtime (in milliseconds) using the Mozilla Observer service to anyone registered to receive PluginWatcher's notifications.

==Release Information==

PW Core is part of Mozilla 1.9 and will be released along with Firefox 3. If you are interested in seeing the code please visit [https://bugzilla.mozilla.org/show_bug.cgi?id=412770 this bug].

==Runtime Data==

The runtime information that PW Core reports is always in fractions of a second. For example a reported runtime of 0.500 would mean 500 milliseconds. Because PW Core measures the wall clock time it takes for blocking plugin calls to execute, the value includes both CPU time, the wait time between allocation of CPU time to a call as well as any disk I/O time. It is therefore technically incorrect to say that the runtime is a measure of CPU use, however, it is a good representation of overall resources being taken up by the plugin.

==Usage==

To make use of PW Core you must register to receive its runtime notifications using Mozilla's Observer service. To do this you need to know the notification's topic which is 'experimental-notify-plugin-call'. If you are new to the Mozilla Observer service, you may want to familiarize yourself with it before proceeding further. You can find more information on the Observer service [http://developer.mozilla.org/en/docs/nsIObserverService here] and [http://developer.mozilla.org/en/docs/nsIObserver here].

Below are a number of JavaScript snippets that would be useful to developers trying to work with PW Core:

===Registration===

To register for PW notifications with the Observer service you must create a class with an 'observe' method which receives 3 parameters (subject, topic and data) as well as a 'register' method that contains the following code:

  var observerService = Components.classes["@mozilla.org/observer-service;1"]
                                  .getService(Components.interfaces.nsIObserverService);
  observerService.addObserver(this, "experimental-notify-plugin-call", false);

===Observing===

As discussed above, to specify what you want done when a notification arrives your class must have an 'observe' method, receiving 3 parameters (subject, topic and data) that gets called with each notification. The topic contains PW's notification topic - 'experimental-notify-plugin-call', the data is the runtime in milliseconds and the subject is always 'null' and should not be used.  

Here is an example that shows the runtime in an alert box to the user if the runtime exceeds half a second in length:

  observe: function(subject, topic, data) {	
    if (topic == "experimental-notify-plugin-call" ) {
      if (data > 0.500) {
        alert("Runtime is:" + data);
      }
    }
  }

- NOTE: This is just a simplified example and the use of alert() is discouraged as PW can send hundreds of notifications each second and could potentially cause your browser to crash if an excessive number of alert boxes are displayed.

Also note that in the example above an if statement first checks to see that the arriving notification's topic is the correct one. This is useful in cases where your class is registered to receive notifications for more than one topic with the Observer service.

===Clean Up===

To unregister your class with the Observer service - when you no longer want to be listening to PW's notifications - your class must include an 'unregister' method that contains the following code:

  var observerService = Components.classes["@mozilla.org/observer-service;1"]
                                  .getService(Components.interfaces.nsIObserverService);
  observerService.removeObserver(this, "experimental-notify-plugin-call");


===Skeleton PW Observer Class===

Below is a skeleton class that you may use to listen to PW runtime notifications:

  function PluginWatcherObserver()
  {
    this.register();	//takes care of registering this class with observer services as an observer for plugin runtime notifications
    this.registered = false;	
  }
  
  PluginWatcherObserver.prototype = {
    observe: function(subject, topic, data) {	

      if (topic == "experimental-notify-plugin-call") //In case your class is registered to listen to other topics
        //This gets executed each time a PW runtime notification arrives
        // --YOUR CODE GOES HERE--        
      }
   
  
    },
    //Takes care of registering the observer services for the "experimental-notify-plugin-call" topic
    register: function() {
      if (this.registered == false) { //This check prevents double registration -- something you want to avoid!!
        var observerService = Components.classes["@mozilla.org/observer-service;1"]
                                        .getService(Components.interfaces.nsIObserverService);
        observerService.addObserver(this, "experimental-notify-plugin-call", false);
        this.registered = true;
      }
    },
    //Unregisters from the observer services
    unregister: function() {
      if (this.registered == true) {
        var observerService = Components.classes["@mozilla.org/observer-service;1"]
                                        .getService(Components.interfaces.nsIObserverService);
        observerService.removeObserver(this, "experimental-notify-plugin-call");
        this.registered = false;
      }
    }
  }