embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl@deefc01c0e14
embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl
Thu, 15 Jan 2015 21:03:48 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 15 Jan 2015 21:03:48 +0100
- branch
- TOR_BUG_9701
- changeset 11
- deefc01c0e14
- permissions
- -rw-r--r--
Integrate friendly tips from Tor colleagues to make (or not) 4.5 alpha 3;
This includes removal of overloaded (but unused) methods, and addition of
a overlooked call to DataStruct::SetData(nsISupports, uint32_t, bool.)
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/. */
7 #include "nsICancelable.idl"
9 interface nsIURI;
10 interface nsIInputStream;
11 interface nsIDOMDocument;
12 interface nsIWebProgressListener;
13 interface nsIFile;
14 interface nsIChannel;
15 interface nsILoadContext;
17 /**
18 * Interface for persisting DOM documents and URIs to local or remote storage.
19 */
20 [scriptable, uuid(35c1f231-582b-4315-a26c-a1227e3539b4)]
21 interface nsIWebBrowserPersist : nsICancelable
22 {
23 /** No special persistence behaviour. */
24 const unsigned long PERSIST_FLAGS_NONE = 0;
25 /** Use cached data if present (skipping validation), else load from network */
26 const unsigned long PERSIST_FLAGS_FROM_CACHE = 1;
27 /** Bypass the cached data. */
28 const unsigned long PERSIST_FLAGS_BYPASS_CACHE = 2;
29 /** Ignore any redirected data (usually adverts). */
30 const unsigned long PERSIST_FLAGS_IGNORE_REDIRECTED_DATA = 4;
31 /** Ignore IFRAME content (usually adverts). */
32 const unsigned long PERSIST_FLAGS_IGNORE_IFRAMES = 8;
33 /** Do not run the incoming data through a content converter e.g. to decompress it */
34 const unsigned long PERSIST_FLAGS_NO_CONVERSION = 16;
35 /** Replace existing files on the disk (use with due diligence!) */
36 const unsigned long PERSIST_FLAGS_REPLACE_EXISTING_FILES = 32;
37 /** Don't modify or add base tags */
38 const unsigned long PERSIST_FLAGS_NO_BASE_TAG_MODIFICATIONS = 64;
39 /** Make changes to original dom rather than cloning nodes */
40 const unsigned long PERSIST_FLAGS_FIXUP_ORIGINAL_DOM = 128;
41 /** Fix links relative to destination location (not origin) */
42 const unsigned long PERSIST_FLAGS_FIXUP_LINKS_TO_DESTINATION = 256;
43 /** Don't make any adjustments to links */
44 const unsigned long PERSIST_FLAGS_DONT_FIXUP_LINKS = 512;
45 /** Force serialization of output (one file at a time; not concurrent) */
46 const unsigned long PERSIST_FLAGS_SERIALIZE_OUTPUT = 1024;
47 /** Don't make any adjustments to filenames */
48 const unsigned long PERSIST_FLAGS_DONT_CHANGE_FILENAMES = 2048;
49 /** Fail on broken inline links */
50 const unsigned long PERSIST_FLAGS_FAIL_ON_BROKEN_LINKS = 4096;
51 /**
52 * Automatically cleanup after a failed or cancelled operation, deleting all
53 * created files and directories. This flag does nothing for failed upload
54 * operations to remote servers.
55 */
56 const unsigned long PERSIST_FLAGS_CLEANUP_ON_FAILURE = 8192;
57 /**
58 * Let the WebBrowserPersist decide whether the incoming data is encoded
59 * and whether it needs to go through a content converter e.g. to
60 * decompress it.
61 */
62 const unsigned long PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION = 16384;
63 /**
64 * Append the downloaded data to the target file.
65 * This can only be used when persisting to a local file.
66 */
67 const unsigned long PERSIST_FLAGS_APPEND_TO_FILE = 32768;
69 /**
70 * Force relevant cookies to be sent with this load even if normally they
71 * wouldn't be.
72 */
73 const unsigned long PERSIST_FLAGS_FORCE_ALLOW_COOKIES = 65536;
75 /**
76 * Flags governing how data is fetched and saved from the network.
77 * It is best to set this value explicitly unless you are prepared
78 * to accept the default values.
79 */
80 attribute unsigned long persistFlags;
82 /** Persister is ready to save data */
83 const unsigned long PERSIST_STATE_READY = 1;
84 /** Persister is saving data */
85 const unsigned long PERSIST_STATE_SAVING = 2;
86 /** Persister has finished saving data */
87 const unsigned long PERSIST_STATE_FINISHED = 3;
89 /**
90 * Current state of the persister object.
91 */
92 readonly attribute unsigned long currentState;
94 /**
95 * Value indicating the success or failure of the persist
96 * operation.
97 *
98 * @throws NS_BINDING_ABORTED Operation cancelled.
99 * @throws NS_ERROR_FAILURE Non-specific failure.
100 */
101 readonly attribute nsresult result;
103 /**
104 * Callback listener for progress notifications. The object that the
105 * embbedder supplies may also implement nsIInterfaceRequestor and be
106 * prepared to return nsIAuthPrompt or other interfaces that may be required
107 * to download data.
108 *
109 * @see nsIAuthPrompt
110 * @see nsIInterfaceRequestor
111 */
112 attribute nsIWebProgressListener progressListener;
114 /**
115 * Save the specified URI to file.
116 *
117 * @param aURI URI to save to file. Some implementations of this interface
118 * may also support <CODE>nullptr</CODE> to imply the currently
119 * loaded URI.
120 * @param aCacheKey An object representing the URI in the cache or
121 * <CODE>nullptr</CODE>. This can be a necko cache key,
122 * an nsIWebPageDescriptor, or the currentDescriptor of an
123 * nsIWebPageDescriptor.
124 * @param aReferrer The referrer URI to pass with an HTTP request or
125 * <CODE>nullptr</CODE>.
126 * @param aPostData Post data to pass with an HTTP request or
127 * <CODE>nullptr</CODE>.
128 * @param aExtraHeaders Additional headers to supply with an HTTP request
129 * or <CODE>nullptr</CODE>.
130 * @param aFile Target file. This may be a nsIFile object or an
131 * nsIURI object with a file scheme or a scheme that
132 * supports uploading (e.g. ftp).
133 * @param aPrivacyContext A context from which the privacy status of this
134 * save operation can be determined. Must only be null
135 * in situations in which no such context is available
136 * (eg. the operation has no logical association with any
137 * window or document)
138 *
139 * @see nsIFile
140 * @see nsIURI
141 * @see nsIInputStream
142 *
143 * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
144 */
145 void saveURI(in nsIURI aURI, in nsISupports aCacheKey,
146 in nsIURI aReferrer, in nsIInputStream aPostData,
147 in string aExtraHeaders, in nsISupports aFile,
148 in nsILoadContext aPrivacyContext);
150 /**
151 * @param aIsPrivate Treat the save operation as private (ie. with
152 * regards to networking operations and persistence
153 * of intermediate data, etc.)
154 * @see saveURI for all other parameter descriptions
155 */
156 void savePrivacyAwareURI(in nsIURI aURI, in nsISupports aCacheKey,
157 in nsIURI aReferrer, in nsIInputStream aPostData,
158 in string aExtraHeaders, in nsISupports aFile,
159 in boolean aIsPrivate);
161 /**
162 * Save a channel to a file. It must not be opened yet.
163 * @see saveURI
164 */
165 void saveChannel(in nsIChannel aChannel, in nsISupports aFile);
167 /** Output only the current selection as opposed to the whole document. */
168 const unsigned long ENCODE_FLAGS_SELECTION_ONLY = 1;
169 /**
170 * For plaintext output. Convert html to plaintext that looks like the html.
171 * Implies wrap (except inside <pre>), since html wraps.
172 * HTML output: always do prettyprinting, ignoring existing formatting.
173 */
174 const unsigned long ENCODE_FLAGS_FORMATTED = 2;
175 /**
176 * Output without formatting or wrapping the content. This flag
177 * may be used to preserve the original formatting as much as possible.
178 */
179 const unsigned long ENCODE_FLAGS_RAW = 4;
180 /** Output only the body section, no HTML tags. */
181 const unsigned long ENCODE_FLAGS_BODY_ONLY = 8;
182 /** Wrap even if when not doing formatted output (e.g. for text fields). */
183 const unsigned long ENCODE_FLAGS_PREFORMATTED = 16;
184 /** Wrap documents at the specified column. */
185 const unsigned long ENCODE_FLAGS_WRAP = 32;
186 /**
187 * For plaintext output. Output for format flowed (RFC 2646). This is used
188 * when converting to text for mail sending. This differs just slightly
189 * but in an important way from normal formatted, and that is that
190 * lines are space stuffed. This can't (correctly) be done later.
191 */
192 const unsigned long ENCODE_FLAGS_FORMAT_FLOWED = 64;
193 /** Convert links to absolute links where possible. */
194 const unsigned long ENCODE_FLAGS_ABSOLUTE_LINKS = 128;
196 /**
197 * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
198 * This is a catch-all flag for documents with mixed contents. Beware of
199 * interoperability issues. See below for other flags which might likely
200 * do what you want.
201 */
202 const unsigned long ENCODE_FLAGS_ENCODE_W3C_ENTITIES = 256;
204 /**
205 * Output with carriage return line breaks. May also be combined with
206 * ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform
207 * default format is used.
208 */
209 const unsigned long ENCODE_FLAGS_CR_LINEBREAKS = 512;
210 /**
211 * Output with linefeed line breaks. May also be combined with
212 * ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform
213 * default format is used.
214 */
215 const unsigned long ENCODE_FLAGS_LF_LINEBREAKS = 1024;
216 /** For plaintext output. Output the content of noscript elements. */
217 const unsigned long ENCODE_FLAGS_NOSCRIPT_CONTENT = 2048;
218 /** For plaintext output. Output the content of noframes elements. */
219 const unsigned long ENCODE_FLAGS_NOFRAMES_CONTENT = 4096;
221 /**
222 * Encode basic entities, e.g. output instead of character code 0xa0.
223 * The basic set is just & < > " for interoperability
224 * with older products that don't support α and friends.
225 */
226 const unsigned long ENCODE_FLAGS_ENCODE_BASIC_ENTITIES = 8192;
227 /**
228 * Encode Latin1 entities. This includes the basic set and
229 * accented letters between 128 and 255.
230 */
231 const unsigned long ENCODE_FLAGS_ENCODE_LATIN1_ENTITIES = 16384;
232 /**
233 * Encode HTML4 entities. This includes the basic set, accented
234 * letters, greek letters and certain special markup symbols.
235 */
236 const unsigned long ENCODE_FLAGS_ENCODE_HTML_ENTITIES = 32768;
238 /**
239 * Save the specified DOM document to file and optionally all linked files
240 * (e.g. images, CSS, JS & subframes). Do not call this method until the
241 * document has finished loading!
242 *
243 * @param aDocument Document to save to file. Some implementations of
244 * this interface may also support <CODE>nullptr</CODE>
245 * to imply the currently loaded document.
246 * @param aFile Target local file. This may be a nsIFile object or an
247 * nsIURI object with a file scheme or a scheme that
248 * supports uploading (e.g. ftp).
249 * @param aDataPath Path to directory where URIs linked to the document
250 * are saved or nullptr if no linked URIs should be saved.
251 * This may be a nsIFile object or an nsIURI object
252 * with a file scheme.
253 * @param aOutputContentType The desired MIME type format to save the
254 * document and all subdocuments into or nullptr to use
255 * the default behaviour.
256 * @param aEncodingFlags Flags to pass to the encoder.
257 * @param aWrapColumn For text documents, indicates the desired width to
258 * wrap text at. Parameter is ignored if wrapping is not
259 * specified by the encoding flags.
260 *
261 * @see nsIFile
262 * @see nsIURI
263 *
264 * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
265 */
266 void saveDocument(in nsIDOMDocument aDocument,
267 in nsISupports aFile, in nsISupports aDataPath,
268 in string aOutputContentType, in unsigned long aEncodingFlags,
269 in unsigned long aWrapColumn);
271 /**
272 * Cancels the current operation. The caller is responsible for cleaning up
273 * partially written files or directories. This has the same effect as calling
274 * cancel with an argument of NS_BINDING_ABORTED.
275 */
276 void cancelSave();
277 };
