1 files changed, 113 insertions, 0 deletions
diff --git a/dom/chrome-webidl/UserInteraction.webidl b/dom/chrome-webidl/UserInteraction.webidl
new file mode 100644
index 0000000000..ccde57dcac
--- /dev/null
+++ b/dom/chrome-webidl/UserInteraction.webidl
@@ -0,0 +1,113 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this file,
+ * You can obtain one at http://mozilla.org/MPL/2.0/.
+ */
+
+[ChromeOnly, Exposed=Window]
+namespace UserInteraction {
+  /**
+   * Starts a timer associated with a UserInteraction ID. The timer can be
+   * directly associated with a UserInteraction ID, or with a pair of a
+   * UserInteraction ID and an object.
+   *
+   * @param id - the interaction being recorded, as
+   * declared in UserInteractions.yaml. This is also the annotation
+   * key that will be set in the BHR hang report if a hang occurs
+   * before the UserInteraction is finished.
+   *
+   * @param value - a value to be set on the key in the event
+   * that a hang occurs when the timer is running. This value is limited
+   * to 50 characters to avoid abuse, and if the value exceeds that limit
+   * then no timer is started, an error is printed, and this function returns
+   * false.
+   *
+   * @param obj - Optional parameter. If specified, the timer is
+   * associated with this object, meaning that multiple timers for the
+   * same annotation key may be run concurrently, as long as they are
+   * associated with different objects.
+   *
+   * @returns True if the timer was successfully started, false otherwise.
+   * If a timer already exists, it will be overwritten, and the new timer
+   * will include a "(clobbered)" suffix in any BHR annotations that get
+   * created.
+   */
+  boolean start(DOMString id,
+                UTF8String value,
+                optional object? obj = null);
+
+  /**
+   * Updates an already-running timer associated with a UserInteraction ID
+   * (and object) with a new value string.
+   *
+   * @param id - the interaction being recorded, as
+   * declared in UserInteractions.yaml. This is also the annotation
+   * key that will be set in the BHR hang report if a hang occurs
+   * before the UserInteraction is finished.
+   *
+   * @param value - a new value to be set on the key in the event
+   * that a hang occurs when the timer is running. This value is limited
+   * to 50 characters to avoid abuse.
+   *
+   * @param obj - Optional parameter. If specified, the timer is
+   * associated with this object, meaning that multiple timers for the
+   * same annotation key may be run concurrently, as long as they are
+   * associated with different objects.
+   *
+   * @returns True if the timer was successfully updated, false
+   * otherwise.
+   */
+  boolean update(DOMString id,
+                 UTF8String value,
+                 optional object? obj = null);
+
+  /**
+   * Cancels the timer associated with the given UserInteraction ID
+   * (and object) and does not add the profiler marker for it.
+   *
+   * @param id - the interaction being recorded, as
+   * declared in UserInteractions.yaml.
+   *
+   * @param obj - Optional parameter which associates the
+   * timer with the given object.
+   *
+   * @returns True if the timer was successfully stopped.
+   */
+  boolean cancel(DOMString id, optional object? obj = null);
+
+  /**
+   * Returns whether a UserInteraction timer is currently running.
+   *
+   * @param id - the ID of the interaction to check, as declared in
+   * UserInteractions.yaml.
+   *
+   * @param obj - Optional parameter which checks for a timer associated
+   * with this particular object. If you're checking for a running timer
+   * that was started with an object, you'll need to pass in that same
+   * object here to check its running state.
+   *
+   * @returns True if the timer exists and is currently running.
+   */
+  boolean running(DOMString id, optional object? obj = null);
+
+  /**
+   * Stops the timer associated with the given UserInteraction ID
+   * (and object), calculates the time delta between start and finish,
+   * and adds a profiler marker with that time range.
+   *
+   * @param id - the interaction being recorded, as
+   * declared in UserInteractions.yaml.
+   *
+   * @param obj - Optional parameter which associates the
+   * timer with the given object.
+   *
+   * @param additionalText - Optional parameter with includes additional
+   * text in the profiler marker. This text is not included in the hang
+   * annotation.
+   *
+   * @returns True if the timer was successfully stopped and the data
+   * was added to the profile.
+   */
+  boolean finish(DOMString id,
+                 optional object? obj = null,
+                 optional UTF8String additionalText);
+};