/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
 42interface nsIURI;
 43interface nsIInputStream;
 44interface nsIDOMDocument;
 45interface nsIWebProgressListener;
 46interface nsILocalFile;
 47interface 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)]
 53interface 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};