/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is the Mozilla browser.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications, Inc.  Portions created by Netscape are
 * Copyright (C) 1999, Mozilla.  All Rights Reserved.
 * 
 * Contributor(s):
 *   Adam Lock <adamlock@netscape.com>
 */

#include "nsISupports.idl"

interface nsIURI;
interface nsIInputStream;
interface nsIDOMDocument;
interface nsIWebProgressListener;
interface nsILocalFile;

/**
 * @status UNDER_REVIEW
 */

/**
 * Interface for persisting DOM documents and URIs to local storage.
 */
[scriptable, uuid(814ba433-a816-4785-9f95-ad3ba0a43dab)]
interface nsIWebBrowserPersist : nsISupports
{
  /** No special persistence behaviour. */
  const unsigned long PERSIST_FLAGS_NONE = 0;
  /** Only use cached data (could result in failure if data is not cached). */
  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;

  /** Flags governing how data is fetched from the network. */
  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.
   *
   * @return NS_OK Operation was successful or is still ongoing.
   * @return NS_BINDING_ABORTED Operation cancelled.
   * @return NS_ERROR_FAILURE Non-specific failure.
   */
  readonly attribute unsigned long 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>nsnull</CODE> to imply the currently
   *                   loaded URI.
   * @param aPostData  Data to pass with in an HTTP request or nsnull.
   * @param aFile      Target local file. This may be a nsILocalFile object or an
   *                   nsIURI object with a file scheme.
   *
   * @see nsILocalFile
   * @see nsIURI
   *
   * @return NS_OK Operation has been started.
   * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
   */
  void saveURI(in nsIURI aURI, in nsIInputStream aPostData, 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;
  /** Encode entities, e.g. output &nbsp; instead of character code 0xa0. */
  const unsigned long ENCODE_FLAGS_ENCODE_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;

  /**
   * 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>nsnull</CODE>
   *                           to imply the currently loaded document.
   * @param aFile              Target local file. This may be a nsILocalFile object or an
   *                           nsIURI object with a file scheme.
   * @param aDataPath          Path to directory where URIs linked to the document
   *                           are saved or nsnull if no linked URIs should be saved.
   *                           This may be a nsILocalFile 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 nsnull 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 nsILocalFile
   * @see nsIURI
   *
   * @return NS_OK Operation has been started.
   * @return 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.
   */
  void cancelSave();
};
