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