dom/webbrowserpersist/nsIWebBrowserPersist.idl

   1 /* -*- Mode: IDL; tab-width: 4; 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 "nsICancelable.idl"
   8 #include "nsIContentPolicy.idl"
   9
  10 interface nsIURI;
  11 interface nsIInputStream;
  12 interface nsIWebProgressListener;
  13 interface nsIFile;
  14 interface nsIChannel;
  15 interface nsILoadContext;
  16 interface nsIPrincipal;
  17 interface nsIReferrerInfo;
  18 interface nsICookieJarSettings;
  19
  20 /**
  21  * Interface for persisting DOM documents and URIs to local or remote storage.
  22  */
  23 [scriptable, uuid(8cd752a4-60b1-42c3-a819-65c7a1138a28)]
  24 interface nsIWebBrowserPersist : nsICancelable
  25 {
  26   /** No special persistence behaviour. */
  27   const unsigned long PERSIST_FLAGS_NONE = 0;
  28   /** Use cached data if present (skipping validation), else load from network */
  29   const unsigned long PERSIST_FLAGS_FROM_CACHE = 1;
  30   /** Bypass the cached data. */
  31   const unsigned long PERSIST_FLAGS_BYPASS_CACHE = 2;
  32   /** Ignore any redirected data (usually adverts). */
  33   const unsigned long PERSIST_FLAGS_IGNORE_REDIRECTED_DATA = 4;
  34   /** Ignore IFRAME content (usually adverts). */
  35   const unsigned long PERSIST_FLAGS_IGNORE_IFRAMES = 8;
  36   /** Do not run the incoming data through a content converter e.g. to decompress it */
  37   const unsigned long PERSIST_FLAGS_NO_CONVERSION = 16;
  38   /** Replace existing files on the disk (use with due diligence!) */
  39   const unsigned long PERSIST_FLAGS_REPLACE_EXISTING_FILES = 32;
  40   /** Don't modify or add base tags */
  41   const unsigned long PERSIST_FLAGS_NO_BASE_TAG_MODIFICATIONS = 64;
  42   /** Make changes to original dom rather than cloning nodes */
  43   const unsigned long PERSIST_FLAGS_FIXUP_ORIGINAL_DOM = 128;
  44   /** Fix links relative to destination location (not origin) */
  45   const unsigned long PERSIST_FLAGS_FIXUP_LINKS_TO_DESTINATION = 256;
  46   /** Don't make any adjustments to links */
  47   const unsigned long PERSIST_FLAGS_DONT_FIXUP_LINKS = 512;
  48   /** Force serialization of output (one file at a time; not concurrent) */
  49   const unsigned long PERSIST_FLAGS_SERIALIZE_OUTPUT = 1024;
  50   /** Don't make any adjustments to filenames */
  51   const unsigned long PERSIST_FLAGS_DONT_CHANGE_FILENAMES = 2048;
  52   /** Fail on broken inline links */
  53   const unsigned long PERSIST_FLAGS_FAIL_ON_BROKEN_LINKS = 4096;
  54   /**
  55    * Automatically cleanup after a failed or cancelled operation, deleting all
  56    * created files and directories. This flag does nothing for failed upload
  57    * operations to remote servers.
  58    */
  59   const unsigned long PERSIST_FLAGS_CLEANUP_ON_FAILURE = 8192;
  60   /**
  61    * Let the WebBrowserPersist decide whether the incoming data is encoded
  62    * and whether it needs to go through a content converter e.g. to
  63    * decompress it.
  64    */
  65   const unsigned long PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION = 16384;
  66   /**
  67    * Append the downloaded data to the target file.
  68    * This can only be used when persisting to a local file.
  69    */
  70   const unsigned long PERSIST_FLAGS_APPEND_TO_FILE = 32768;
  71
  72   /**
  73    * Flags governing how data is fetched and saved from the network.
  74    * It is best to set this value explicitly unless you are prepared
  75    * to accept the default values.
  76    */
  77   attribute unsigned long persistFlags;
  78
  79   /** Persister is ready to save data */
  80   const unsigned long PERSIST_STATE_READY = 1;
  81   /** Persister is saving data */
  82   const unsigned long PERSIST_STATE_SAVING = 2;
  83   /** Persister has finished saving data */
  84   const unsigned long PERSIST_STATE_FINISHED = 3;
  85
  86   /**
  87    * Current state of the persister object.
  88    */
  89   readonly attribute unsigned long currentState;
  90
  91   /**
  92    * Value indicating the success or failure of the persist
  93    * operation.
  94    *
  95    * @throws NS_BINDING_ABORTED Operation cancelled.
  96    * @throws NS_ERROR_FAILURE Non-specific failure.
  97    */
  98   readonly attribute nsresult result;
  99
 100   /**
 101    * Callback listener for progress notifications. The object that the
 102    * embbedder supplies may also implement nsIInterfaceRequestor and be
 103    * prepared to return nsIAuthPrompt or other interfaces that may be required
 104    * to download data.
 105    *
 106    * @see nsIAuthPrompt
 107    * @see nsIInterfaceRequestor
 108    */
 109   attribute nsIWebProgressListener progressListener;
 110
 111   /**
 112    * Save the specified URI to file.
 113    *
 114    * @param aURI       URI to save to file. Some implementations of this interface
 115    *                   may also support <CODE>nullptr</CODE> to imply the currently
 116    *                   loaded URI.
 117    * @param aTriggeringPrincipal
 118    *                   The triggering principal for the URI we're saving.
 119    * @param aCacheKey  The necko cache key integer.
 120    * @param aReferrerInfo  The referrer info for compute and send referrer via
 121    *                   HTTP Referer header.
 122    * @param aCookieJarSettings The cookieJarSettings for the HTTP channel which
 123    *                   is saving the URI.
 124    * @param aPostData  Post data to pass with an HTTP request or
 125    *                   <CODE>nullptr</CODE>.
 126    * @param aExtraHeaders Additional headers to supply with an HTTP request
 127    *                   or <CODE>nullptr</CODE>.
 128    * @param aFile      Target file. This may be a nsIFile object or an
 129    *                   nsIURI object with a file scheme or a scheme that
 130    *                   supports uploading (e.g. ftp).
 131    * @param aContentPolicyType The type of content we're saving.
 132    * @param aIsPrivate Treat the save operation as private (ie. with
 133    *                   regards to networking operations and persistence
 134    *                   of intermediate data, etc.)
 135    *
 136    * @see nsIFile
 137    * @see nsIURI
 138    * @see nsIInputStream
 139    *
 140    * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
 141    */
 142   void saveURI(in nsIURI aURI,
 143       in nsIPrincipal aTriggeringPrincipal, in unsigned long aCacheKey,
 144       in nsIReferrerInfo aReferrerInfo,
 145       in nsICookieJarSettings aCookieJarSettings,
 146       in nsIInputStream aPostData,
 147       in string aExtraHeaders, in nsISupports aFile,
 148       in nsContentPolicyType aContentPolicyType,
 149       in boolean aIsPrivate);
 150
 151   /**
 152    * Save a channel to a file. It must not be opened yet.
 153    * @see saveURI
 154    */
 155   void saveChannel(in nsIChannel aChannel, in nsISupports aFile);
 156
 157   /** Output only the current selection as opposed to the whole document. */
 158   const unsigned long ENCODE_FLAGS_SELECTION_ONLY = 1;
 159   /**
 160    * For plaintext output. Convert html to plaintext that looks like the html.
 161    * Implies wrap (except inside &lt;pre&gt;), since html wraps.
 162    * HTML output: always do prettyprinting, ignoring existing formatting.
 163    */
 164   const unsigned long ENCODE_FLAGS_FORMATTED = 2;
 165   /**
 166    * Output without formatting or wrapping the content. This flag
 167    * may be used to preserve the original formatting as much as possible.
 168    */
 169   const unsigned long ENCODE_FLAGS_RAW = 4;
 170   /** Output only the body section, no HTML tags. */
 171   const unsigned long ENCODE_FLAGS_BODY_ONLY = 8;
 172   /** Wrap even if when not doing formatted output (e.g. for text fields). */
 173   const unsigned long ENCODE_FLAGS_PREFORMATTED = 16;
 174   /** Wrap documents at the specified column. */
 175   const unsigned long ENCODE_FLAGS_WRAP = 32;
 176   /**
 177    * For plaintext output. Output for format flowed (RFC 2646). This is used
 178    * when converting to text for mail sending. This differs just slightly
 179    * but in an important way from normal formatted, and that is that
 180    * lines are space stuffed. This can't (correctly) be done later.
 181    */
 182   const unsigned long ENCODE_FLAGS_FORMAT_FLOWED = 64;
 183   /** Convert links to absolute links where possible. */
 184   const unsigned long ENCODE_FLAGS_ABSOLUTE_LINKS = 128;
 185
 186   /**
 187    * Output with carriage return line breaks. May also be combined with
 188    * ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform
 189    * default format is used.
 190    */
 191   const unsigned long ENCODE_FLAGS_CR_LINEBREAKS = 512;
 192   /**
 193    * Output with linefeed line breaks. May also be combined with
 194    * ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform
 195    * default format is used.
 196    */
 197   const unsigned long ENCODE_FLAGS_LF_LINEBREAKS = 1024;
 198   /** For plaintext output. Output the content of noscript elements. */
 199   const unsigned long ENCODE_FLAGS_NOSCRIPT_CONTENT = 2048;
 200   /** For plaintext output. Output the content of noframes elements. */
 201   const unsigned long ENCODE_FLAGS_NOFRAMES_CONTENT = 4096;
 202
 203   /**
 204    * Encode basic entities, e.g. output &nbsp; instead of character code 0xa0.
 205    * The basic set is just &nbsp; &amp; &lt; &gt; &quot; for interoperability
 206    * with older products that don't support &alpha; and friends.
 207    */
 208   const unsigned long ENCODE_FLAGS_ENCODE_BASIC_ENTITIES = 8192;
 209
 210   /**
 211    * Save the specified DOM document to file and optionally all linked files
 212    * (e.g. images, CSS, JS & subframes). Do not call this method until the
 213    * document has finished loading!
 214    *
 215    * @param aDocument          Document to save to file. Some implementations of
 216    *                           this interface may also support <CODE>nullptr</CODE>
 217    *                           to imply the currently loaded document.  Can be an
 218    *                           nsIWebBrowserPersistDocument or Document.
 219    * @param aFile              Target local file. This may be a nsIFile object or an
 220    *                           nsIURI object with a file scheme or a scheme that
 221    *                           supports uploading (e.g. ftp).
 222    * @param aDataPath          Path to directory where URIs linked to the document
 223    *                           are saved or nullptr if no linked URIs should be saved.
 224    *                           This may be a nsIFile object or an nsIURI object
 225    *                           with a file scheme.
 226    * @param aOutputContentType The desired MIME type format to save the
 227    *                           document and all subdocuments into or nullptr to use
 228    *                           the default behaviour.
 229    * @param aEncodingFlags     Flags to pass to the encoder.
 230    * @param aWrapColumn        For text documents, indicates the desired width to
 231    *                           wrap text at. Parameter is ignored if wrapping is not
 232    *                           specified by the encoding flags.
 233    *
 234    * @see nsIWebBrowserPersistDocument
 235    * @see WebBrowserPersistable
 236    * @see nsIFile
 237    * @see nsIURI
 238    *
 239    * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
 240    */
 241   void saveDocument(in nsISupports aDocument,
 242      in nsISupports aFile, in nsISupports aDataPath,
 243      in string aOutputContentType, in unsigned long aEncodingFlags,
 244      in unsigned long aWrapColumn);
 245
 246   /**
 247    * Cancels the current operation. The caller is responsible for cleaning up
 248    * partially written files or directories. This has the same effect as calling
 249    * cancel with an argument of NS_BINDING_ABORTED.
 250    */
 251   void cancelSave();
 252 };
 253
 254 /**
 255  * We don't export nsWebBrowserPersist.h as a public header, so we need a place
 256  * to put the CID/ContractID. All places uses the WebBrowserPersist include
 257  * nsIWebBrowserPersist.h, so we define our contract IDs here for now.
 258  */
 259 %{ C++
 260 // {7E677795-C582-4cd1-9E8D-8271B3474D2A}
 261 #define NS_WEBBROWSERPERSIST_CID \
 262   { 0x7e677795, 0xc582, 0x4cd1, { 0x9e, 0x8d, 0x82, 0x71, 0xb3, 0x47, 0x4d, 0x2a } }
 263 #define NS_WEBBROWSERPERSIST_CONTRACTID \
 264   "@mozilla.org/embedding/browser/nsWebBrowserPersist;1"
 265 %}