/* -*- Mode: C++; tab-width: 2; 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 "nsISupports.idl"

interface nsIOutputStream;
interface nsIDOMNode;

/**
 * The nsIDOMSerializer interface is really a placeholder till the W3C
 * DOM Working Group defines a mechanism for serializing DOM nodes.
 * An instance of this interface can be used to serialize a DOM document
 * or any DOM subtree.
 */

[uuid(9fd4ba15-e67c-4c98-b52c-7715f62c9196)]
interface nsIDOMSerializer : nsISupports
{
  /**
   * The subtree rooted by the specified element is serialized to
   * a string.
   * 
   * @param root The root of the subtree to be serialized. This could
   *             be any node, including a Document.
   * @returns The serialized subtree in the form of a Unicode string
   */
  AString serializeToString(in nsIDOMNode root);

  /**
   * The subtree rooted by the specified element is serialized to
   * a byte stream using the character set specified.
   * @param root The root of the subtree to be serialized. This could
   *             be any node, including a Document.
   * @param stream The byte stream to which the subtree is serialized.
   * @param charset The name of the character set to use for the encoding
   *                to a byte stream.  If this string is empty and root is
   *                a document, the document's character set will be used.
   */
  void serializeToStream(in nsIDOMNode root, in nsIOutputStream stream,
                         in AUTF8String charset);
};

%{ C++
#define NS_XMLSERIALIZER_CID                        \
 { /* a6cf9124-15b3-11d2-932e-00805f8add32 */       \
   0xa6cf9124, 0x15b3, 0x11d2,                      \
  {0x93, 0x2e, 0x00, 0x80, 0x5f, 0x8a, 0xdd, 0x32} }
#define NS_XMLSERIALIZER_CONTRACTID \
"@mozilla.org/xmlextras/xmlserializer;1"
%}