/* 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 nsIDOMEventTarget;

/**
 * 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.
   *
   * Once bug 1444991 is fixed, this should start taking an EventTarget.
   */
  [implicit_jscontext]
  nsISupports addDynamicFrameFilteredListener(in nsIDOMEventTarget 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 nsIDOMEventTarget target,
                                          in AString type,
                                          in nsISupports listener,
                                          in boolean useCapture);
};