/* -*- 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"
%}