/* -*- 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 "domstubs.idl"

interface nsIInputStream;
interface nsIOutputStream;
interface nsIScriptGlobalObject;

[ptr] native JSValPtr(jsval);
[ptr] native JSContext(JSContext);

/**
 * Don't use this!  Use JSON.parse and JSON.stringify directly.
 */
[scriptable, uuid(083aebb0-7790-43b2-ae81-9e404e626236)]
interface nsIJSON : nsISupports
{
  /**
   * New users should use JSON.stringify!
   * The encode() method is only present for backward compatibility.
   * encode() is not a conforming JSON stringify implementation!
   */
  [deprecated,implicit_jscontext,optional_argc]
  AString encode([optional] in jsval value);

  /**
   * New users should use JSON.stringify.
   * You may also want to have a look at nsIConverterOutputStream.
   *
   * The encodeToStream() method is only present for backward compatibility.
   * encodeToStream() is not a conforming JSON stringify implementation!
   */
  [deprecated,implicit_jscontext,optional_argc]
  void encodeToStream(in nsIOutputStream stream,
                      in string charset,
                      in boolean writeBOM,
                      [optional] in jsval value);

  /**
   * New users should use JSON.parse!
   * The decode() method is only present for backward compatibility.
   */
  [deprecated,implicit_jscontext]
  jsval decode(in AString str);

  [implicit_jscontext]
  jsval decodeFromStream(in nsIInputStream stream,
                         in long contentLength);

  [noscript] AString  encodeFromJSVal(in JSValPtr value, in JSContext cx);

  // Make sure you GCroot the result of this function before using it.
  [noscript] jsval    decodeToJSVal(in AString str, in JSContext cx);
};