/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is the Mozilla browser. * * The Initial Developer of the Original Code is * Netscape Communications, Inc. * Portions created by the Initial Developer are Copyright (C) 1999 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Adam Lock * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsICancelable.idl" interface nsIURI; interface nsIInputStream; interface nsIDOMDocument; interface nsIWebProgressListener; interface nsILocalFile; interface nsIChannel; /** * Interface for persisting DOM documents and URIs to local or remote storage. * * @status UNDER_REVIEW */ [scriptable, uuid(dd4e0a6a-210f-419a-ad85-40e8543b9465)] interface nsIWebBrowserPersist : nsICancelable { /** No special persistence behaviour. */ const unsigned long PERSIST_FLAGS_NONE = 0; /** Only use cached data (could result in failure if data is not cached). */ const unsigned long PERSIST_FLAGS_FROM_CACHE = 1; /** Bypass the cached data. */ const unsigned long PERSIST_FLAGS_BYPASS_CACHE = 2; /** Ignore any redirected data (usually adverts). */ const unsigned long PERSIST_FLAGS_IGNORE_REDIRECTED_DATA = 4; /** Ignore IFRAME content (usually adverts). */ const unsigned long PERSIST_FLAGS_IGNORE_IFRAMES = 8; /** Do not run the incoming data through a content converter e.g. to decompress it */ const unsigned long PERSIST_FLAGS_NO_CONVERSION = 16; /** Replace existing files on the disk (use with due diligence!) */ const unsigned long PERSIST_FLAGS_REPLACE_EXISTING_FILES = 32; /** Don't modify or add base tags */ const unsigned long PERSIST_FLAGS_NO_BASE_TAG_MODIFICATIONS = 64; /** Make changes to original dom rather than cloning nodes */ const unsigned long PERSIST_FLAGS_FIXUP_ORIGINAL_DOM = 128; /** Fix links relative to destination location (not origin) */ const unsigned long PERSIST_FLAGS_FIXUP_LINKS_TO_DESTINATION = 256; /** Don't make any adjustments to links */ const unsigned long PERSIST_FLAGS_DONT_FIXUP_LINKS = 512; /** Force serialization of output (one file at a time; not concurrent) */ const unsigned long PERSIST_FLAGS_SERIALIZE_OUTPUT = 1024; /** Don't make any adjustments to filenames */ const unsigned long PERSIST_FLAGS_DONT_CHANGE_FILENAMES = 2048; /** Fail on broken inline links */ const unsigned long PERSIST_FLAGS_FAIL_ON_BROKEN_LINKS = 4096; /** * Automatically cleanup after a failed or cancelled operation, deleting all * created files and directories. This flag does nothing for failed upload * operations to remote servers. */ const unsigned long PERSIST_FLAGS_CLEANUP_ON_FAILURE = 8192; /** * Let the WebBrowserPersist decide whether the incoming data is encoded * and whether it needs to go through a content converter e.g. to * decompress it. */ const unsigned long PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION = 16384; /** * Append the downloaded data to the target file. * This can only be used when persisting to a local file. */ const unsigned long PERSIST_FLAGS_APPEND_TO_FILE = 32768; /** * Force relevant cookies to be sent with this load even if normally they * wouldn't be. */ const unsigned long PERSIST_FLAGS_FORCE_ALLOW_COOKIES = 65536; /** * Flags governing how data is fetched and saved from the network. * It is best to set this value explicitly unless you are prepared * to accept the default values. */ attribute unsigned long persistFlags; /** Persister is ready to save data */ const unsigned long PERSIST_STATE_READY = 1; /** Persister is saving data */ const unsigned long PERSIST_STATE_SAVING = 2; /** Persister has finished saving data */ const unsigned long PERSIST_STATE_FINISHED = 3; /** * Current state of the persister object. */ readonly attribute unsigned long currentState; /** * Value indicating the success or failure of the persist * operation. * * @return NS_OK Operation was successful or is still ongoing. * @return NS_BINDING_ABORTED Operation cancelled. * @return NS_ERROR_FAILURE Non-specific failure. */ readonly attribute unsigned long result; /** * Callback listener for progress notifications. The object that the * embbedder supplies may also implement nsIInterfaceRequestor and be * prepared to return nsIAuthPrompt or other interfaces that may be required * to download data. * * @see nsIAuthPrompt * @see nsIInterfaceRequestor */ attribute nsIWebProgressListener progressListener; /** * Save the specified URI to file. * * @param aURI URI to save to file. Some implementations of this interface * may also support nsnull to imply the currently * loaded URI. * @param aCacheKey An object representing the URI in the cache or * nsnull. This can be a necko cache key, * an nsIWebPageDescriptor, or the currentDescriptor of an * nsIWebPageDescriptor. * @param aReferrer The referrer URI to pass with an HTTP request or * nsnull. * @param aPostData Post data to pass with an HTTP request or * nsnull. * @param aExtraHeaders Additional headers to supply with an HTTP request * or nsnull. * @param aFile Target file. This may be a nsILocalFile object or an * nsIURI object with a file scheme or a scheme that * supports uploading (e.g. ftp). * * @see nsILocalFile * @see nsIURI * @see nsIInputStream * * @return NS_OK Operation has been started. * @return NS_ERROR_INVALID_ARG One or more arguments was invalid. */ void saveURI(in nsIURI aURI, in nsISupports aCacheKey, in nsIURI aReferrer, in nsIInputStream aPostData, in string aExtraHeaders, in nsISupports aFile); /** * Save a channel to a file. It must not be opened yet. * @see saveURI */ void saveChannel(in nsIChannel aChannel, in nsISupports aFile); /** Output only the current selection as opposed to the whole document. */ const unsigned long ENCODE_FLAGS_SELECTION_ONLY = 1; /** * For plaintext output. Convert html to plaintext that looks like the html. * Implies wrap (except inside <pre>), since html wraps. * HTML output: always do prettyprinting, ignoring existing formatting. */ const unsigned long ENCODE_FLAGS_FORMATTED = 2; /** * Output without formatting or wrapping the content. This flag * may be used to preserve the original formatting as much as possible. */ const unsigned long ENCODE_FLAGS_RAW = 4; /** Output only the body section, no HTML tags. */ const unsigned long ENCODE_FLAGS_BODY_ONLY = 8; /** Wrap even if when not doing formatted output (e.g. for text fields). */ const unsigned long ENCODE_FLAGS_PREFORMATTED = 16; /** Wrap documents at the specified column. */ const unsigned long ENCODE_FLAGS_WRAP = 32; /** * For plaintext output. Output for format flowed (RFC 2646). This is used * when converting to text for mail sending. This differs just slightly * but in an important way from normal formatted, and that is that * lines are space stuffed. This can't (correctly) be done later. */ const unsigned long ENCODE_FLAGS_FORMAT_FLOWED = 64; /** Convert links to absolute links where possible. */ const unsigned long ENCODE_FLAGS_ABSOLUTE_LINKS = 128; /** * Attempt to encode entities standardized at W3C (HTML, MathML, etc). * This is a catch-all flag for documents with mixed contents. Beware of * interoperability issues. See below for other flags which might likely * do what you want. */ const unsigned long ENCODE_FLAGS_ENCODE_W3C_ENTITIES = 256; /** * Output with carriage return line breaks. May also be combined with * ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform * default format is used. */ const unsigned long ENCODE_FLAGS_CR_LINEBREAKS = 512; /** * Output with linefeed line breaks. May also be combined with * ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform * default format is used. */ const unsigned long ENCODE_FLAGS_LF_LINEBREAKS = 1024; /** For plaintext output. Output the content of noscript elements. */ const unsigned long ENCODE_FLAGS_NOSCRIPT_CONTENT = 2048; /** For plaintext output. Output the content of noframes elements. */ const unsigned long ENCODE_FLAGS_NOFRAMES_CONTENT = 4096; /** * Encode basic entities, e.g. output   instead of character code 0xa0. * The basic set is just   & < > " for interoperability * with older products that don't support α and friends. */ const unsigned long ENCODE_FLAGS_ENCODE_BASIC_ENTITIES = 8192; /** * Encode Latin1 entities. This includes the basic set and * accented letters between 128 and 255. */ const unsigned long ENCODE_FLAGS_ENCODE_LATIN1_ENTITIES = 16384; /** * Encode HTML4 entities. This includes the basic set, accented * letters, greek letters and certain special markup symbols. */ const unsigned long ENCODE_FLAGS_ENCODE_HTML_ENTITIES = 32768; /** * Save the specified DOM document to file and optionally all linked files * (e.g. images, CSS, JS & subframes). Do not call this method until the * document has finished loading! * * @param aDocument Document to save to file. Some implementations of * this interface may also support nsnull * to imply the currently loaded document. * @param aFile Target local file. This may be a nsILocalFile object or an * nsIURI object with a file scheme or a scheme that * supports uploading (e.g. ftp). * @param aDataPath Path to directory where URIs linked to the document * are saved or nsnull if no linked URIs should be saved. * This may be a nsILocalFile object or an nsIURI object * with a file scheme. * @param aOutputContentType The desired MIME type format to save the * document and all subdocuments into or nsnull to use * the default behaviour. * @param aEncodingFlags Flags to pass to the encoder. * @param aWrapColumn For text documents, indicates the desired width to * wrap text at. Parameter is ignored if wrapping is not * specified by the encoding flags. * * @see nsILocalFile * @see nsIURI * * @return NS_OK Operation has been started. * @return NS_ERROR_INVALID_ARG One or more arguments was invalid. */ void saveDocument(in nsIDOMDocument aDocument, in nsISupports aFile, in nsISupports aDataPath, in string aOutputContentType, in unsigned long aEncodingFlags, in unsigned long aWrapColumn); /** * Cancels the current operation. The caller is responsible for cleaning up * partially written files or directories. This has the same effect as calling * cancel with an argument of NS_BINDING_ABORTED. */ void cancelSave(); };