1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,277 @@
1.4 +/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsICancelable.idl"
1.11 +
1.12 +interface nsIURI;
1.13 +interface nsIInputStream;
1.14 +interface nsIDOMDocument;
1.15 +interface nsIWebProgressListener;
1.16 +interface nsIFile;
1.17 +interface nsIChannel;
1.18 +interface nsILoadContext;
1.19 +
1.20 +/**
1.21 + * Interface for persisting DOM documents and URIs to local or remote storage.
1.22 + */
1.23 +[scriptable, uuid(35c1f231-582b-4315-a26c-a1227e3539b4)]
1.24 +interface nsIWebBrowserPersist : nsICancelable
1.25 +{
1.26 + /** No special persistence behaviour. */
1.27 + const unsigned long PERSIST_FLAGS_NONE = 0;
1.28 + /** Use cached data if present (skipping validation), else load from network */
1.29 + const unsigned long PERSIST_FLAGS_FROM_CACHE = 1;
1.30 + /** Bypass the cached data. */
1.31 + const unsigned long PERSIST_FLAGS_BYPASS_CACHE = 2;
1.32 + /** Ignore any redirected data (usually adverts). */
1.33 + const unsigned long PERSIST_FLAGS_IGNORE_REDIRECTED_DATA = 4;
1.34 + /** Ignore IFRAME content (usually adverts). */
1.35 + const unsigned long PERSIST_FLAGS_IGNORE_IFRAMES = 8;
1.36 + /** Do not run the incoming data through a content converter e.g. to decompress it */
1.37 + const unsigned long PERSIST_FLAGS_NO_CONVERSION = 16;
1.38 + /** Replace existing files on the disk (use with due diligence!) */
1.39 + const unsigned long PERSIST_FLAGS_REPLACE_EXISTING_FILES = 32;
1.40 + /** Don't modify or add base tags */
1.41 + const unsigned long PERSIST_FLAGS_NO_BASE_TAG_MODIFICATIONS = 64;
1.42 + /** Make changes to original dom rather than cloning nodes */
1.43 + const unsigned long PERSIST_FLAGS_FIXUP_ORIGINAL_DOM = 128;
1.44 + /** Fix links relative to destination location (not origin) */
1.45 + const unsigned long PERSIST_FLAGS_FIXUP_LINKS_TO_DESTINATION = 256;
1.46 + /** Don't make any adjustments to links */
1.47 + const unsigned long PERSIST_FLAGS_DONT_FIXUP_LINKS = 512;
1.48 + /** Force serialization of output (one file at a time; not concurrent) */
1.49 + const unsigned long PERSIST_FLAGS_SERIALIZE_OUTPUT = 1024;
1.50 + /** Don't make any adjustments to filenames */
1.51 + const unsigned long PERSIST_FLAGS_DONT_CHANGE_FILENAMES = 2048;
1.52 + /** Fail on broken inline links */
1.53 + const unsigned long PERSIST_FLAGS_FAIL_ON_BROKEN_LINKS = 4096;
1.54 + /**
1.55 + * Automatically cleanup after a failed or cancelled operation, deleting all
1.56 + * created files and directories. This flag does nothing for failed upload
1.57 + * operations to remote servers.
1.58 + */
1.59 + const unsigned long PERSIST_FLAGS_CLEANUP_ON_FAILURE = 8192;
1.60 + /**
1.61 + * Let the WebBrowserPersist decide whether the incoming data is encoded
1.62 + * and whether it needs to go through a content converter e.g. to
1.63 + * decompress it.
1.64 + */
1.65 + const unsigned long PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION = 16384;
1.66 + /**
1.67 + * Append the downloaded data to the target file.
1.68 + * This can only be used when persisting to a local file.
1.69 + */
1.70 + const unsigned long PERSIST_FLAGS_APPEND_TO_FILE = 32768;
1.71 +
1.72 + /**
1.73 + * Force relevant cookies to be sent with this load even if normally they
1.74 + * wouldn't be.
1.75 + */
1.76 + const unsigned long PERSIST_FLAGS_FORCE_ALLOW_COOKIES = 65536;
1.77 +
1.78 + /**
1.79 + * Flags governing how data is fetched and saved from the network.
1.80 + * It is best to set this value explicitly unless you are prepared
1.81 + * to accept the default values.
1.82 + */
1.83 + attribute unsigned long persistFlags;
1.84 +
1.85 + /** Persister is ready to save data */
1.86 + const unsigned long PERSIST_STATE_READY = 1;
1.87 + /** Persister is saving data */
1.88 + const unsigned long PERSIST_STATE_SAVING = 2;
1.89 + /** Persister has finished saving data */
1.90 + const unsigned long PERSIST_STATE_FINISHED = 3;
1.91 +
1.92 + /**
1.93 + * Current state of the persister object.
1.94 + */
1.95 + readonly attribute unsigned long currentState;
1.96 +
1.97 + /**
1.98 + * Value indicating the success or failure of the persist
1.99 + * operation.
1.100 + *
1.101 + * @throws NS_BINDING_ABORTED Operation cancelled.
1.102 + * @throws NS_ERROR_FAILURE Non-specific failure.
1.103 + */
1.104 + readonly attribute nsresult result;
1.105 +
1.106 + /**
1.107 + * Callback listener for progress notifications. The object that the
1.108 + * embbedder supplies may also implement nsIInterfaceRequestor and be
1.109 + * prepared to return nsIAuthPrompt or other interfaces that may be required
1.110 + * to download data.
1.111 + *
1.112 + * @see nsIAuthPrompt
1.113 + * @see nsIInterfaceRequestor
1.114 + */
1.115 + attribute nsIWebProgressListener progressListener;
1.116 +
1.117 + /**
1.118 + * Save the specified URI to file.
1.119 + *
1.120 + * @param aURI URI to save to file. Some implementations of this interface
1.121 + * may also support <CODE>nullptr</CODE> to imply the currently
1.122 + * loaded URI.
1.123 + * @param aCacheKey An object representing the URI in the cache or
1.124 + * <CODE>nullptr</CODE>. This can be a necko cache key,
1.125 + * an nsIWebPageDescriptor, or the currentDescriptor of an
1.126 + * nsIWebPageDescriptor.
1.127 + * @param aReferrer The referrer URI to pass with an HTTP request or
1.128 + * <CODE>nullptr</CODE>.
1.129 + * @param aPostData Post data to pass with an HTTP request or
1.130 + * <CODE>nullptr</CODE>.
1.131 + * @param aExtraHeaders Additional headers to supply with an HTTP request
1.132 + * or <CODE>nullptr</CODE>.
1.133 + * @param aFile Target file. This may be a nsIFile object or an
1.134 + * nsIURI object with a file scheme or a scheme that
1.135 + * supports uploading (e.g. ftp).
1.136 + * @param aPrivacyContext A context from which the privacy status of this
1.137 + * save operation can be determined. Must only be null
1.138 + * in situations in which no such context is available
1.139 + * (eg. the operation has no logical association with any
1.140 + * window or document)
1.141 + *
1.142 + * @see nsIFile
1.143 + * @see nsIURI
1.144 + * @see nsIInputStream
1.145 + *
1.146 + * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
1.147 + */
1.148 + void saveURI(in nsIURI aURI, in nsISupports aCacheKey,
1.149 + in nsIURI aReferrer, in nsIInputStream aPostData,
1.150 + in string aExtraHeaders, in nsISupports aFile,
1.151 + in nsILoadContext aPrivacyContext);
1.152 +
1.153 + /**
1.154 + * @param aIsPrivate Treat the save operation as private (ie. with
1.155 + * regards to networking operations and persistence
1.156 + * of intermediate data, etc.)
1.157 + * @see saveURI for all other parameter descriptions
1.158 + */
1.159 + void savePrivacyAwareURI(in nsIURI aURI, in nsISupports aCacheKey,
1.160 + in nsIURI aReferrer, in nsIInputStream aPostData,
1.161 + in string aExtraHeaders, in nsISupports aFile,
1.162 + in boolean aIsPrivate);
1.163 +
1.164 + /**
1.165 + * Save a channel to a file. It must not be opened yet.
1.166 + * @see saveURI
1.167 + */
1.168 + void saveChannel(in nsIChannel aChannel, in nsISupports aFile);
1.169 +
1.170 + /** Output only the current selection as opposed to the whole document. */
1.171 + const unsigned long ENCODE_FLAGS_SELECTION_ONLY = 1;
1.172 + /**
1.173 + * For plaintext output. Convert html to plaintext that looks like the html.
1.174 + * Implies wrap (except inside <pre>), since html wraps.
1.175 + * HTML output: always do prettyprinting, ignoring existing formatting.
1.176 + */
1.177 + const unsigned long ENCODE_FLAGS_FORMATTED = 2;
1.178 + /**
1.179 + * Output without formatting or wrapping the content. This flag
1.180 + * may be used to preserve the original formatting as much as possible.
1.181 + */
1.182 + const unsigned long ENCODE_FLAGS_RAW = 4;
1.183 + /** Output only the body section, no HTML tags. */
1.184 + const unsigned long ENCODE_FLAGS_BODY_ONLY = 8;
1.185 + /** Wrap even if when not doing formatted output (e.g. for text fields). */
1.186 + const unsigned long ENCODE_FLAGS_PREFORMATTED = 16;
1.187 + /** Wrap documents at the specified column. */
1.188 + const unsigned long ENCODE_FLAGS_WRAP = 32;
1.189 + /**
1.190 + * For plaintext output. Output for format flowed (RFC 2646). This is used
1.191 + * when converting to text for mail sending. This differs just slightly
1.192 + * but in an important way from normal formatted, and that is that
1.193 + * lines are space stuffed. This can't (correctly) be done later.
1.194 + */
1.195 + const unsigned long ENCODE_FLAGS_FORMAT_FLOWED = 64;
1.196 + /** Convert links to absolute links where possible. */
1.197 + const unsigned long ENCODE_FLAGS_ABSOLUTE_LINKS = 128;
1.198 +
1.199 + /**
1.200 + * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
1.201 + * This is a catch-all flag for documents with mixed contents. Beware of
1.202 + * interoperability issues. See below for other flags which might likely
1.203 + * do what you want.
1.204 + */
1.205 + const unsigned long ENCODE_FLAGS_ENCODE_W3C_ENTITIES = 256;
1.206 +
1.207 + /**
1.208 + * Output with carriage return line breaks. May also be combined with
1.209 + * ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform
1.210 + * default format is used.
1.211 + */
1.212 + const unsigned long ENCODE_FLAGS_CR_LINEBREAKS = 512;
1.213 + /**
1.214 + * Output with linefeed line breaks. May also be combined with
1.215 + * ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform
1.216 + * default format is used.
1.217 + */
1.218 + const unsigned long ENCODE_FLAGS_LF_LINEBREAKS = 1024;
1.219 + /** For plaintext output. Output the content of noscript elements. */
1.220 + const unsigned long ENCODE_FLAGS_NOSCRIPT_CONTENT = 2048;
1.221 + /** For plaintext output. Output the content of noframes elements. */
1.222 + const unsigned long ENCODE_FLAGS_NOFRAMES_CONTENT = 4096;
1.223 +
1.224 + /**
1.225 + * Encode basic entities, e.g. output instead of character code 0xa0.
1.226 + * The basic set is just & < > " for interoperability
1.227 + * with older products that don't support α and friends.
1.228 + */
1.229 + const unsigned long ENCODE_FLAGS_ENCODE_BASIC_ENTITIES = 8192;
1.230 + /**
1.231 + * Encode Latin1 entities. This includes the basic set and
1.232 + * accented letters between 128 and 255.
1.233 + */
1.234 + const unsigned long ENCODE_FLAGS_ENCODE_LATIN1_ENTITIES = 16384;
1.235 + /**
1.236 + * Encode HTML4 entities. This includes the basic set, accented
1.237 + * letters, greek letters and certain special markup symbols.
1.238 + */
1.239 + const unsigned long ENCODE_FLAGS_ENCODE_HTML_ENTITIES = 32768;
1.240 +
1.241 + /**
1.242 + * Save the specified DOM document to file and optionally all linked files
1.243 + * (e.g. images, CSS, JS & subframes). Do not call this method until the
1.244 + * document has finished loading!
1.245 + *
1.246 + * @param aDocument Document to save to file. Some implementations of
1.247 + * this interface may also support <CODE>nullptr</CODE>
1.248 + * to imply the currently loaded document.
1.249 + * @param aFile Target local file. This may be a nsIFile object or an
1.250 + * nsIURI object with a file scheme or a scheme that
1.251 + * supports uploading (e.g. ftp).
1.252 + * @param aDataPath Path to directory where URIs linked to the document
1.253 + * are saved or nullptr if no linked URIs should be saved.
1.254 + * This may be a nsIFile object or an nsIURI object
1.255 + * with a file scheme.
1.256 + * @param aOutputContentType The desired MIME type format to save the
1.257 + * document and all subdocuments into or nullptr to use
1.258 + * the default behaviour.
1.259 + * @param aEncodingFlags Flags to pass to the encoder.
1.260 + * @param aWrapColumn For text documents, indicates the desired width to
1.261 + * wrap text at. Parameter is ignored if wrapping is not
1.262 + * specified by the encoding flags.
1.263 + *
1.264 + * @see nsIFile
1.265 + * @see nsIURI
1.266 + *
1.267 + * @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
1.268 + */
1.269 + void saveDocument(in nsIDOMDocument aDocument,
1.270 + in nsISupports aFile, in nsISupports aDataPath,
1.271 + in string aOutputContentType, in unsigned long aEncodingFlags,
1.272 + in unsigned long aWrapColumn);
1.273 +
1.274 + /**
1.275 + * Cancels the current operation. The caller is responsible for cleaning up
1.276 + * partially written files or directories. This has the same effect as calling
1.277 + * cancel with an argument of NS_BINDING_ABORTED.
1.278 + */
1.279 + void cancelSave();
1.280 +};
