extensions/metrics/public/nsIMetricsService.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
   3 /* ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is the Metrics extension.
  17  *
  18  * The Initial Developer of the Original Code is Google Inc.
  19  * Portions created by the Initial Developer are Copyright (C) 2006
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *  Darin Fisher <darin@meer.net>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #include "nsISupports.idl"
  40
  41 interface nsIPropertyBag;
  42 interface nsIDOMWindow;
  43
  44 /**
  45  * This file defines the interfaces for the Metrics Service.
  46  *
  47  * This service allows arbitrary types of events to be logged and uploaded
  48  * to a server, based on server-configured collection parameters.
  49  * The nsIMetricsService API provides an abstraction for the underlying XML
  50  * data format.
  51  *
  52  * For more information about the data format and the built-in
  53  * event collectors, see http://wiki.mozilla.org/Browser_Metrics.
  54  */
  55
  56
  57 /**
  58  * nsIMetricsEventItem represents a particular node of data to record
  59  * in an event.  Each item has a namespaced item name, a list of properties
  60  * (key/value pairs), and an ordered list of child items.  The child items
  61  * need not be unique; an item may be repeated.
  62  */
  63 [scriptable, uuid(62f4528f-5c59-4e86-a7ee-f34b67d7d65f)]
  64 interface nsIMetricsEventItem : nsISupports
  65 {
  66   /**
  67    * The namespace for this item, which must be a valid XML namespace URI.
  68    */
  69   readonly attribute DOMString itemNamespace;
  70
  71   /**
  72    * The name of this item, which must be a valid XML tag name.
  73    */
  74   readonly attribute DOMString itemName;
  75
  76   /**
  77    * A PropertyBag containing the key/value pairs to be included in the item.
  78    * JavaScript callers can simply set this to an object containing the
  79    * key/value pairs as object properties.
  80    */
  81   attribute nsIPropertyBag properties;
  82
  83   /**
  84    * Returns the child event item at the given index.
  85    */
  86   nsIMetricsEventItem childAt(in long index);
  87
  88   /**
  89    * Returns the first occurrence of the given item in the child list,
  90    * or -1 if the item is not in the child list.
  91    */
  92   long indexOf(in nsIMetricsEventItem item);
  93
  94   /**
  95    * Appends a child event item to this item.
  96    */
  97   void appendChild(in nsIMetricsEventItem item);
  98
  99   /**
 100    * Inserts a child event item at a given index, moving later items
 101    * up by one position.
 102    *  @param item   The new item to insert
 103    *  @param index  The position in the array.  If the index is equal to
 104    *                childCount, the new item will be appended.
 105    *                The index may not be greater than childCount.
 106    */
 107   void insertChildAt(in nsIMetricsEventItem item, in long index);
 108
 109   /**
 110    * Removes a child event item at the given index, moving all items
 111    * stored at a higher position down one.
 112    */
 113   void removeChildAt(in long index);
 114
 115   /**
 116    * Replaces a child event item at the given index.
 117    *  @param newItem  The new item
 118    *  @param index    The position of the item to be replaced
 119    */
 120   void replaceChildAt(in nsIMetricsEventItem newItem, in long index);
 121
 122   /**
 123    * Clears all of the child items.
 124    */
 125   void clearChildren();
 126
 127   /**
 128    * The number of child event items
 129    */
 130   readonly attribute long childCount;
 131 };
 132
 133 [scriptable, uuid(0aad28fd-3478-4090-9730-0fff8c7683b5)]
 134 interface nsIMetricsService : nsISupports
 135 {
 136   /**
 137    * Creates a new EventItem object to hold event data.
 138    * The event will not be logged until logEvent() is called.
 139    *  @param itemNamespace   The new item's namespace
 140    *  @param itemName        The new item's name
 141    *
 142    * @returns a new MetricsEventItem instance
 143    */
 144   nsIMetricsEventItem createEventItem(in DOMString itemNamespace,
 145                                       in DOMString itemName);
 146
 147   /**
 148    * Logs an event using the given EventItem.  The event is recorded with a
 149    * timestamp generated at the time at which this method is called, and a
 150    * session id for this instance of the application.  The keys "time" and
 151    * "sessionid" are reserved for this data.
 152    *
 153    * @param item
 154    *        The item to log.  This item and its entire tree of child items
 155    *        will be logged as part of the event.
 156    */
 157   void logEvent(in nsIMetricsEventItem item);
 158
 159   /**
 160    * Constructs and logs an EventItem, using the given namespace, event name,
 161    * and event properties. This is a more convenient version of logEvent() for
 162    * the case where there are no child EventItems.
 163    *
 164    * @see nsIMetricsEventItem
 165    */
 166   void logSimpleEvent(in DOMString eventNS, in DOMString event,
 167                       in nsIPropertyBag eventValues);
 168
 169   /**
 170    * Flush data to disk.
 171    */
 172   void flush();
 173
 174   /**
 175    * Initiate the upload of the current event log.  This causes the current
 176    * event log to be truncated once the upload completes.
 177    */
 178   void upload();
 179
 180   /**
 181    * Suspend log collection.  LogEvent calls will be silently ignored while log
 182    * collection is suspended.  For each call to suspend, resume must be called
 183    * to re-enable log collection.
 184    */
 185   void suspend();
 186
 187   /**
 188    * Resume log collection.  Call this method once per call to suspend to
 189    * re-enable log collection.
 190    */
 191   void resume();
 192
 193   /**
 194    * Gets a numeric window id corresponding to the given DOMWindow.
 195    * The id remains constant for as long as the window exists.
 196    */
 197   unsigned long getWindowID(in nsIDOMWindow window);
 198 };
 199
 200 %{C++
 201 /**
 202   * Observer notifications
 203   */
 204
 205 /**
 206  * These work like NS[_CHROME]_WEBNAVIGATION_DESTROY, except that the
 207  * MetricsService is guaranteed to still know about the window which is being
 208  * destroyed (via getWindowID).  Collectors should use these notifications
 209  * instead of the docshell-provided ones.
 210  */
 211 #define NS_METRICS_WEBNAVIGATION_DESTROY "metrics-webnavigation-destroy"
 212 #define NS_METRICS_CHROME_WEBNAVIGATION_DESTROY \
 213   "metrics-chrome-webnavigation-destroy"
 214 %}