dom/chrome-webidl/SessionStoreUtils.webidl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 interface nsIDocShell;
   6 interface nsISupports;
   7 interface nsISessionStoreRestoreData;
   8
   9 /**
  10  * A callback passed to SessionStoreUtils.forEachNonDynamicChildFrame().
  11  */
  12 callback SessionStoreUtilsFrameCallback = undefined (WindowProxy frame, unsigned long index);
  13
  14 /**
  15  * SessionStore utility functions implemented in C++ for performance reasons.
  16  */
  17 [ChromeOnly, Exposed=Window]
  18 namespace SessionStoreUtils {
  19   /**
  20    * Calls the given |callback| once for each non-dynamic child frame of the
  21    * given |window|.
  22    */
  23   [Throws]
  24   undefined forEachNonDynamicChildFrame(WindowProxy window,
  25                                         SessionStoreUtilsFrameCallback callback);
  26
  27   /**
  28    * Takes the given listener, wraps it in a filter that filters out events from
  29    * dynamic docShells, and adds that filter as a listener for the given event
  30    * type on the given event target.  The listener that was added is returned
  31    * (as nsISupports) so that it can later be removed via
  32    * removeDynamicFrameFilteredListener.
  33    *
  34    * This is implemented as a native filter, rather than a JS-based one, for
  35    * performance reasons.
  36    */
  37   [Throws]
  38   nsISupports? addDynamicFrameFilteredListener(EventTarget target,
  39                                                DOMString type,
  40                                                any listener,
  41                                                boolean useCapture,
  42                                                optional boolean mozSystemGroup = false);
  43
  44   /**
  45    * Remove the passed-in filtered listener from the given event target, if it's
  46    * currently a listener for the given event type there.  The 'listener'
  47    * argument must be something that was returned by
  48    * addDynamicFrameFilteredListener.
  49    *
  50    * This is needed, instead of the normal removeEventListener, because the
  51    * caller doesn't actually have something that WebIDL considers an
  52    * EventListener.
  53    */
  54   [Throws]
  55   undefined removeDynamicFrameFilteredListener(EventTarget target,
  56                                                DOMString type,
  57                                                nsISupports listener,
  58                                                boolean useCapture,
  59                                                optional boolean mozSystemGroup = false);
  60
  61   /*
  62    * Save the docShell.allow* properties
  63    */
  64   ByteString collectDocShellCapabilities(nsIDocShell docShell);
  65
  66   /*
  67    * Restore the docShell.allow* properties
  68    */
  69   undefined restoreDocShellCapabilities(nsIDocShell docShell,
  70                                         ByteString disallowCapabilities);
  71
  72   /**
  73    * Collects scroll position data for any given |frame| in the frame hierarchy.
  74    *
  75    * @param document (DOMDocument)
  76    *
  77    * @return {scroll: "x,y"} e.g. {scroll: "100,200"}
  78    *         Returns null when there is no scroll data we want to store for the
  79    *         given |frame|.
  80    */
  81   CollectedData? collectScrollPosition(WindowProxy window);
  82
  83   /**
  84    * Restores scroll position data for any given |frame| in the frame hierarchy.
  85    *
  86    * @param frame (DOMWindow)
  87    * @param value (object, see collectScrollPosition())
  88    */
  89   undefined restoreScrollPosition(Window frame, optional CollectedData data = {});
  90
  91   /**
  92    * Collect form data for a given |frame| *not* including any subframes.
  93    *
  94    * The returned object may have an "id", "xpath", or "innerHTML" key or a
  95    * combination of those three. Form data stored under "id" is for input
  96    * fields with id attributes. Data stored under "xpath" is used for input
  97    * fields that don't have a unique id and need to be queried using XPath.
  98    * The "innerHTML" key is used for editable documents (designMode=on).
  99    *
 100    * Example:
 101    *   {
 102    *     id: {input1: "value1", input3: "value3"},
 103    *     xpath: {
 104    *       "/xhtml:html/xhtml:body/xhtml:input[@name='input2']" : "value2",
 105    *       "/xhtml:html/xhtml:body/xhtml:input[@name='input4']" : "value4"
 106    *     }
 107    *   }
 108    *
 109    * @return object
 110    *         Returns null when there is no scroll data
 111    */
 112   CollectedData? collectFormData(WindowProxy window);
 113
 114   boolean restoreFormData(Document document, optional CollectedData data = {});
 115
 116    nsISessionStoreRestoreData constructSessionStoreRestoreData();
 117
 118    [Throws]
 119    Promise<undefined> initializeRestore(CanonicalBrowsingContext browsingContext,
 120                                         nsISessionStoreRestoreData? data);
 121
 122    [NewObject]
 123    Promise<undefined> restoreDocShellState(
 124       CanonicalBrowsingContext browsingContext,
 125       UTF8String? url,
 126       ByteString? docShellCaps);
 127
 128    undefined restoreSessionStorageFromParent(
 129      CanonicalBrowsingContext browsingContext,
 130      record<UTF8String, record<DOMString, DOMString>> sessionStorage);
 131 };
 132
 133 [GenerateConversionToJS, GenerateInit]
 134 dictionary CollectedFileListValue
 135 {
 136   DOMString type = "file";
 137   required sequence<DOMString> fileList;
 138 };
 139
 140 [GenerateConversionToJS, GenerateInit]
 141 dictionary CollectedNonMultipleSelectValue
 142 {
 143   required long selectedIndex;
 144   required DOMString value;
 145 };
 146
 147 [GenerateConversionToJS, GenerateInit]
 148 dictionary CollectedCustomElementValue
 149 {
 150   (File or USVString or FormData)? value = null;
 151   (File or USVString or FormData)? state = null;
 152 };
 153
 154 // object contains either a CollectedFileListValue or a CollectedNonMultipleSelectValue or Sequence<DOMString>
 155 // or a CollectedCustomElementValue
 156 typedef (DOMString or boolean or object) CollectedFormDataValue;
 157
 158 dictionary CollectedData
 159 {
 160   ByteString scroll;
 161   record<DOMString, CollectedFormDataValue> id;
 162   record<DOMString, CollectedFormDataValue> xpath;
 163   DOMString innerHTML;
 164   ByteString url;
 165   // mChildren contains CollectedData instances
 166   sequence<object?> children;
 167 };
 168
 169 dictionary InputElementData {
 170   sequence<DOMString> id;
 171   sequence<DOMString> type;
 172   sequence<long> valueIdx;
 173   sequence<long> selectedIndex;
 174   sequence<DOMString> selectVal;
 175   sequence<DOMString> strVal;
 176   sequence<boolean> boolVal;
 177 };