summaryrefslogtreecommitdiffstats
path: root/dom/webbrowserpersist/nsIWebBrowserPersist.idl
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 14:29:10 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 14:29:10 +0000
commit2aa4a82499d4becd2284cdb482213d541b8804dd (patch)
treeb80bf8bf13c3766139fbacc530efd0dd9d54394c /dom/webbrowserpersist/nsIWebBrowserPersist.idl
parentInitial commit. (diff)
downloadfirefox-upstream.tar.xz
firefox-upstream.zip
Adding upstream version 86.0.1.upstream/86.0.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'dom/webbrowserpersist/nsIWebBrowserPersist.idl')
-rw-r--r--dom/webbrowserpersist/nsIWebBrowserPersist.idl282
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 &lt;pre&gt;), 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 &nbsp; instead of character code 0xa0.
+ * The basic set is just &nbsp; &amp; &lt; &gt; &quot; for interoperability
+ * with older products that don't support &alpha; 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"
+%}