gecko/extensions/metrics/public/nsIMetricsService.idl

215 lines
7.1 KiB
Plaintext

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et cindent: */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is the Metrics extension.
*
* The Initial Developer of the Original Code is Google Inc.
* Portions created by the Initial Developer are Copyright (C) 2006
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Darin Fisher <darin@meer.net>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#include "nsISupports.idl"
interface nsIPropertyBag;
interface nsIDOMWindow;
/**
* This file defines the interfaces for the Metrics Service.
*
* This service allows arbitrary types of events to be logged and uploaded
* to a server, based on server-configured collection parameters.
* The nsIMetricsService API provides an abstraction for the underlying XML
* data format.
*
* For more information about the data format and the built-in
* event collectors, see http://wiki.mozilla.org/Browser_Metrics.
*/
/**
* nsIMetricsEventItem represents a particular node of data to record
* in an event. Each item has a namespaced item name, a list of properties
* (key/value pairs), and an ordered list of child items. The child items
* need not be unique; an item may be repeated.
*/
[scriptable, uuid(880b8655-15a4-4b72-b6d4-6e3325bca4b6)]
interface nsIMetricsEventItem : nsISupports
{
/**
* The namespace for this item, which must be a valid XML namespace URI.
*/
readonly attribute DOMString itemNamespace;
/**
* The name of this item, which must be a valid XML tag name.
*/
readonly attribute DOMString itemName;
/**
* A PropertyBag containing the key/value pairs to be included in the item.
* JavaScript callers can simply set this to an object containing the
* key/value pairs as object properties.
*/
attribute nsIPropertyBag properties;
/**
* Returns the child event item at the given index.
*/
nsIMetricsEventItem childAt(in long index);
/**
* Returns the first occurrence of the given item in the child list,
* or -1 if the item is not in the child list.
*/
long indexOf(in nsIMetricsEventItem item);
/**
* Appends a child event item to this item.
*/
void appendChild(in nsIMetricsEventItem item);
/**
* Inserts a child event item at a given index, moving later items
* up by one position.
* @param item The new item to insert
* @param index The position in the array. If the index is equal to
* childCount, the new item will be appended.
* The index may not be greater than childCount.
*/
void insertChildAt(in nsIMetricsEventItem item, in long index);
/**
* Removes a child event item at the given index, moving all items
* stored at a higher position down one.
*/
void removeChildAt(in long index);
/**
* Replaces a child event item at the given index.
* @param newItem The new item
* @param index The position of the item to be replaced
*/
void replaceChildAt(in nsIMetricsEventItem newItem, in long index);
/**
* Clears all of the child items.
*/
void clearChildren();
/**
* The number of child event items
*/
readonly attribute long childCount;
};
[scriptable, uuid(289cd0d3-00b4-4554-9e6d-71eded08d1d8)]
interface nsIMetricsService : nsISupports
{
/**
* Creates a new EventItem object to hold event data.
* The event will not be logged until logEvent() is called.
* @param itemNamespace The new item's namespace
* @param itemName The new item's name
*
* @returns a new MetricsEventItem instance
*/
nsIMetricsEventItem createEventItem(in DOMString itemNamespace,
in DOMString itemName);
/**
* Logs an event using the given EventItem. The event is recorded with a
* timestamp generated at the time at which this method is called, and a
* session id for this instance of the application. The keys "time" and
* "sessionid" are reserved for this data.
*
* @param item
* The item to log. This item and its entire tree of child items
* will be logged as part of the event.
*/
void logEvent(in nsIMetricsEventItem item);
/**
* Constructs and logs an EventItem, using the given namespace, event name,
* and event properties. This is a more convenient version of logEvent() for
* the case where there are no child EventItems.
*
* @see nsIMetricsEventItem
*/
void logSimpleEvent(in DOMString eventNS, in DOMString event,
in nsIPropertyBag eventValues);
/**
* Flush data to disk.
*/
void flush();
/**
* Initiate the upload of the current event log. This causes the current
* event log to be truncated once the upload completes.
*/
void upload();
/**
* Suspend log collection. LogEvent calls will be silently ignored while log
* collection is suspended. For each call to suspend, resume must be called
* to re-enable log collection.
*/
void suspend();
/**
* Resume log collection. Call this method once per call to suspend to
* re-enable log collection.
*/
void resume();
/**
* Gets a numeric window id corresponding to the given DOMWindow.
* The id remains constant for as long as the window exists.
*/
unsigned long getWindowID(in nsIDOMWindow window);
};
%{C++
/**
* Observer notifications
*/
/**
* These work like NS[_CHROME]_WEBNAVIGATION_DESTROY, except that the
* MetricsService is guaranteed to still know about the window which is being
* destroyed (via getWindowID). Collectors should use these notifications
* instead of the docshell-provided ones.
*/
#define NS_METRICS_WEBNAVIGATION_DESTROY "metrics-webnavigation-destroy"
#define NS_METRICS_CHROME_WEBNAVIGATION_DESTROY \
"metrics-chrome-webnavigation-destroy"
%}