/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsICancelable.idl"
interface nsIURI;
interface nsIInputStream;
interface nsIDOMDocument;
interface nsIWebProgressListener;
interface nsIFile;
interface nsIChannel;
interface nsILoadContext;
/**
* Interface for persisting DOM documents and URIs to local or remote storage.
*/
[scriptable, uuid(8cd752a4-60b1-42c3-a819-65c7a1138a28)]
interface nsIWebBrowserPersist : nsICancelable
{
/** No special persistence behaviour. */
const unsigned long PERSIST_FLAGS_NONE = 0;
/** Use cached data if present (skipping validation), else load from network */
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.
*
* @throws NS_BINDING_ABORTED Operation cancelled.
* @throws NS_ERROR_FAILURE Non-specific failure.
*/
readonly attribute nsresult 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 <CODE>nullptr</CODE> to imply the currently
* loaded URI.
* @param aCacheKey An object representing the URI in the cache or
* <CODE>nullptr</CODE>. 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
* <CODE>nullptr</CODE>.
* @param aReferrerPolicy The referrer policy for when and what to send via
* HTTP Referer header. Ignored if aReferrer is
* <CODE>nullptr</CODE>. Taken from REFERRER_POLICY
* constants in nsIHttpChannel.
* @param aPostData Post data to pass with an HTTP request or
* <CODE>nullptr</CODE>.
* @param aExtraHeaders Additional headers to supply with an HTTP request
* or <CODE>nullptr</CODE>.
* @param aFile Target file. This may be a nsIFile object or an
* nsIURI object with a file scheme or a scheme that
* supports uploading (e.g. ftp).
* @param aPrivacyContext A context from which the privacy status of this
* save operation can be determined. Must only be null
* in situations in which no such context is available
* (eg. the operation has no logical association with any
* window or document)
*
* @see nsIFile
* @see nsIURI
* @see nsIInputStream
*
* @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
*/
void saveURI(in nsIURI aURI, in nsISupports aCacheKey,
in nsIURI aReferrer, in unsigned long aReferrerPolicy,
in nsIInputStream aPostData,
in string aExtraHeaders, in nsISupports aFile,
in nsILoadContext aPrivacyContext);
/**
* @param aIsPrivate Treat the save operation as private (ie. with
* regards to networking operations and persistence
* of intermediate data, etc.)
* @see saveURI for all other parameter descriptions
*/
void savePrivacyAwareURI(in nsIURI aURI, in nsISupports aCacheKey,
in nsIURI aReferrer, in unsigned long aReferrerPolicy,
in nsIInputStream aPostData,
in string aExtraHeaders, in nsISupports aFile,
in boolean aIsPrivate);
/**
* 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;
/**
* 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;
/**
* 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 <CODE>nullptr</CODE>
* to imply the currently loaded document. Can be an
* nsIWebBrowserPersistDocument or nsIDOMDocument.
* @param aFile Target local file. This may be a nsIFile 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 nullptr if no linked URIs should be saved.
* This may be a nsIFile 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 nullptr 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 nsIWebBrowserPersistDocument
* @see nsIWebBrowserPersistable
* @see nsIFile
* @see nsIURI
*
* @throws NS_ERROR_INVALID_ARG One or more arguments was invalid.
*/
void saveDocument(in nsISupports 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();
};