nsIJSON 编辑

dom/interfaces/json/nsIJSON.idlScriptable This interface provides a convenient way to encode and decode JSON strings from JavaScript code. 1.0 66 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(inAStringstr); Obsolete since Gecko 7.0

jsval decodeToJSVal(inAStringstr, in JSContext cx); Native code only!

JSObjectdecodeFromStream(in nsIInputStream stream, in long contentLength);

AString encode(inJSObjectvalue); Obsolete since Gecko 7.0

AStringencodeFromJSVal(inJsvaljsval value, in JSContext cx); Native code only!

void encodeToStream(in nsIOutputStream stream, in string charset, in boolean writeBOM, inJSObjectvalue);

jsval legacyDecode(inAStringstr); Deprecated since Gecko 2.0

jsval legacyDecodeFromStream(inAStringstr);  Deprecated since Gecko 2.0

jsval legacyDecodeToJSVal(inAStringstr, in JSContext cx); Native code only! Deprecated since Gecko 2.0

Methods

decode()

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

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.

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.

encode()

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

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.

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.

legacyDecode()

Deprecated
This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work 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.

legacyDecodeFromStream()

Deprecated
This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work 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.

legacyDecodeToJSVal()

Deprecated
This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work 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

• JSON