nsIJSON

This interface provides a convenient way to encode and decode JSON strings from JavaScript code.
1.0
28
Introduced
Gecko 1.9
Inherits from: nsISupports Last changed in Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

Note: This interface may only be used from JavaScript code, with the exception of the legacyDecodeToJSVal() method. However, you should use native JSON instead if at all possible.

Implemented by: @mozilla.org/dom/json;1. To create an instance, use:

var nativeJSON = Components.classes["@mozilla.org/dom/json;1"]
                 .createInstance(Components.interfaces.nsIJSON);

Method overview

Note: The IDL file has portions of the IDL commented out because they represent things that can't actually be properly described by IDL; however, for the purposes of this article, we'll pretend they can be and ignore that issue.

JSObject decode(in AString str); Obsolete since Gecko 7.0
jsval decodeToJSVal(in AString str, in JSContext cx); Native code only!
JSObject decodeFromStream(in nsIInputStream stream, in long contentLength);
AString encode(in JSObject value); Obsolete since Gecko 7.0
AString encodeFromJSVal(in Jsvaljsval value, in JSContext cx); Native code only!
void encodeToStream(in nsIOutputStream stream, in string charset, in boolean writeBOM, in JSObject value);
jsval legacyDecode(in AString str); Deprecated since Gecko 2.0
jsval legacyDecodeFromStream(in AString str);  Deprecated since Gecko 2.0
jsval legacyDecodeToJSVal(in AString str, in JSContext cx); Native code only! Deprecated since Gecko 2.0

Methods

Obsolete since Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

decode()

Decodes a JSON string, returning the JavaScript object it represents.

Note: This method is more flexible than it should be, and accepts some not-correctly-structured JSON. For that reason, it has been removed in Gecko 7.0.
 JSObject decode(
   in AString str
 );
Parameters
str
The JSON string to decode.
Return value

The original JavaScript object, reconstructed from the JSON string.

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

decodeToJSVal()

Note: This method may only be used from native code, and provides a way to decode a JSON string to a jsval for use in your native code. Don't forget to GCroot the result before using it.
 jsval decodeToJSVal(
   in AString str,
   in JSContext cx
 );
Parameters
str
The JSON string to decode.
cx
The JavaScript runtime context to use to decode the string.
Return value

The original JavaScript object, reconstructed from the JSON string. Don't forget to GCroot the jsval before using it.

decodeFromStream()

Decodes a JSON string read from an input stream, returning the JavaScript object it represents.

 JSObject decodeFromStream(
   in nsIInputStream stream,
   in long contentLength
 );
Parameters
stream
The nsIInputStream from which to read the JSON string.
contentLength
The length of the JSON string to read.
Return value

A JSObject which is the original JavaScript object, reconstructed from the JSON string.

Obsolete since Gecko 7.0 (Firefox 7.0 / Thunderbird 7.0 / SeaMonkey 2.4)

encode()

Encodes a JavaScript object into a JSON string.

 AString encode(
   in JSObject value
 );
Parameters
value
The JavaScript object to encode.
Return value

A JSON string representing the object.

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

encodeFromJSVal()

Note: This method may only be used from native code, and provides a way to encode a jsval to a JSON string for use in your native code.
 AString encodeFromJSVal(
   in jsval value,
   in JSContext cx
 );
Parameters
value
A pointer to the jsval to encode.
cx
The JavaScript runtime context to use to encode the value.
Return value

A JSON string representing the value.

encodeToStream()

Encodes a JavaScript object into JSON format, writing it to a stream.

 void encodeToStream(
   in nsIOutputStream stream,
   in string charset,
   in boolean writeBOM
   in JSObject value
 );
Parameters
stream
The nsIOutputStream to which to write the JSON string.
charset
The string encoding to use. Only the five Unicode encodings "UTF-8", "UTF-16LE", "UTF-16BE", "UTF-32LE" and "UTF-32BE" are supported.
writeBOM
Specify true if you wish to write a byte-order mark (BOM) into the stream, otherwise specify false.
value
The JavaScript object to encode.

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

legacyDecode()

Deprecated
This feature has been removed from the Web. Though some browsers may still support it, it is in the process of being dropped. Do not use it in old or new projects. Pages or Web apps using it may break at any time.

Decodes a JSON string. This method accepts slightly more than the exact JSON syntax; details of extra accepted syntax are deliberately not described.  This method is intended for use only by code processing legacy data.  When the original instance requiring this function is removed, this method will be removed.  Thus, this deprecated method should not be used.

 jsval legacyDecode(
   in AString str
 );
Parameters
str
The JSON string to decode.
Return value

The original JavaScript object, reconstructed from the JSON string.

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

legacyDecodeFromStream()

Deprecated
This feature has been removed from the Web. Though some browsers may still support it, it is in the process of being dropped. Do not use it in old or new projects. Pages or Web apps using it may break at any time.

Decodes a JSON string, read from a stream. This method accepts slightly more than the exact JSON syntax; details of extra accepted syntax are deliberately not described.  This method is intended for use only by code processing legacy data.  When the original instance requiring this function is removed, this method will be removed.  Thus, this deprecated method should not be used.

 jsval legacyDecodeFromStream(
   in nsIInputStream stream,
   in long contentLength
 );
Parameters
stream
The nsIInputStream from which to read the JSON string to decode.
contentLength
The length of the string to decode.
Return value

The original JavaScript object, reconstructed from the JSON string.

Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

legacyDecodeToJSVal()

Deprecated
This feature has been removed from the Web. Though some browsers may still support it, it is in the process of being dropped. Do not use it in old or new projects. Pages or Web apps using it may break at any time.

Decodes a JSON string to a jsval. This method accepts slightly more than the exact JSON syntax; details of extra accepted syntax are deliberately not described.  This method is intended for use only by code processing legacy data.  When the original instance requiring this function is removed, this method will be removed.  Thus, this deprecated method should not be used.

Note: This method may only be used from native code, and provides a way to decode a JSON string to a jsval for use in your native code. Don't forget to GCroot the result before using it.
 jsval legacyDecodeToJSVal(
   in AString str,
   in JSContext cx
 );
Parameters
str
The JSON string to decode.
cx
The JavaScript runtime context to use to decode the string.
Return value

The original JavaScript object, reconstructed from the JSON string. Don't forget to GCroot the jsval before using it.

See also

Document Tags and Contributors

Tags: 
 Contributors to this page: Sheppy, Neil, Waldo, trevorh, Kliu0x52, Kohei
 Last updated by: Sheppy,