1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 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"
8 #include
"nsIContentPolicy.idl"
11 interface nsIInputStream
;
12 interface nsIWebProgressListener
;
15 interface nsILoadContext
;
16 interface nsIPrincipal
;
17 interface nsIReferrerInfo
;
18 interface nsICookieJarSettings
;
21 * Interface for persisting DOM documents and URIs to local or remote storage.
23 [scriptable
, uuid(8cd752a4
-60b1
-42c3
-a819
-65c7a1138a28
)]
24 interface nsIWebBrowserPersist
: nsICancelable
26 /** No special persistence behaviour. */
27 const unsigned long PERSIST_FLAGS_NONE
= 0;
28 /** Use cached data if present (skipping validation), else load from network */
29 const unsigned long PERSIST_FLAGS_FROM_CACHE
= 1;
30 /** Bypass the cached data. */
31 const unsigned long PERSIST_FLAGS_BYPASS_CACHE
= 2;
32 /** Ignore any redirected data (usually adverts). */
33 const unsigned long PERSIST_FLAGS_IGNORE_REDIRECTED_DATA
= 4;
34 /** Ignore IFRAME content (usually adverts). */
35 const unsigned long PERSIST_FLAGS_IGNORE_IFRAMES
= 8;
36 /** Do not run the incoming data through a content converter e.g. to decompress it */
37 const unsigned long PERSIST_FLAGS_NO_CONVERSION
= 16;
38 /** Replace existing files on the disk (use with due diligence!) */
39 const unsigned long PERSIST_FLAGS_REPLACE_EXISTING_FILES
= 32;
40 /** Don't modify or add base tags */
41 const unsigned long PERSIST_FLAGS_NO_BASE_TAG_MODIFICATIONS
= 64;
42 /** Make changes to original dom rather than cloning nodes */
43 const unsigned long PERSIST_FLAGS_FIXUP_ORIGINAL_DOM
= 128;
44 /** Fix links relative to destination location (not origin) */
45 const unsigned long PERSIST_FLAGS_FIXUP_LINKS_TO_DESTINATION
= 256;
46 /** Don't make any adjustments to links */
47 const unsigned long PERSIST_FLAGS_DONT_FIXUP_LINKS
= 512;
48 /** Force serialization of output (one file at a time; not concurrent) */
49 const unsigned long PERSIST_FLAGS_SERIALIZE_OUTPUT
= 1024;
50 /** Don't make any adjustments to filenames */
51 const unsigned long PERSIST_FLAGS_DONT_CHANGE_FILENAMES
= 2048;
52 /** Fail on broken inline links */
53 const unsigned long PERSIST_FLAGS_FAIL_ON_BROKEN_LINKS
= 4096;
55 * Automatically cleanup after a failed or cancelled operation, deleting all
56 * created files and directories. This flag does nothing for failed upload
57 * operations to remote servers.
59 const unsigned long PERSIST_FLAGS_CLEANUP_ON_FAILURE
= 8192;
61 * Let the WebBrowserPersist decide whether the incoming data is encoded
62 * and whether it needs to go through a content converter e.g. to
65 const unsigned long PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION
= 16384;
67 * Append the downloaded data to the target file.
68 * This can only be used when persisting to a local file.
70 const unsigned long PERSIST_FLAGS_APPEND_TO_FILE
= 32768;
73 * Flags governing how data is fetched and saved from the network.
74 * It is best to set this value explicitly unless you are prepared
75 * to accept the default values.
77 attribute
unsigned long persistFlags
;
79 /** Persister is ready to save data */
80 const unsigned long PERSIST_STATE_READY
= 1;
81 /** Persister is saving data */
82 const unsigned long PERSIST_STATE_SAVING
= 2;
83 /** Persister has finished saving data */
84 const unsigned long PERSIST_STATE_FINISHED
= 3;
87 * Current state of the persister object.
89 readonly attribute
unsigned long currentState
;
92 * Value indicating the success or failure of the persist
95 * @throws NS_BINDING_ABORTED Operation cancelled.
96 * @throws NS_ERROR_FAILURE Non-specific failure.
98 readonly attribute nsresult result
;
101 * Callback listener for progress notifications. The object that the
102 * embbedder supplies may also implement nsIInterfaceRequestor and be
103 * prepared to return nsIAuthPrompt or other interfaces that may be required
107 * @see nsIInterfaceRequestor
109 attribute nsIWebProgressListener progressListener
;
112 * Save the specified URI to file.
114 * @param aURI URI to save to file. Some implementations of this interface
115 * may also support <CODE>nullptr</CODE> to imply the currently
117 * @param aTriggeringPrincipal
118 * The triggering principal for the URI we're saving.
119 * @param aCacheKey The necko cache key integer.
120 * @param aReferrerInfo The referrer info for compute and send referrer via
121 * HTTP Referer header.
122 * @param aCookieJarSettings The cookieJarSettings for the HTTP channel which
124 * @param aPostData Post data to pass with an HTTP request or
125 * <CODE>nullptr</CODE>.
126 * @param aExtraHeaders Additional headers to supply with an HTTP request
127 * or <CODE>nullptr</CODE>.
128 * @param aFile Target file. This may be a nsIFile object or an
129 * nsIURI object with a file scheme or a scheme that
130 * supports uploading (e.g. ftp).
131 * @param aContentPolicyType The type of content we're saving.
132 * @param aIsPrivate Treat the save operation as private (ie. with
133 * regards to networking operations and persistence
134 * of intermediate data, etc.)
138 * @see nsIInputStream
140 * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
142 void saveURI
(in nsIURI aURI
,
143 in nsIPrincipal aTriggeringPrincipal
, in unsigned long aCacheKey
,
144 in nsIReferrerInfo aReferrerInfo
,
145 in nsICookieJarSettings aCookieJarSettings
,
146 in nsIInputStream aPostData
,
147 in string aExtraHeaders
, in nsISupports aFile
,
148 in nsContentPolicyType aContentPolicyType
,
149 in boolean aIsPrivate
);
152 * Save a channel to a file. It must not be opened yet.
155 void saveChannel
(in nsIChannel aChannel
, in nsISupports aFile
);
157 /** Output only the current selection as opposed to the whole document. */
158 const unsigned long ENCODE_FLAGS_SELECTION_ONLY
= 1;
160 * For plaintext output. Convert html to plaintext that looks like the html.
161 * Implies wrap (except inside <pre>), since html wraps.
162 * HTML output: always do prettyprinting, ignoring existing formatting.
164 const unsigned long ENCODE_FLAGS_FORMATTED
= 2;
166 * Output without formatting or wrapping the content. This flag
167 * may be used to preserve the original formatting as much as possible.
169 const unsigned long ENCODE_FLAGS_RAW
= 4;
170 /** Output only the body section, no HTML tags. */
171 const unsigned long ENCODE_FLAGS_BODY_ONLY
= 8;
172 /** Wrap even if when not doing formatted output (e.g. for text fields). */
173 const unsigned long ENCODE_FLAGS_PREFORMATTED
= 16;
174 /** Wrap documents at the specified column. */
175 const unsigned long ENCODE_FLAGS_WRAP
= 32;
177 * For plaintext output. Output for format flowed (RFC 2646). This is used
178 * when converting to text for mail sending. This differs just slightly
179 * but in an important way from normal formatted, and that is that
180 * lines are space stuffed. This can't (correctly) be done later.
182 const unsigned long ENCODE_FLAGS_FORMAT_FLOWED
= 64;
183 /** Convert links to absolute links where possible. */
184 const unsigned long ENCODE_FLAGS_ABSOLUTE_LINKS
= 128;
187 * Output with carriage return line breaks. May also be combined with
188 * ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform
189 * default format is used.
191 const unsigned long ENCODE_FLAGS_CR_LINEBREAKS
= 512;
193 * Output with linefeed line breaks. May also be combined with
194 * ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform
195 * default format is used.
197 const unsigned long ENCODE_FLAGS_LF_LINEBREAKS
= 1024;
198 /** For plaintext output. Output the content of noscript elements. */
199 const unsigned long ENCODE_FLAGS_NOSCRIPT_CONTENT
= 2048;
200 /** For plaintext output. Output the content of noframes elements. */
201 const unsigned long ENCODE_FLAGS_NOFRAMES_CONTENT
= 4096;
204 * Encode basic entities, e.g. output instead of character code 0xa0.
205 * The basic set is just & < > " for interoperability
206 * with older products that don't support α and friends.
208 const unsigned long ENCODE_FLAGS_ENCODE_BASIC_ENTITIES
= 8192;
211 * Save the specified DOM document to file and optionally all linked files
212 * (e.g. images, CSS, JS & subframes). Do not call this method until the
213 * document has finished loading!
215 * @param aDocument Document to save to file. Some implementations of
216 * this interface may also support <CODE>nullptr</CODE>
217 * to imply the currently loaded document. Can be an
218 * nsIWebBrowserPersistDocument or Document.
219 * @param aFile Target local file. This may be a nsIFile object or an
220 * nsIURI object with a file scheme or a scheme that
221 * supports uploading (e.g. ftp).
222 * @param aDataPath Path to directory where URIs linked to the document
223 * are saved or nullptr if no linked URIs should be saved.
224 * This may be a nsIFile object or an nsIURI object
225 * with a file scheme.
226 * @param aOutputContentType The desired MIME type format to save the
227 * document and all subdocuments into or nullptr to use
228 * the default behaviour.
229 * @param aEncodingFlags Flags to pass to the encoder.
230 * @param aWrapColumn For text documents, indicates the desired width to
231 * wrap text at. Parameter is ignored if wrapping is not
232 * specified by the encoding flags.
234 * @see nsIWebBrowserPersistDocument
235 * @see WebBrowserPersistable
239 * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
241 void saveDocument
(in nsISupports aDocument
,
242 in nsISupports aFile
, in nsISupports aDataPath
,
243 in string aOutputContentType
, in unsigned long aEncodingFlags
,
244 in unsigned long aWrapColumn
);
247 * Cancels the current operation. The caller is responsible for cleaning up
248 * partially written files or directories. This has the same effect as calling
249 * cancel with an argument of NS_BINDING_ABORTED.
255 * We don't export nsWebBrowserPersist.h as a public header, so we need a place
256 * to put the CID/ContractID. All places uses the WebBrowserPersist include
257 * nsIWebBrowserPersist.h, so we define our contract IDs here for now.
260 // {7E677795-C582-4cd1-9E8D-8271B3474D2A}
261 #define NS_WEBBROWSERPERSIST_CID \
262 { 0x7e677795, 0xc582, 0x4cd1, { 0x9e, 0x8d, 0x82, 0x71, 0xb3, 0x47, 0x4d, 0x2a } }
263 #define NS_WEBBROWSERPERSIST_CONTRACTID \
264 "@mozilla.org/embedding/browser/nsWebBrowserPersist;1"