toolkit/components/sessionstore/nsISessionStoreUtils.idl
author Alphan Chen <alchen@mozilla.com>
Tue, 23 Oct 2018 08:15:56 +0000
changeset 442553 5b7afb9ada5e29dabba18a040bdcb509f3a3a315
parent 416737 1877b11a8fb6e62e88bbc7cb31517a74fae8f6e9
child 452616 1054653e187dc65cf6451104ee63561fe5565d0d
permissions -rw-r--r--
Bug 1497144 - Rewrite DocShellCapabilities.jsm and ScrollPosition.jsm into C++ r=nika Differential Revision: https://phabricator.services.mozilla.com/D8083

/* 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/. */

#include "nsISupports.idl"

interface mozIDOMWindowProxy;
interface nsIDocShell;
webidl EventTarget;
webidl Document;
interface mozIDOMWindow;

/**
 * A callback passed to nsISessionStoreUtils.forEachNonDynamicChildFrame().
 */
[function, scriptable, uuid(8199ebf7-76c0-43d6-bcbe-913dd3de3ebf)]
interface nsISessionStoreUtilsFrameCallback : nsISupports
{
  /**
   * handleFrame() will be called once for each non-dynamic child frame of the
   * given parent |frame|. The second argument is the |index| of the frame in
   * the list of all child frames.
   */
  void handleFrame(in mozIDOMWindowProxy frame, in unsigned long index);
};

/**
 * SessionStore utility functions implemented in C++ for performance reasons.
 */
[scriptable, uuid(2be448ef-c783-45de-a0df-442bccbb4532)]
interface nsISessionStoreUtils : nsISupports
{
  /**
   * Calls the given |callback| once for each non-dynamic child frame of the
   * given |window|.
   */
  void forEachNonDynamicChildFrame(in mozIDOMWindowProxy window,
                                   in nsISessionStoreUtilsFrameCallback callback);

  /**
   * Takes the given listener, wraps it in a filter that filters out events from
   * dynamic docShells, and adds that filter as a listener for the given event
   * type on the given event target.  The listener that was added is returned
   * (as nsISupports) so that it can later be removed via
   * removeDynamicFrameFilteredListener.
   *
   * This is implemented as a native filter, rather than a JS-based one, for
   * performance reasons.
   */
  [implicit_jscontext]
  nsISupports addDynamicFrameFilteredListener(in EventTarget target,
                                              in AString type,
                                              in jsval listener,
                                              in boolean useCapture);

  /**
   * Remove the passed-in filtered listener from the given event target, if it's
   * currently a listener for the given event type there.  The 'listener'
   * argument must be something that was returned by
   * addDynamicFrameFilteredListener.
   *
   * This is needed, instead of the normal removeEventListener, because the
   * caller doesn't actually have something that WebIDL considers an
   * EventListener.
   */
  void removeDynamicFrameFilteredListener(in EventTarget target,
                                          in AString type,
                                          in nsISupports listener,
                                          in boolean useCapture);

  /*
   * Save the docShell.allow* properties
   */
  ACString collectDocShellCapabilities(in nsIDocShell docShell);

  /*
   * Restore the docShell.allow* properties
   */
  void restoreDocShellCapabilities(in nsIDocShell docShell,
                                   in ACString disallowCapabilities);

  /**
   * Collects scroll position data for any given |frame| in the frame hierarchy.
   *
   * @param document (DOMDocument)
   *
   * @return {scroll: "x,y"} e.g. {scroll: "100,200"}
   *         Returns null when there is no scroll data we want to store for the
   *         given |frame|.
   */
  ACString collectScrollPosition(in Document document);

  /**
   * Restores scroll position data for any given |frame| in the frame hierarchy.
   *
   * @param frame (DOMWindow)
   * @param value (ACString)
   */
  void restoreScrollPosition(in mozIDOMWindow frame, in ACString data);
};