diff options
Diffstat (limited to 'dom/webbrowserpersist/nsIWebBrowserPersist.idl')
| -rw-r--r-- | dom/webbrowserpersist/nsIWebBrowserPersist.idl | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/dom/webbrowserpersist/nsIWebBrowserPersist.idl b/dom/webbrowserpersist/nsIWebBrowserPersist.idl new file mode 100644 index 0000000000..0cfd021142 --- /dev/null +++ b/dom/webbrowserpersist/nsIWebBrowserPersist.idl @@ -0,0 +1,282 @@ +/* -*- 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" +#include "nsIContentPolicy.idl" + +interface nsIURI; +interface nsIInputStream; +interface nsIWebProgressListener; +interface nsIFile; +interface nsIChannel; +interface nsILoadContext; +interface nsIPrincipal; +interface nsIReferrerInfo; +interface nsICookieJarSettings; + +/** + * 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; + + /** + * 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 aTriggeringPrincipal + * The triggering principal for the URI we're saving. + * @param aCacheKey The necko cache key integer. + * @param aReferrerInfo The referrer info for compute and send referrer via + * HTTP Referer header. + * @param aCookieJarSettings The cookieJarSettings for the HTTP channel which + * is saving the URI. + * @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 aContentPolicyType The type of content we're saving. + * @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 nsIPrincipal aTriggeringPrincipal, + in unsigned long aCacheKey, + in nsIReferrerInfo aReferrerInfo, + in nsICookieJarSettings aCookieJarSettings, + in nsIInputStream aPostData, + in string aExtraHeaders, in nsISupports aFile, + in nsContentPolicyType aContentPolicyType, + 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 nsIPrincipal aTriggeringPrincipal, in unsigned long aCacheKey, + in nsIReferrerInfo aReferrerInfo, + in nsICookieJarSettings aCookieJarSettings, + in nsIInputStream aPostData, + in string aExtraHeaders, in nsISupports aFile, + in nsContentPolicyType aContentPolicyType, + 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 Document. + * @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 WebBrowserPersistable + * @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(); +}; + +/** + * We don't export nsWebBrowserPersist.h as a public header, so we need a place + * to put the CID/ContractID. All places uses the WebBrowserPersist include + * nsIWebBrowserPersist.h, so we define our contract IDs here for now. + */ +%{ C++ +// {7E677795-C582-4cd1-9E8D-8271B3474D2A} +#define NS_WEBBROWSERPERSIST_CID \ + { 0x7e677795, 0xc582, 0x4cd1, { 0x9e, 0x8d, 0x82, 0x71, 0xb3, 0x47, 0x4d, 0x2a } } +#define NS_WEBBROWSERPERSIST_CONTRACTID \ + "@mozilla.org/embedding/browser/nsWebBrowserPersist;1" +%} |