The Tor Browser: embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl@deefc01c0e14 (annotated)

embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl@deefc01c0e14 (annotated)

embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl

Thu, 15 Jan 2015 21:03:48 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 15 Jan 2015 21:03:48 +0100
branch: TOR_BUG_9701
changeset 11: deefc01c0e14
permissions: -rw-r--r--

Integrate friendly tips from Tor colleagues to make (or not) 4.5 alpha 3;
This includes removal of overloaded (but unused) methods, and addition of
a overlooked call to DataStruct::SetData(nsISupports, uint32_t, bool.)

 /* -*- 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(35c1f231-582b-4315-a26c-a1227e3539b4)]
 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 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 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 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 &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;
   /**
    * 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 &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;
   /**
    * 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 <CODE>nullptr</CODE>
    *                           to imply the currently loaded 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 nsIFile
    * @see nsIURI
    *
    * @throws 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();
 };

The Tor Browser / annotate

embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl@deefc01c0e14 (annotated)

embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl