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 * @status UNDER_REVIEW
53 */
54 [scriptable, uuid(dd4e0a6a-210f-419a-ad85-40e8543b9465)]
55 interface nsIWebBrowserPersist : nsICancelable
56 {
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;
85 /**
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.
89 */
90 const unsigned long PERSIST_FLAGS_CLEANUP_ON_FAILURE = 8192;
91 /**
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
94 * decompress it.
95 */
96 const unsigned long PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION = 16384;
97 /**
98 * Append the downloaded data to the target file.
99 * This can only be used when persisting to a local file.
100 */
101 const unsigned long PERSIST_FLAGS_APPEND_TO_FILE = 32768;
102
103
104 /**
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.
108 */
109 attribute unsigned long persistFlags;
110
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;
117
118 /**
119 * Current state of the persister object.
120 */
121 readonly attribute unsigned long currentState;
122
123 /**
124 * Value indicating the success or failure of the persist
125 * operation.
126 *
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.
130 */
131 readonly attribute unsigned long result;
132
133 /**
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
137 * to download data.
138 *
139 * @see nsIAuthPrompt
140 * @see nsIInterfaceRequestor
141 */
142 attribute nsIWebProgressListener progressListener;
143
144 /**
145 * Save the specified URI to file.
146 *
147 * @param aURI URI to save to file. Some implementations of this interface
148 * may also support <CODE>nsnull</CODE> to imply the currently
149 * loaded URI.
150 * @param aCacheKey An object representing the URI in the cache or
151 * <CODE>nsnull</CODE>.
152 * @param aReferrer The referrer URI to pass with an HTTP request or
153 * <CODE>nsnull</CODE>.
154 * @param aPostData Post data to pass with an HTTP request or
155 * <CODE>nsnull</CODE>.
156 * @param aExtraHeaders Additional headers to supply with an HTTP request
157 * or <CODE>nsnull</CODE>.
158 * @param aFile Target file. This may be a nsILocalFile object or an
159 * nsIURI object with a file scheme or a scheme that
160 * supports uploading (e.g. ftp).
161 *
162 * @see nsILocalFile
163 * @see nsIURI
164 * @see nsIInputStream
165 *
166 * @return NS_OK Operation has been started.
167 * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
168 */
169 void saveURI(in nsIURI aURI, in nsISupports aCacheKey,
170 in nsIURI aReferrer, in nsIInputStream aPostData,
171 in string aExtraHeaders, in nsISupports aFile);
172
173 /**
174 * Save a channel to a file. It must not be opened yet.
175 * @see saveURI
176 */
177 void saveChannel(in nsIChannel aChannel, in nsISupports aFile);
178
179 /** Output only the current selection as opposed to the whole document. */
180 const unsigned long ENCODE_FLAGS_SELECTION_ONLY = 1;
181 /**
182 * For plaintext output. Convert html to plaintext that looks like the html.
183 * Implies wrap (except inside <pre>), since html wraps.
184 * HTML output: always do prettyprinting, ignoring existing formatting.
185 */
186 const unsigned long ENCODE_FLAGS_FORMATTED = 2;
187 /**
188 * Output without formatting or wrapping the content. This flag
189 * may be used to preserve the original formatting as much as possible.
190 */
191 const unsigned long ENCODE_FLAGS_RAW = 4;
192 /** Output only the body section, no HTML tags. */
193 const unsigned long ENCODE_FLAGS_BODY_ONLY = 8;
194 /** Wrap even if when not doing formatted output (e.g. for text fields). */
195 const unsigned long ENCODE_FLAGS_PREFORMATTED = 16;
196 /** Wrap documents at the specified column. */
197 const unsigned long ENCODE_FLAGS_WRAP = 32;
198 /**
199 * For plaintext output. Output for format flowed (RFC 2646). This is used
200 * when converting to text for mail sending. This differs just slightly
201 * but in an important way from normal formatted, and that is that
202 * lines are space stuffed. This can't (correctly) be done later.
203 */
204 const unsigned long ENCODE_FLAGS_FORMAT_FLOWED = 64;
205 /** Convert links to absolute links where possible. */
206 const unsigned long ENCODE_FLAGS_ABSOLUTE_LINKS = 128;
207
208 /**
209 * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
210 * This is a catch-all flag for documents with mixed contents. Beware of
211 * interoperability issues. See below for other flags which might likely
212 * do what you want.
213 */
214 const unsigned long ENCODE_FLAGS_ENCODE_W3C_ENTITIES = 256;
215
216 /**
217 * Output with carriage return line breaks. May also be combined with
218 * ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform
219 * default format is used.
220 */
221 const unsigned long ENCODE_FLAGS_CR_LINEBREAKS = 512;
222 /**
223 * Output with linefeed line breaks. May also be combined with
224 * ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform
225 * default format is used.
226 */
227 const unsigned long ENCODE_FLAGS_LF_LINEBREAKS = 1024;
228 /** For plaintext output. Output the content of noscript elements. */
229 const unsigned long ENCODE_FLAGS_NOSCRIPT_CONTENT = 2048;
230 /** For plaintext output. Output the content of noframes elements. */
231 const unsigned long ENCODE_FLAGS_NOFRAMES_CONTENT = 4096;
232
233 /**
234 * Encode basic entities, e.g. output instead of character code 0xa0.
235 * The basic set is just & < > " for interoperability
236 * with older products that don't support α and friends.
237 */
238 const unsigned long ENCODE_FLAGS_ENCODE_BASIC_ENTITIES = 8192;
239 /**
240 * Encode Latin1 entities. This includes the basic set and
241 * accented letters between 128 and 255.
242 */
243 const unsigned long ENCODE_FLAGS_ENCODE_LATIN1_ENTITIES = 16384;
244 /**
245 * Encode HTML4 entities. This includes the basic set, accented
246 * letters, greek letters and certain special markup symbols.
247 */
248 const unsigned long ENCODE_FLAGS_ENCODE_HTML_ENTITIES = 32768;
249
250 /**
251 * Save the specified DOM document to file and optionally all linked files
252 * (e.g. images, CSS, JS & subframes). Do not call this method until the
253 * document has finished loading!
254 *
255 * @param aDocument Document to save to file. Some implementations of
256 * this interface may also support <CODE>nsnull</CODE>
257 * to imply the currently loaded document.
258 * @param aFile Target local file. This may be a nsILocalFile object or an
259 * nsIURI object with a file scheme or a scheme that
260 * supports uploading (e.g. ftp).
261 * @param aDataPath Path to directory where URIs linked to the document
262 * are saved or nsnull if no linked URIs should be saved.
263 * This may be a nsILocalFile object or an nsIURI object
264 * with a file scheme.
265 * @param aOutputContentType The desired MIME type format to save the
266 * document and all subdocuments into or nsnull to use
267 * the default behaviour.
268 * @param aEncodingFlags Flags to pass to the encoder.
269 * @param aWrapColumn For text documents, indicates the desired width to
270 * wrap text at. Parameter is ignored if wrapping is not
271 * specified by the encoding flags.
272 *
273 * @see nsILocalFile
274 * @see nsIURI
275 *
276 * @return NS_OK Operation has been started.
277 * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
278 */
279 void saveDocument(in nsIDOMDocument aDocument,
280 in nsISupports aFile, in nsISupports aDataPath,
281 in string aOutputContentType, in unsigned long aEncodingFlags,
282 in unsigned long aWrapColumn);
283
284 /**
285 * Cancels the current operation. The caller is responsible for cleaning up
286 * partially written files or directories. This has the same effect as calling
287 * cancel with an argument of NS_BINDING_ABORTED.
288 */
289 void cancelSave();
290 };