embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl

   1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is the Mozilla browser.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Netscape Communications, Inc.
  20  * Portions created by the Initial Developer are Copyright (C) 1999
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Adam Lock <adamlock@netscape.com>
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsICancelable.idl"
  41
  42 interface nsIURI;
  43 interface nsIInputStream;
  44 interface nsIDOMDocument;
  45 interface nsIWebProgressListener;
  46 interface nsILocalFile;
  47 interface nsIChannel;
  48
  49 /**
  50  * Interface for persisting DOM documents and URIs to local or remote storage.
  51  */
  52 [scriptable, uuid(dd4e0a6a-210f-419a-ad85-40e8543b9465)]
  53 interface nsIWebBrowserPersist : nsICancelable
  54 {
  55   /** No special persistence behaviour. */
  56   const unsigned long PERSIST_FLAGS_NONE = 0;
  57   /** Only use cached data (could result in failure if data is not cached). */
  58   const unsigned long PERSIST_FLAGS_FROM_CACHE = 1;
  59   /** Bypass the cached data. */
  60   const unsigned long PERSIST_FLAGS_BYPASS_CACHE = 2;
  61   /** Ignore any redirected data (usually adverts). */
  62   const unsigned long PERSIST_FLAGS_IGNORE_REDIRECTED_DATA = 4;
  63   /** Ignore IFRAME content (usually adverts). */
  64   const unsigned long PERSIST_FLAGS_IGNORE_IFRAMES = 8;
  65   /** Do not run the incoming data through a content converter e.g. to decompress it */
  66   const unsigned long PERSIST_FLAGS_NO_CONVERSION = 16;
  67   /** Replace existing files on the disk (use with due diligence!) */
  68   const unsigned long PERSIST_FLAGS_REPLACE_EXISTING_FILES = 32;
  69   /** Don't modify or add base tags */
  70   const unsigned long PERSIST_FLAGS_NO_BASE_TAG_MODIFICATIONS = 64;
  71   /** Make changes to original dom rather than cloning nodes */
  72   const unsigned long PERSIST_FLAGS_FIXUP_ORIGINAL_DOM = 128;
  73   /** Fix links relative to destination location (not origin) */
  74   const unsigned long PERSIST_FLAGS_FIXUP_LINKS_TO_DESTINATION = 256;
  75   /** Don't make any adjustments to links */
  76   const unsigned long PERSIST_FLAGS_DONT_FIXUP_LINKS = 512;
  77   /** Force serialization of output (one file at a time; not concurrent) */
  78   const unsigned long PERSIST_FLAGS_SERIALIZE_OUTPUT = 1024;
  79   /** Don't make any adjustments to filenames */
  80   const unsigned long PERSIST_FLAGS_DONT_CHANGE_FILENAMES = 2048;
  81   /** Fail on broken inline links */
  82   const unsigned long PERSIST_FLAGS_FAIL_ON_BROKEN_LINKS = 4096;
  83   /**
  84    * Automatically cleanup after a failed or cancelled operation, deleting all
  85    * created files and directories. This flag does nothing for failed upload
  86    * operations to remote servers.
  87    */
  88   const unsigned long PERSIST_FLAGS_CLEANUP_ON_FAILURE = 8192;
  89   /**
  90    * Let the WebBrowserPersist decide whether the incoming data is encoded
  91    * and whether it needs to go through a content converter e.g. to
  92    * decompress it.
  93    */
  94   const unsigned long PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION = 16384;
  95   /**
  96    * Append the downloaded data to the target file.
  97    * This can only be used when persisting to a local file.
  98    */
  99   const unsigned long PERSIST_FLAGS_APPEND_TO_FILE = 32768;
 100
 101   /**
 102    * Force relevant cookies to be sent with this load even if normally they
 103    * wouldn't be.
 104    */
 105   const unsigned long PERSIST_FLAGS_FORCE_ALLOW_COOKIES = 65536;
 106
 107   /**
 108    * Flags governing how data is fetched and saved from the network.
 109    * It is best to set this value explicitly unless you are prepared
 110    * to accept the default values.
 111    */
 112   attribute unsigned long persistFlags;
 113
 114   /** Persister is ready to save data */
 115   const unsigned long PERSIST_STATE_READY = 1;
 116   /** Persister is saving data */
 117   const unsigned long PERSIST_STATE_SAVING = 2;
 118   /** Persister has finished saving data */
 119   const unsigned long PERSIST_STATE_FINISHED = 3;
 120
 121   /**
 122    * Current state of the persister object.
 123    */
 124   readonly attribute unsigned long currentState;
 125
 126   /**
 127    * Value indicating the success or failure of the persist
 128    * operation.
 129    *
 130    * @return NS_OK Operation was successful or is still ongoing.
 131    * @return NS_BINDING_ABORTED Operation cancelled.
 132    * @return NS_ERROR_FAILURE Non-specific failure.
 133    */
 134   readonly attribute unsigned long result;
 135
 136   /**
 137    * Callback listener for progress notifications. The object that the
 138    * embbedder supplies may also implement nsIInterfaceRequestor and be
 139    * prepared to return nsIAuthPrompt or other interfaces that may be required
 140    * to download data.
 141    *
 142    * @see nsIAuthPrompt
 143    * @see nsIInterfaceRequestor
 144    */
 145   attribute nsIWebProgressListener progressListener;
 146
 147   /**
 148    * Save the specified URI to file.
 149    *
 150    * @param aURI       URI to save to file. Some implementations of this interface
 151    *                   may also support <CODE>nsnull</CODE> to imply the currently
 152    *                   loaded URI.
 153    * @param aCacheKey  An object representing the URI in the cache or
 154    *                   <CODE>nsnull</CODE>.  This can be a necko cache key,
 155    *                   an nsIWebPageDescriptor, or the currentDescriptor of an
 156    *                   nsIWebPageDescriptor.
 157    * @param aReferrer  The referrer URI to pass with an HTTP request or
 158    *                   <CODE>nsnull</CODE>.
 159    * @param aPostData  Post data to pass with an HTTP request or
 160    *                   <CODE>nsnull</CODE>.
 161    * @param aExtraHeaders Additional headers to supply with an HTTP request
 162    *                   or <CODE>nsnull</CODE>.
 163    * @param aFile      Target file. This may be a nsILocalFile object or an
 164    *                   nsIURI object with a file scheme or a scheme that
 165    *                   supports uploading (e.g. ftp).
 166    *
 167    * @see nsILocalFile
 168    * @see nsIURI
 169    * @see nsIInputStream
 170    *
 171    * @return NS_OK Operation has been started.
 172    * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
 173    */
 174   void saveURI(in nsIURI aURI, in nsISupports aCacheKey,
 175       in nsIURI aReferrer, in nsIInputStream aPostData,
 176       in string aExtraHeaders, in nsISupports aFile);
 177
 178   /**
 179    * Save a channel to a file. It must not be opened yet.
 180    * @see saveURI
 181    */
 182   void saveChannel(in nsIChannel aChannel, in nsISupports aFile);
 183
 184   /** Output only the current selection as opposed to the whole document. */
 185   const unsigned long ENCODE_FLAGS_SELECTION_ONLY = 1;
 186   /**
 187    * For plaintext output. Convert html to plaintext that looks like the html.
 188    * Implies wrap (except inside &lt;pre&gt;), since html wraps.
 189    * HTML output: always do prettyprinting, ignoring existing formatting.
 190    */
 191   const unsigned long ENCODE_FLAGS_FORMATTED = 2;
 192   /**
 193    * Output without formatting or wrapping the content. This flag
 194    * may be used to preserve the original formatting as much as possible.
 195    */
 196   const unsigned long ENCODE_FLAGS_RAW = 4;
 197   /** Output only the body section, no HTML tags. */
 198   const unsigned long ENCODE_FLAGS_BODY_ONLY = 8;
 199   /** Wrap even if when not doing formatted output (e.g. for text fields). */
 200   const unsigned long ENCODE_FLAGS_PREFORMATTED = 16;
 201   /** Wrap documents at the specified column. */
 202   const unsigned long ENCODE_FLAGS_WRAP = 32;
 203   /**
 204    * For plaintext output. Output for format flowed (RFC 2646). This is used
 205    * when converting to text for mail sending. This differs just slightly
 206    * but in an important way from normal formatted, and that is that
 207    * lines are space stuffed. This can't (correctly) be done later.
 208    */
 209   const unsigned long ENCODE_FLAGS_FORMAT_FLOWED = 64;
 210   /** Convert links to absolute links where possible. */
 211   const unsigned long ENCODE_FLAGS_ABSOLUTE_LINKS = 128;
 212
 213   /**
 214    * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
 215    * This is a catch-all flag for documents with mixed contents. Beware of
 216    * interoperability issues. See below for other flags which might likely
 217    * do what you want.
 218    */
 219   const unsigned long ENCODE_FLAGS_ENCODE_W3C_ENTITIES = 256;
 220
 221   /**
 222    * Output with carriage return line breaks. May also be combined with
 223    * ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform
 224    * default format is used.
 225    */
 226   const unsigned long ENCODE_FLAGS_CR_LINEBREAKS = 512;
 227   /**
 228    * Output with linefeed line breaks. May also be combined with
 229    * ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform
 230    * default format is used.
 231    */
 232   const unsigned long ENCODE_FLAGS_LF_LINEBREAKS = 1024;
 233   /** For plaintext output. Output the content of noscript elements. */
 234   const unsigned long ENCODE_FLAGS_NOSCRIPT_CONTENT = 2048;
 235   /** For plaintext output. Output the content of noframes elements. */
 236   const unsigned long ENCODE_FLAGS_NOFRAMES_CONTENT = 4096;
 237
 238   /**
 239    * Encode basic entities, e.g. output &nbsp; instead of character code 0xa0.
 240    * The basic set is just &nbsp; &amp; &lt; &gt; &quot; for interoperability
 241    * with older products that don't support &alpha; and friends.
 242    */
 243   const unsigned long ENCODE_FLAGS_ENCODE_BASIC_ENTITIES = 8192;
 244   /**
 245    * Encode Latin1 entities. This includes the basic set and
 246    * accented letters between 128 and 255.
 247    */
 248   const unsigned long ENCODE_FLAGS_ENCODE_LATIN1_ENTITIES = 16384;
 249   /**
 250    * Encode HTML4 entities. This includes the basic set, accented
 251    * letters, greek letters and certain special markup symbols.
 252    */
 253   const unsigned long ENCODE_FLAGS_ENCODE_HTML_ENTITIES = 32768;
 254
 255   /**
 256    * Save the specified DOM document to file and optionally all linked files
 257    * (e.g. images, CSS, JS & subframes). Do not call this method until the
 258    * document has finished loading!
 259    *
 260    * @param aDocument          Document to save to file. Some implementations of
 261    *                           this interface may also support <CODE>nsnull</CODE>
 262    *                           to imply the currently loaded document.
 263    * @param aFile              Target local file. This may be a nsILocalFile object or an
 264    *                           nsIURI object with a file scheme or a scheme that
 265    *                           supports uploading (e.g. ftp).
 266    * @param aDataPath          Path to directory where URIs linked to the document
 267    *                           are saved or nsnull if no linked URIs should be saved.
 268    *                           This may be a nsILocalFile object or an nsIURI object
 269    *                           with a file scheme.
 270    * @param aOutputContentType The desired MIME type format to save the
 271    *                           document and all subdocuments into or nsnull to use
 272    *                           the default behaviour.
 273    * @param aEncodingFlags     Flags to pass to the encoder.
 274    * @param aWrapColumn        For text documents, indicates the desired width to
 275    *                           wrap text at. Parameter is ignored if wrapping is not
 276    *                           specified by the encoding flags.
 277    *
 278    * @see nsILocalFile
 279    * @see nsIURI
 280    *
 281    * @return NS_OK Operation has been started.
 282    * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
 283    */
 284   void saveDocument(in nsIDOMDocument aDocument,
 285      in nsISupports aFile, in nsISupports aDataPath,
 286      in string aOutputContentType, in unsigned long aEncodingFlags,
 287      in unsigned long aWrapColumn);
 288
 289   /**
 290    * Cancels the current operation. The caller is responsible for cleaning up
 291    * partially written files or directories. This has the same effect as calling
 292    * cancel with an argument of NS_BINDING_ABORTED.
 293    */
 294   void cancelSave();
 295 };