DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (901e88980751)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276
/* -*- 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 nsIWebProgressListener;
interface nsIFile;
interface nsIChannel;
interface nsILoadContext;
interface nsIPrincipal;

/**
 * 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 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 nsIPrincipal aTriggeringPrincipal,
      in unsigned long 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 nsIPrincipal aTriggeringPrincipal, in unsigned long 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 &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"
%}