1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
3 * ***** BEGIN LICENSE BLOCK *****
4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
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/
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
16 * The Original Code is the Mozilla browser.
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.
24 * Adam Lock <adamlock@netscape.com>
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.
38 * ***** END LICENSE BLOCK ***** */
40 #include
"nsICancelable.idl"
43 interface nsIInputStream
;
44 interface nsIDOMDocument
;
45 interface nsIWebProgressListener
;
46 interface nsILocalFile
;
50 * Interface for persisting DOM documents and URIs to local or remote storage.
52 * @status UNDER_REVIEW
54 [scriptable
, uuid(dd4e0a6a
-210f
-419a
-ad85
-40e8543b9465
)]
55 interface nsIWebBrowserPersist
: nsICancelable
57 /** No special persistence behaviour. */
58 const unsigned long PERSIST_FLAGS_NONE
= 0;
59 /** Only use cached data (could result in failure if data is not cached). */
60 const unsigned long PERSIST_FLAGS_FROM_CACHE
= 1;
61 /** Bypass the cached data. */
62 const unsigned long PERSIST_FLAGS_BYPASS_CACHE
= 2;
63 /** Ignore any redirected data (usually adverts). */
64 const unsigned long PERSIST_FLAGS_IGNORE_REDIRECTED_DATA
= 4;
65 /** Ignore IFRAME content (usually adverts). */
66 const unsigned long PERSIST_FLAGS_IGNORE_IFRAMES
= 8;
67 /** Do not run the incoming data through a content converter e.g. to decompress it */
68 const unsigned long PERSIST_FLAGS_NO_CONVERSION
= 16;
69 /** Replace existing files on the disk (use with due diligence!) */
70 const unsigned long PERSIST_FLAGS_REPLACE_EXISTING_FILES
= 32;
71 /** Don't modify or add base tags */
72 const unsigned long PERSIST_FLAGS_NO_BASE_TAG_MODIFICATIONS
= 64;
73 /** Make changes to original dom rather than cloning nodes */
74 const unsigned long PERSIST_FLAGS_FIXUP_ORIGINAL_DOM
= 128;
75 /** Fix links relative to destination location (not origin) */
76 const unsigned long PERSIST_FLAGS_FIXUP_LINKS_TO_DESTINATION
= 256;
77 /** Don't make any adjustments to links */
78 const unsigned long PERSIST_FLAGS_DONT_FIXUP_LINKS
= 512;
79 /** Force serialization of output (one file at a time; not concurrent) */
80 const unsigned long PERSIST_FLAGS_SERIALIZE_OUTPUT
= 1024;
81 /** Don't make any adjustments to filenames */
82 const unsigned long PERSIST_FLAGS_DONT_CHANGE_FILENAMES
= 2048;
83 /** Fail on broken inline links */
84 const unsigned long PERSIST_FLAGS_FAIL_ON_BROKEN_LINKS
= 4096;
86 * Automatically cleanup after a failed or cancelled operation, deleting all
87 * created files and directories. This flag does nothing for failed upload
88 * operations to remote servers.
90 const unsigned long PERSIST_FLAGS_CLEANUP_ON_FAILURE
= 8192;
92 * Let the WebBrowserPersist decide whether the incoming data is encoded
93 * and whether it needs to go through a content converter e.g. to
96 const unsigned long PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION
= 16384;
98 * Append the downloaded data to the target file.
99 * This can only be used when persisting to a local file.
101 const unsigned long PERSIST_FLAGS_APPEND_TO_FILE
= 32768;
105 * Flags governing how data is fetched and saved from the network.
106 * It is best to set this value explicitly unless you are prepared
107 * to accept the default values.
109 attribute
unsigned long persistFlags
;
111 /** Persister is ready to save data */
112 const unsigned long PERSIST_STATE_READY
= 1;
113 /** Persister is saving data */
114 const unsigned long PERSIST_STATE_SAVING
= 2;
115 /** Persister has finished saving data */
116 const unsigned long PERSIST_STATE_FINISHED
= 3;
119 * Current state of the persister object.
121 readonly attribute
unsigned long currentState
;
124 * Value indicating the success or failure of the persist
127 * @return NS_OK Operation was successful or is still ongoing.
128 * @return NS_BINDING_ABORTED Operation cancelled.
129 * @return NS_ERROR_FAILURE Non-specific failure.
131 readonly attribute
unsigned long result
;
134 * Callback listener for progress notifications. The object that the
135 * embbedder supplies may also implement nsIInterfaceRequestor and be
136 * prepared to return nsIAuthPrompt or other interfaces that may be required
140 * @see nsIInterfaceRequestor
142 attribute nsIWebProgressListener progressListener
;
145 * Save the specified URI to file.
147 * @param aURI URI to save to file. Some implementations of this interface
148 * may also support <CODE>nsnull</CODE> to imply the currently
150 * @param aCacheKey An object representing the URI in the cache or
151 * <CODE>nsnull</CODE>. This can be a necko cache key,
152 * an nsIWebPageDescriptor, or the currentDescriptor of an
153 * nsIWebPageDescriptor.
154 * @param aReferrer The referrer URI to pass with an HTTP request or
155 * <CODE>nsnull</CODE>.
156 * @param aPostData Post data to pass with an HTTP request or
157 * <CODE>nsnull</CODE>.
158 * @param aExtraHeaders Additional headers to supply with an HTTP request
159 * or <CODE>nsnull</CODE>.
160 * @param aFile Target file. This may be a nsILocalFile object or an
161 * nsIURI object with a file scheme or a scheme that
162 * supports uploading (e.g. ftp).
166 * @see nsIInputStream
168 * @return NS_OK Operation has been started.
169 * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
171 void saveURI
(in nsIURI aURI
, in nsISupports aCacheKey
,
172 in nsIURI aReferrer
, in nsIInputStream aPostData
,
173 in string aExtraHeaders
, in nsISupports aFile
);
176 * Save a channel to a file. It must not be opened yet.
179 void saveChannel
(in nsIChannel aChannel
, in nsISupports aFile
);
181 /** Output only the current selection as opposed to the whole document. */
182 const unsigned long ENCODE_FLAGS_SELECTION_ONLY
= 1;
184 * For plaintext output. Convert html to plaintext that looks like the html.
185 * Implies wrap (except inside <pre>), since html wraps.
186 * HTML output: always do prettyprinting, ignoring existing formatting.
188 const unsigned long ENCODE_FLAGS_FORMATTED
= 2;
190 * Output without formatting or wrapping the content. This flag
191 * may be used to preserve the original formatting as much as possible.
193 const unsigned long ENCODE_FLAGS_RAW
= 4;
194 /** Output only the body section, no HTML tags. */
195 const unsigned long ENCODE_FLAGS_BODY_ONLY
= 8;
196 /** Wrap even if when not doing formatted output (e.g. for text fields). */
197 const unsigned long ENCODE_FLAGS_PREFORMATTED
= 16;
198 /** Wrap documents at the specified column. */
199 const unsigned long ENCODE_FLAGS_WRAP
= 32;
201 * For plaintext output. Output for format flowed (RFC 2646). This is used
202 * when converting to text for mail sending. This differs just slightly
203 * but in an important way from normal formatted, and that is that
204 * lines are space stuffed. This can't (correctly) be done later.
206 const unsigned long ENCODE_FLAGS_FORMAT_FLOWED
= 64;
207 /** Convert links to absolute links where possible. */
208 const unsigned long ENCODE_FLAGS_ABSOLUTE_LINKS
= 128;
211 * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
212 * This is a catch-all flag for documents with mixed contents. Beware of
213 * interoperability issues. See below for other flags which might likely
216 const unsigned long ENCODE_FLAGS_ENCODE_W3C_ENTITIES
= 256;
219 * Output with carriage return line breaks. May also be combined with
220 * ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform
221 * default format is used.
223 const unsigned long ENCODE_FLAGS_CR_LINEBREAKS
= 512;
225 * Output with linefeed line breaks. May also be combined with
226 * ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform
227 * default format is used.
229 const unsigned long ENCODE_FLAGS_LF_LINEBREAKS
= 1024;
230 /** For plaintext output. Output the content of noscript elements. */
231 const unsigned long ENCODE_FLAGS_NOSCRIPT_CONTENT
= 2048;
232 /** For plaintext output. Output the content of noframes elements. */
233 const unsigned long ENCODE_FLAGS_NOFRAMES_CONTENT
= 4096;
236 * Encode basic entities, e.g. output instead of character code 0xa0.
237 * The basic set is just & < > " for interoperability
238 * with older products that don't support α and friends.
240 const unsigned long ENCODE_FLAGS_ENCODE_BASIC_ENTITIES
= 8192;
242 * Encode Latin1 entities. This includes the basic set and
243 * accented letters between 128 and 255.
245 const unsigned long ENCODE_FLAGS_ENCODE_LATIN1_ENTITIES
= 16384;
247 * Encode HTML4 entities. This includes the basic set, accented
248 * letters, greek letters and certain special markup symbols.
250 const unsigned long ENCODE_FLAGS_ENCODE_HTML_ENTITIES
= 32768;
253 * Save the specified DOM document to file and optionally all linked files
254 * (e.g. images, CSS, JS & subframes). Do not call this method until the
255 * document has finished loading!
257 * @param aDocument Document to save to file. Some implementations of
258 * this interface may also support <CODE>nsnull</CODE>
259 * to imply the currently loaded document.
260 * @param aFile Target local file. This may be a nsILocalFile object or an
261 * nsIURI object with a file scheme or a scheme that
262 * supports uploading (e.g. ftp).
263 * @param aDataPath Path to directory where URIs linked to the document
264 * are saved or nsnull if no linked URIs should be saved.
265 * This may be a nsILocalFile object or an nsIURI object
266 * with a file scheme.
267 * @param aOutputContentType The desired MIME type format to save the
268 * document and all subdocuments into or nsnull to use
269 * the default behaviour.
270 * @param aEncodingFlags Flags to pass to the encoder.
271 * @param aWrapColumn For text documents, indicates the desired width to
272 * wrap text at. Parameter is ignored if wrapping is not
273 * specified by the encoding flags.
278 * @return NS_OK Operation has been started.
279 * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
281 void saveDocument
(in nsIDOMDocument aDocument
,
282 in nsISupports aFile
, in nsISupports aDataPath
,
283 in string aOutputContentType
, in unsigned long aEncodingFlags
,
284 in unsigned long aWrapColumn
);
287 * Cancels the current operation. The caller is responsible for cleaning up
288 * partially written files or directories. This has the same effect as calling
289 * cancel with an argument of NS_BINDING_ABORTED.