dom/webbrowserpersist/nsIWebBrowserPersistDocument.idl

   1 /* -*- Mode: IDL; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #include "nsISupports.idl"
   8 #include "nsIContentPolicy.idl"
   9
  10 interface nsIInputStream;
  11 interface nsIOutputStream;
  12 interface nsIPrincipal;
  13 interface nsIRemoteTab;
  14 interface nsIWebBrowserPersistResourceVisitor;
  15 interface nsIWebBrowserPersistWriteCompletion;
  16 interface nsIReferrerInfo;
  17 interface nsISHEntry;
  18 interface nsICookieJarSettings;
  19
  20 webidl BrowsingContext;
  21
  22 native SHEntryRef(already_AddRefed<nsISHEntry>);
  23
  24 /**
  25  * Interface for the URI-mapping information that can be supplied when
  26  * serializing the DOM of an nsIWebBrowserPersistDocument.
  27  *
  28  * @see nsIWebBrowserPersistDocument
  29  */
  30 [scriptable, uuid(d52e8b93-2771-45e8-a5b0-6e12b667046b)]
  31 interface nsIWebBrowserPersistURIMap : nsISupports
  32 {
  33   /**
  34    * The number of URI mappings.
  35    */
  36   readonly attribute unsigned long numMappedURIs;
  37
  38   /**
  39    * Obtain the URI mapping at the given index, which must be less than
  40    * numMappedURIs, as a pair of URI spec strings.
  41    */
  42   void getURIMapping(in unsigned long aIndex,
  43                      out AUTF8String aMapFrom,
  44                      out AUTF8String aMapTo);
  45
  46   /**
  47    * The spec of the base URI that the document will have after it is
  48    * serialized.
  49    */
  50   readonly attribute AUTF8String targetBaseURI;
  51 };
  52
  53 /**
  54  * Interface representing a document that can be serialized with
  55  * nsIWebBrowserPersist; it may or may not be in this process.  Some
  56  * information is exposed as attributes, which may or may not reflect
  57  * changes made to the underlying document; most of these are
  58  * self-explanatory from their names and types.
  59  */
  60 [scriptable, builtinclass, uuid(74aa4918-5d15-46b6-9ccf-74f9696d721d)]
  61 interface nsIWebBrowserPersistDocument : nsISupports
  62 {
  63   readonly attribute boolean isClosed;
  64   readonly attribute boolean isPrivate;
  65   readonly attribute AUTF8String documentURI;
  66   readonly attribute AUTF8String baseURI;
  67   readonly attribute ACString contentType;
  68   readonly attribute ACString characterSet;
  69   readonly attribute AString title;
  70   readonly attribute nsIReferrerInfo referrerInfo;
  71   readonly attribute nsICookieJarSettings cookieJarSettings;
  72   readonly attribute AString contentDisposition;
  73   readonly attribute nsIInputStream postData;
  74   readonly attribute nsIPrincipal principal;
  75
  76   /**
  77    * The cache key.  Unlike in nsISHEntry, where it's wrapped in an
  78    * nsISupportsPRUint32, this is just the integer.
  79    */
  80   [infallible]
  81   readonly attribute unsigned long cacheKey;
  82
  83   /**
  84    * This attribute is set by nsIWebBrowserPersist implementations to
  85    * propagate persist flags that apply to the DOM traversal and
  86    * serialization (rather than to managing file I/O).
  87    */
  88   attribute unsigned long persistFlags;
  89
  90   /**
  91    * Walk the DOM searching for external resources needed to render it.
  92    * The visitor callbacks may be called either before or after
  93    * readResources returns.
  94    *
  95    * @see nsIWebBrowserPersistResourceVisitor
  96    */
  97   void readResources(in nsIWebBrowserPersistResourceVisitor aVisitor);
  98
  99   /**
 100    * Serialize the document's DOM.
 101    *
 102    * @param aStream       The output stream to write the document to.
 103    *
 104    * @param aURIMap       Optional; specifies URI rewriting to perform on
 105    *                      external references (as read by readResources).
 106    *                      If given, also causes relative hyperlinks to be
 107    *                      converted to absolute in the written text.
 108    *
 109    * @param aRequestedContentType
 110    *                      The desired MIME type to save the document as;
 111    *                      optional and defaults to the document's type.
 112    *                      (If no encoder exists for that type, "text/html"
 113    *                      is used instead.)
 114    *
 115    * @param aEncoderFlags Flags to pass to the encoder.
 116    *
 117    * @param aWrapColumn   Desired text width, ignored if wrapping is not
 118    *                      specified by the encoding flags, or if 0.
 119    *
 120    * @param aCompletion   Callback invoked when writing is complete.
 121    *                      It may be called either before or after writeContent
 122    *                      returns.
 123    *
 124    * @see nsIDocumentEncoder
 125    */
 126   void writeContent(in nsIOutputStream aStream,
 127                     in nsIWebBrowserPersistURIMap aURIMap,
 128                     in ACString aRequestedContentType,
 129                     in unsigned long aEncoderFlags,
 130                     in unsigned long aWrapColumn,
 131                     in nsIWebBrowserPersistWriteCompletion aCompletion);
 132
 133   [notxpcom, nostdcall] SHEntryRef GetHistory();
 134 };
 135
 136 /**
 137  * Asynchronous visitor that receives external resources linked by an
 138  * nsIWebBrowserPersistDocument and which are needed to render the
 139  * document.
 140  */
 141 [scriptable, uuid(8ce37706-b7d3-481a-be68-54f174fc0d0a)]
 142 interface nsIWebBrowserPersistResourceVisitor : nsISupports
 143 {
 144   /**
 145    * Indicates a resource that is not a document; e.g., an image, script,
 146    * or stylesheet.
 147    *
 148    * @param aDocument   The document containing the reference.
 149    * @param aURI        The absolute URI spec for the referenced resource.
 150    * @param aContentPolicyType The type of resource.
 151    */
 152   void visitResource(in nsIWebBrowserPersistDocument aDocument,
 153                      in AUTF8String aURI,
 154                      in nsContentPolicyType aContentPolicyType);
 155
 156   /**
 157    * Indicates a subdocument resource; e.g., a frame or iframe.
 158    *
 159    * @param aDocument     The document containing the reference.
 160    * @param aSubDocument  The referenced document.
 161    */
 162   void visitDocument(in nsIWebBrowserPersistDocument aDocument,
 163                      in nsIWebBrowserPersistDocument aSubDocument);
 164
 165   /**
 166    * Indicates a cross origin subdocument resource; e.g., a frame
 167    * or iframe loaded in another process.
 168    *
 169    * @param aDocument     The document containing the reference.
 170    * @param aContext      The referenced document's browsing context.
 171    */
 172   void visitBrowsingContext(in nsIWebBrowserPersistDocument aDocument,
 173                             in BrowsingContext aContext);
 174
 175   /**
 176    * Indicates that the document traversal is complete.
 177    *
 178    * @param aDocument   The document that was being traversed.
 179    * @param aStatus     Indicates whether the traversal encountered an error.
 180    */
 181   void endVisit(in nsIWebBrowserPersistDocument aDocument,
 182                 in nsresult aStatus);
 183 };
 184
 185 /**
 186  * Asynchronous callback for when nsIWebBrowserPersistDocument is finished
 187  * serializing the document's DOM.
 188  */
 189 [scriptable, function, uuid(a07e6892-38ae-4207-8340-7fa6ec446ed6)]
 190 interface nsIWebBrowserPersistWriteCompletion : nsISupports
 191 {
 192   /**
 193    * Indicates that serialization is finished.
 194    *
 195    * @param aDocument     The document that was being serialized.
 196    *
 197    * @param aStream       The stream that was being written to.  If it
 198    *                      needs to be closed, the callback must do that;
 199    *                      the serialization process leaves it open.
 200    *
 201    * @param aContentType  The content type with which the document was
 202    *                      actually serialized; this may be useful to set
 203    *                      metadata on the result, or if uploading it.
 204    *
 205    * @param aStatus       Indicates whether serialization encountered an error.
 206    */
 207   void onFinish(in nsIWebBrowserPersistDocument aDocument,
 208                 in nsIOutputStream aStream,
 209                 in ACString aContentType,
 210                 in nsresult aStatus);
 211 };
 212
 213 /**
 214  * Asynchronous callback for creating a persistable document from some
 215  * other object.
 216  *
 217  * XXXbz This should really be changed to just return a promise that
 218  * then gets resolved or rejected...
 219  *
 220  * @see WebBrowserPersistable in FrameLoader.webidl.
 221  */
 222 [scriptable, uuid(321e3174-594f-4036-b7be-791b821bd376)]
 223 interface nsIWebBrowserPersistDocumentReceiver : nsISupports
 224 {
 225   void onDocumentReady(in nsIWebBrowserPersistDocument aDocument);
 226   void onError(in nsresult aFailure);
 227 };