<EXTERNALREFname='LXR ID Search'value='http://lxr.mozilla.org/seamonkey/ident?i={e}'/>
<ENTRYid='JSVAL_IS_OBJECT'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a specified value is a JS object.
</SUMMARY>
<SYNTAX>
JSVAL_IS_OBJECT(v)
</SYNTAX>
<DESCRIPTION>
Use <C>JSVAL_IS_OBJECT</C> to determine if a given JS value, <C>v</C>, is a JS object or <C>NULL</C>. If the type tag for <C>v</C> is <C>JSVAL_OBJECT</C>, <C>JSVAL_IS_OBJECT</C> evaluates to <I><C>true</C></I>. Otherwise, it evaluates to <I><C>false</C></I>. These return types are C values, not JS Boolean values.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code snippet illustrates how a JavaScript variable, MyItem, is conditionally tested in an if statement to see if it is a JS object.'>
if (JSVAL_IS_OBJECT(MyItem)) {
. . .
}
</EXAMPLE>
<SEEALSOvalue='JSVAL_IS_NUMBER'/>
<SEEALSOvalue='JSVAL_IS_INT'/>
<SEEALSOvalue='JSVAL_IS_DOUBLE'/>
<SEEALSOvalue='JSVAL_IS_STRING'/>
<SEEALSOvalue='JSVAL_IS_BOOLEAN'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
<SEEALSOvalue='JSVAL_IS_NULL'/>
<SEEALSOvalue='JSVAL_IS_VOID'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRYid='JSVAL_IS_NUMBER'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a specified value is a JS integer or double.
</SUMMARY>
<SYNTAX>
JSVAL_IS_NUMBER(v)
</SYNTAX>
<DESCRIPTION>
Use <C>JSVAL_IS_NUMBER</C> to determine if a given JS value, <C>v</C>, is an integer or double value. If the type tag for <C>v</C> is <C>JSVAL_INT</C> or <C>JSVAL_DOUBLE</C>, <C>JSVAL_IS_NUMBER</C> evaluates to <I><C>true</C></I>. Otherwise, it evaluates to <I><C>false</C></I>. These return types are C values, not JS Boolean values.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code snippet illustrates how a JavaScript variable, MyItem, is conditionally tested in an if statement to see if it is a JS integer or double value.'>
if (JSVAL_IS_NUMBER(MyItem)) {
. . .
}
</EXAMPLE>
<SEEALSOvalue='JSVAL_IS_OBJECT'/>
<SEEALSOvalue='JSVAL_IS_INT'/>
<SEEALSOvalue='JSVAL_IS_DOUBLE'/>
<SEEALSOvalue='JSVAL_IS_STRING'/>
<SEEALSOvalue='JSVAL_IS_BOOLEAN'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
<SEEALSOvalue='JSVAL_IS_NULL'/>
<SEEALSOvalue='JSVAL_IS_VOID'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRYid='JSVAL_IS_INT'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a specified value is a JS integer data type.
</SUMMARY>
<SYNTAX>
JSVAL_IS_INT(v)
</SYNTAX>
<DESCRIPTION>
Use <C>JSVAL_IS_INT</C> to determine if a given JS value, <C>v</C>, is a JS integer value. If the type tag for <C>v</C> is <C>JSVAL_INT</C> and is not <C>JSVAL_VOID</C>, <C>JSVAL_IS_INT</C> evaluates to <I><C>true</C></I>. Otherwise, it evaluates to <I><C>false</C></I>. These return types are C values, not JS Boolean values.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code snippet illustrates how a JavaScript variable, MyItem, is conditionally tested in an if statement to see if it is a JS integer data type.'>
if (JSVAL_IS_INT(MyItem)) {
. . .
}
</EXAMPLE>
<SEEALSOvalue='JSVAL_IS_OBJECT'/>
<SEEALSOvalue='JSVAL_IS_NUMBER'/>
<SEEALSOvalue='JSVAL_IS_DOUBLE'/>
<SEEALSOvalue='JSVAL_IS_STRING'/>
<SEEALSOvalue='JSVAL_IS_BOOLEAN'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
<SEEALSOvalue='JSVAL_IS_NULL'/>
<SEEALSOvalue='JSVAL_IS_VOID'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRYid='JSVAL_IS_DOUBLE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a specified JS value is a JS double data type.
</SUMMARY>
<SYNTAX>
JSVAL_IS_DOUBLE(v)
</SYNTAX>
<DESCRIPTION>
Use <C>JSVAL_IS_DOUBLE</C> to determine if a given value, <C>v</C>, is a JS double value. If the type tag for <C>v</C> is <C>JSVAL_DOUBLE</C>, <C>JSVAL_IS_DOUBLE</C> evaluates to <I><C>true</C></I>. Otherwise, it evaluates to <I><C>false</C></I>. These return types are C values, not JS Boolean values.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code snippet illustrates how a JavaScript variable, MyItem, is conditionally tested in an if statement to see if it is a JS double data type.'>
if (JSVAL_IS_DOUBLE(MyItem)) {
. . .
}
</EXAMPLE>
<SEEALSOvalue='JSVAL_IS_OBJECT'/>
<SEEALSOvalue='JSVAL_IS_NUMBER'/>
<SEEALSOvalue='JSVAL_IS_INT'/>
<SEEALSOvalue='JSVAL_IS_STRING'/>
<SEEALSOvalue='JSVAL_IS_BOOLEAN'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
<SEEALSOvalue='JSVAL_IS_NULL'/>
<SEEALSOvalue='JSVAL_IS_VOID'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRYid='JSVAL_IS_STRING'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a specified JS value is a JS string data type.
</SUMMARY>
<SYNTAX>
JSVAL_IS_STRING(v)
</SYNTAX>
<DESCRIPTION>
Use <C>JSVAL_IS_STRING</C> to determine if a given JS value, <C>v</C>, is a JS string. If the type tag for <C>v</C> is <C>JSVAL_STRING</C>, <C>JSVAL_IS_STRING</C> evaluates to <I><C>true</C></I>. Otherwise, it evaluates to <I><C>false</C></I>. These return types are C values, not JS Boolean values.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code snippet illustrates how a JavaScript variable, MyItem, is conditionally tested in an if statement to see if it is a JS string data type.'>
if (JSVAL_IS_STRING(MyItem)) {
. . .
}
</EXAMPLE>
<SEEALSOvalue='JSVAL_IS_OBJECT'/>
<SEEALSOvalue='JSVAL_IS_NUMBER'/>
<SEEALSOvalue='JSVAL_IS_INT'/>
<SEEALSOvalue='JSVAL_IS_DOUBLE'/>
<SEEALSOvalue='JSVAL_IS_BOOLEAN'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
<SEEALSOvalue='JSVAL_IS_NULL'/>
<SEEALSOvalue='JSVAL_IS_VOID'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRYid='JSVAL_IS_BOOLEAN'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a specified value is a JS Boolean data type.
</SUMMARY>
<SYNTAX>
JSVAL_IS_BOOLEAN(v)
</SYNTAX>
<DESCRIPTION>
Use <C>JSVAL_IS_BOOLEAN</C> to determine if a given value, <C>v</C>, is a JS Boolean value. If the type tag for <C>v</C> is <C>JSVAL_BOOLEAN</C>, <C>JSVAL_IS_BOOLEAN</C> evaluates to <I><C>true</C></I>. Otherwise, it evaluates to <I><C>false</C></I>. These return types are C values, not JS Boolean values.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code snippet illustrates how a JavaScript variable, MyItem, is conditionally tested in an if statement to see if it is a JS Boolean data type.'>
if (JSVAL_IS_BOOLEAN(MyItem)) {
. . .
}
</EXAMPLE>
<SEEALSOvalue='JSVAL_IS_OBJECT'/>
<SEEALSOvalue='JSVAL_IS_NUMBER'/>
<SEEALSOvalue='JSVAL_IS_INT'/>
<SEEALSOvalue='JSVAL_IS_DOUBLE'/>
<SEEALSOvalue='JSVAL_IS_STRING'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
<SEEALSOvalue='JSVAL_IS_NULL'/>
<SEEALSOvalue='JSVAL_IS_VOID'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRYid='JSVAL_IS_NULL'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a specified JS value is null.
</SUMMARY>
<SYNTAX>
JSVAL_IS_NULL(v)
</SYNTAX>
<DESCRIPTION>
Use <C>JSVAL_IS_NULL</C> to determine if a given JS value, <C>v</C>, contains a null value. If <C>v</C> is <C>JSVAL_NULL</C>, <C>JSVAL_IS_NULL</C> evaluates to <I><C>true</C></I>. Otherwise, it evaluates to <I><C>false</C></I>. These return types are C values, not JS Boolean values.<P/>
</DESCRIPTION>
<NOTE>
Even though <C>v</C> may contain a null value, its type tag is always <C>JSVAL_OBJECT</C>.<P/>
</NOTE>
<EXAMPLEdesc='The following code snippet illustrates how a JavaScript variable, MyItem, is conditionally tested in an if statement to see if it contains a null value.'>
if (JSVAL_IS_NULL(MyItem)) {
. . .
}
</EXAMPLE>
<SEEALSOvalue='JSVAL_IS_OBJECT'/>
<SEEALSOvalue='JSVAL_IS_NUMBER'/>
<SEEALSOvalue='JSVAL_IS_INT'/>
<SEEALSOvalue='JSVAL_IS_DOUBLE'/>
<SEEALSOvalue='JSVAL_IS_STRING'/>
<SEEALSOvalue='JSVAL_IS_BOOLEAN'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
<SEEALSOvalue='JSVAL_IS_VOID'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRYid='JSVAL_IS_PRIMITIVE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a given JS value is a primitive type.
</SUMMARY>
<SYNTAX>
JSVAL_IS_PRIMITIVE(v)
</SYNTAX>
<DESCRIPTION>
Use <C>JSVAL_IS_PRIMITVE</C> to determine if a specified jsval, <C>v</C>, is an instrinsic JS primitive. Primitves are values that are undefined, null, boolean, numeric, or string types. If <C>v</C> is one of these, <C>JSVAL_IS_PRIMITVE</C> returns true. If <C>v</C> is an object, <C>JSVAL_IS_PRIMITIVE</C> returns false.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSVAL_IS_OBJECT'/>
<SEEALSOvalue='JSVAL_IS_NUMBER'/>
<SEEALSOvalue='JSVAL_IS_INT'/>
<SEEALSOvalue='JSVAL_IS_DOUBLE'/>
<SEEALSOvalue='JSVAL_IS_STRING'/>
<SEEALSOvalue='JSVAL_IS_BOOLEAN'/>
<SEEALSOvalue='JSVAL_IS_VOID'/>
<SEEALSOvalue='JSVAL_IS_NULL'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRYid='JSVAL_IS_VOID'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a specified JS value is void.
</SUMMARY>
<SYNTAX>
JSVAL_IS_VOID(v)
</SYNTAX>
<DESCRIPTION>
Use <C>JSVAL_IS_VOID</C> to determine if a given value, <C>v</C>, is void. If <C>v</C> is <C>JSVAL_VOID</C>, <C>JSVAL_IS_VOID</C> evaluates to <I><C>true</C></I>. Otherwise, it evaluates to <I><C>false</C></I>. These return types are C values, not JS Boolean values.<P/>
</DESCRIPTION>
<NOTE>
In JavaScript and in the ECMA language standard, the C type, <C>void</C>, indicates an "undefined" value.<P/>
</NOTE>
<EXAMPLEdesc='The following code snippet illustrates how a JavaScript variable, MyItem, is conditionally tested in an if statement to see if it is void.'>
if (JSVAL_IS_VOID(MyItem)) {
. . .
}
</EXAMPLE>
<SEEALSOvalue='JSVAL_IS_OBJECT'/>
<SEEALSOvalue='JSVAL_IS_NUMBER'/>
<SEEALSOvalue='JSVAL_IS_INT'/>
<SEEALSOvalue='JSVAL_IS_DOUBLE'/>
<SEEALSOvalue='JSVAL_IS_STRING'/>
<SEEALSOvalue='JSVAL_IS_BOOLEAN'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
<SEEALSOvalue='JSVAL_IS_NULL'/>
<SEEALSOvalue='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRYid='JSVAL_IS_GCTHING'>
<TYPEvalue='Macro'/>
<SUMMARY>
Indicates whether a JS value has a type that is subject to garbage collection.
</SUMMARY>
<SYNTAX>
JSVAL_IS_GCTHING(v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_IS_GCTHING</C> determines whether or not a specified JS value, <C>v</C>, is a pointer to value that is subject to garbage collection. JavaScript performs automatic garbage collection of objects, strings, and doubles. If the type tag for <C>v</C> is not <C>JSVAL_INT</C> and it is not <C>JSVAL_BOOLEAN</C>, <C>JSVAL_IS_GCTHING</C> evaluates to <I><C>true</C></I>. Otherwise it evaluates to <I><C>false</C></I>.<P/>
</DESCRIPTION>
<NOTE>
<C>JSVAL_IS_GCTHING</C> evaluates to <C>true</C> for <C>JSVAL_NULL</C>.
</NOTE>
<SEEALSOvalue='JSVAL_TO_GCTHING'/>
</ENTRY>
<ENTRYid='JSVAL_TO_GCTHING'>
<TYPEvalue='Macro'/>
<SUMMARY>
Clears the type tag for specified JS value, so that the JS value can be garbage collected if it is a string, object, or number.
</SUMMARY>
<SYNTAX>
JSVAL_TO_GCTHING(v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_TO_GCTHING</C> clears the type tag for a specified JS value, <C>v</C>, so the JS value can be garbage collected if it is a string, object, or number. It does so by clearing the type tag, which results in clean pointer to the storage area for <C>v</C>. The resulting value is cast to a void pointer.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSVAL_IS_GCTHING'/>
</ENTRY>
<ENTRYid='JSVAL_TO_OBJECT'>
<TYPEvalue='Macro'/>
<SUMMARY>
Casts the type tag for a specified JS value and returns a pointer to the value cast as a JS object.
</SUMMARY>
<SYNTAX>
JSVAL_TO_OBJECT(v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_TO_OBJECT</C> clears a specified JS value, <C>v</C>, to a JS object. It does so by casting the value's type tag and casting the result to an object pointer.<P/>
Casting <C>v</C> to an object pointer manipulates its underlying type tag. <C>v</C> must be an object jsval. Casting does not convert the value stored in <C>v</C> to a different data type. To perform actual data type conversion, use the <C>JS_ValueToObject</C> function.<P/>
</DESCRIPTION>
<NOTE>
This macro assumes that the JS type tag for <C>v</C> is already <C>JSVAL_OBJECT</C>.
Because JS values are represented as bit-shifted C integers, comparisons of
<C>JSVAL_TO_OBJECT(v)</C> to <C>v</C> itself are not equal unless you ignore the C pointer
type mismatch and <C>v</C> is an object reference.
<P/>
</NOTE>
<SEEALSOvalue='JSVAL_TO_GCTHING'/>
<SEEALSOvalue='JSVAL_TO_DOUBLE'/>
<SEEALSOvalue='JSVAL_TO_STRING'/>
<SEEALSOvalue='OBJECT_TO_JSVAL'/>
<SEEALSOvalue='DOUBLE_TO_JSVAL'/>
<SEEALSOvalue='STRING_TO_JSVAL'/>
<SEEALSOvalue='JS_ValueToObject'/>
</ENTRY>
<ENTRYid='JSVAL_TO_DOUBLE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Casts the type flag for a specified JS value and returns a pointer to the value cast as a JS double.
</SUMMARY>
<SYNTAX>
JSVAL_TO_DOUBLE(v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_TO_DOUBLE</C> casts a specified JS value, <C>v</C>, to a JS double. It does so by casting the value's type tag and casting the result to a double pointer.<P/>
Clearing <C>v</C> to a double pointer manipulates its underlying type tag. It does not convert the value stored in <C>v</C> to a different data type. To perform actual data conversion, use the <C>JS_ValueToNumber</C> function.<P/>
</DESCRIPTION>
<NOTE>
This macro assumes that the JS type tag for <C>v</C> is already <C>JSVAL_DOUBLE</C>.
Because JS values are represented as bit-shifted C integers, comparisons of
<C>JSVAL_TO_DOUBLE(v)</C> to <C>v</C> itself are not equal unless you ignore the C pointer
type mismatch and <C>v</C> is an object reference.
<P/>
</NOTE>
<SEEALSOvalue='JSVAL_TO_GCTHING'/>
<SEEALSOvalue='JSVAL_TO_OBJECT'/>
<SEEALSOvalue='JSVAL_TO_STRING'/>
<SEEALSOvalue='OBJECT_TO_JSVAL'/>
<SEEALSOvalue='DOUBLE_TO_JSVAL'/>
<SEEALSOvalue='STRING_TO_JSVAL'/>
<SEEALSOvalue='JS_ValueToNumber'/>
</ENTRY>
<ENTRYid='JSVAL_TO_STRING'>
<TYPEvalue='Macro'/>
<SUMMARY>
Casts the type tag for a specified JS value and returns a pointer to the value cast as a JS string.
</SUMMARY>
<SYNTAX>
JSVAL_TO_STRING(v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_TO_STRING </C>casts a specified JS value, <C>v</C>, to a JS string. It does so by casting the value's type tag and casting the result to a string pointer.<P/>
Casting <C>v</C> to a string pointer manipulate its underlying type tag. It does not convert the value stored in <C>v</C> to a different data type. To perform actual data type conversion, use the <C>JS_ValueToString</C> function.<P/>
</DESCRIPTION>
<NOTE>
This macro assumes that the JS type tag for <C>v</C> is already <C>JSVAL_STRING</C>.
Because JS values are represented as bit-shifted C integers, comparisons of
<C>JSVAL_TO_STRING(v)</C> to <C>v</C> itself are not equal unless you ignore the C pointer
type mismatch and <C>v</C> is an object reference.
<P/>
</NOTE>
<SEEALSOvalue='JSVAL_TO_GCTHING'/>
<SEEALSOvalue='JSVAL_TO_OBJECT'/>
<SEEALSOvalue='JSVAL_TO_STRING'/>
<SEEALSOvalue='OBJECT_TO_JSVAL'/>
<SEEALSOvalue='DOUBLE_TO_JSVAL'/>
<SEEALSOvalue='STRING_TO_JSVAL'/>
<SEEALSOvalue='JS_ValueToString'/>
</ENTRY>
<ENTRYid='OBJECT_TO_JSVAL'>
<TYPEvalue='Macro'/>
<SUMMARY>
Casts a specified JS object to a JS value.
</SUMMARY>
<SYNTAX>
OBJECT_TO_JSVAL(obj)
</SYNTAX>
<DESCRIPTION>
<C>OBJECT_TO_JSVAL</C> casts a specified JS object, <C>obj</C>, to a JS value.<P/>
</DESCRIPTION>
<SEEALSOvalue='DOUBLE_TO_JSVAL'/>
<SEEALSOvalue='STRING_TO_JSVAL'/>
</ENTRY>
<ENTRYid='DOUBLE_TO_JSVAL'>
<TYPEvalue='Macro'/>
<SUMMARY>
Casts a specified JS double to a JS value.
</SUMMARY>
<SYNTAX>
DOUBLE_TO_JSVAL(dp)
</SYNTAX>
<DESCRIPTION>
<C>DOUBLE_TO_JSVAL</C> casts a specified JS double type, <C>dp</C>, to a JS value, <C>jsval</C>. First it sets the double's data type flag to <C>JSVAL_DOUBLE</C> and then performs the cast.<P/>
</DESCRIPTION>
<SEEALSOvalue='OBJECT_TO_JSVAL'/>
<SEEALSOvalue='STRING_TO_JSVAL'/>
</ENTRY>
<ENTRYid='STRING_TO_JSVAL'>
<TYPEvalue='Macro'/>
<SUMMARY>
Casts a specified JS string to a JS value.
</SUMMARY>
<SYNTAX>
STRING_TO_JSVAL(str)
</SYNTAX>
<DESCRIPTION>
<C>STRING_TO_JSVAL</C> casts a specified JS string type, <C>str</C>, to a JS value, <C>jsval</C>. First it sets the string's data type flag to <C>JSVAL_STRING</C> and then performs the cast.<P/>
</DESCRIPTION>
<SEEALSOvalue='OBJECT_TO_JSVAL'/>
<SEEALSOvalue='DOUBLE_TO_JSVAL'/>
</ENTRY>
<ENTRYid='JSVAL_LOCK'>
<TYPEvalue='Macro'/>
<SUMMARY>
Locks a JS value to prevent garbage collection on it.
</SUMMARY>
<SYNTAX>
JSVAL_LOCK(cx,v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_LOCK</C> is a deprecated feature that is supported only for backward compatibility with existing applications. To lock a value, use local roots with JS_AddRoot.<P/>
<C>JSVAL_LOCK</C> locks a JS value, <C>v</C>, to prevent the value from being garbage collected. <C>v </C>is a JS object, string, or double value.<P/>
<C>JSVAL_LOCK</C> determines if <C>v</C> is an object, string, or double value, and if it is, it locks the value. If locking is successful, or <C>v</C> already cannot be garbage collected because it is not an object, string, or double value, <C>JSVAL_LOCK</C> evaluates to <I><C>true</C></I>. Otherwise <C>JSVAL_LOCK</C> evaluates to <I><C>false</C></I>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_AddRoot'/>
<SEEALSOvalue='JSVAL_IS_GCTHING'/>
<SEEALSOvalue='JSVAL_TO_GCTHING'/>
<SEEALSOvalue='JSVAL_UNLOCK'/>
<SEEALSOvalue='JS_LockGCThing'/>
<DEPRECATED/>
</ENTRY>
<ENTRYid='JSVAL_UNLOCK'>
<TYPEvalue='Macro'/>
<SUMMARY>
Unlocks a JS value, enabling garbage collection on it.
</SUMMARY>
<SYNTAX>
JSVAL_UNLOCK(cx,v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_UNLOCK</C> is a deprecated feature that is supported only for backward compatibility with existing applications. To unlock a value, use local roots with JS_RemoveRoot.<P/>
<C>JSVAL_UNLOCK</C> unlocks a previously locked JS value, <C>v</C>, so it can be garbage collected. <C>v</C> is a JS object, string, or double value.<P/>
<C>JSVAL_UNLOCK</C> determine if <C>v</C> is an object, string, or double value, and if it is, it unlocks the value. If unlocking is successful, or <C>v</C> is not affected by garbage collection because it is not an object, string, or double value, <C>JSVAL_UNLOCK</C> evaluates to <I><C>true</C></I>. Otherwise <C>JSVAL_UNLOCK</C> evaluates to <I><C>false</C></I>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_AddRoot'/>
<SEEALSOvalue='JSVAL_IS_GCTHING'/>
<SEEALSOvalue='JSVAL_TO_GCTHING'/>
<SEEALSOvalue='JSVAL_LOCK'/>
<SEEALSOvalue='JS_LockGCThing'/>
<DEPRECATED/>
</ENTRY>
<ENTRYid='INT_FITS_IN_JSVAL'>
<TYPEvalue='Macro'/>
<SUMMARY>
Determines if a specified value is a valid JS integer.
</SUMMARY>
<SYNTAX>
INT_FITS_IN_JSVAL(i)
</SYNTAX>
<DESCRIPTION>
Determines if a specified C integer value, <C>i</C>, lies within the minimum and maximum ranges allowed for a <C>jsval</C> integer. If the value is within range, it can become a valid JS integer, and <C>INT_FITS_IN_JSVAL</C> is <I><C>true</C></I>. Otherwise <C>INT_FITS_IN_JSVAL</C> is <I><C>false</C></I>.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code snippet illustrates how a JavaScript variable, MyItem, is conditionally tested in an if statement to see if it is a legal integer value.'>
if (INT_FITS_IN_JSVAL(MyItem)) {
. . .
}
else
JS_ReportError(MyContext, "Integer out of range: %s",
MyItem);
</EXAMPLE>
<SEEALSOvalue='JSVAL_TO_INT'/>
<SEEALSOvalue='INT_TO_JSVAL'/>
</ENTRY>
<ENTRYid='JSVAL_TO_INT'>
<TYPEvalue='Macro'/>
<SUMMARY>
Converts a JS integer value to an integer.
</SUMMARY>
<SYNTAX>
JSVAL_TO_INT(v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_TO_INT</C> converts a specified JS integer value, <C>v</C>, to a C integer value by performing a bitwise right shift operation. <C>JSVAL_TO_INT</C> assumes that it was passed a JS value of type <C>JSVAL_INT</C>, and returns that JS value's corresponding C integer value. Note that because of the bit-shifting operation, that a C comparison of <C>JSVAL_TO_INT(v)</C> to <C>v</C> always results in nonequality.<P/>
</DESCRIPTION>
<SEEALSOvalue='INT_TO_JSVAL'/>
<SEEALSOvalue='JSVAL_TO_BOOLEAN'/>
<SEEALSOvalue='JSVAL_TO_PRIVATE'/>
</ENTRY>
<ENTRYid='INT_TO_JSVAL'>
<TYPEvalue='Macro'/>
<SUMMARY>
Converts a specified integer value to a JS integer value.
</SUMMARY>
<SYNTAX>
INT_TO_JSVAL(i)
</SYNTAX>
<DESCRIPTION>
<C>INT_TO_JSVAL</C> converts a C integer, <C>i</C>, to a JS integer value type using a bitwise left shift operation and <C>OR</C>'ing the result with the <C>JSVAL_INT</C> macro.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSVAL_TO_INT'/>
<SEEALSOvalue='BOOLEAN_TO_JSVAL'/>
<SEEALSOvalue='PRIVATE_TO_JSVAL'/>
</ENTRY>
<ENTRYid='JSVAL_TO_BOOLEAN'>
<TYPEvalue='Macro'/>
<SUMMARY>
Converts a JS value to a C <C>true</C> or <C>false</C> value.
</SUMMARY>
<SYNTAX>
JSVAL_TO_BOOLEAN(v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_TO_BOOLEAN</C> converts a specified JS value, <C>v</C>, to a C <C>true</C> or <C>false</C> value by performing a bitwise right shift operation. <C>JSVAL_TO_BOOLEAN</C> assumes that it was passed a JS value of type <C>JSVAL_BOOLEAN</C>, and returns that JS value's corresponding C integer value.<P/>
</DESCRIPTION>
<SEEALSOvalue='BOOLEAN_TO_JSVAL'/>
<SEEALSOvalue='JSVAL_TO_INT'/>
<SEEALSOvalue='JSVAL_TO_PRIVATE'/>
</ENTRY>
<ENTRYid='BOOLEAN_TO_JSVAL'>
<TYPEvalue='Macro'/>
<SUMMARY>
Converts a specified C <C>true</C> or <C>false</C> value to a JS value.
</SUMMARY>
<SYNTAX>
BOOLEAN_TO_JSVAL(b)
</SYNTAX>
<DESCRIPTION>
<C>BOOLEAN_TO_JSVAL</C> converts a C <C>true</C> or <C>false</C> value, <C>b</C>, to a JS Boolean value type using a bitwise left shift operation and setting the data type flag to <C>JSVAL_BOOLEAN</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSVAL_TO_BOOLEAN'/>
<SEEALSOvalue='INT_TO_JSVAL'/>
<SEEALSOvalue='PRIVATE_TO_JSVAL'/>
</ENTRY>
<ENTRYid='JSVAL_TO_PRIVATE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Casts a JS value to a private data pointer.
</SUMMARY>
<SYNTAX>
JSVAL_TO_PRIVATE(v)
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_TO_PRIVATE</C> casts a JS value, <C>v</C>, to a void pointer to private data. Private data is associated with an JS class on which the <C>JSCLASS_HAS_PRIVATE</C> attribute is set. Private data is user-allocated, defined, and maintained. Private pointers must be word aligned.<P/>
<C>JSVAL_TO_PRIVATE</C> returns an integer pointer cast as a void pointer.<P/>
</DESCRIPTION>
<SEEALSOvalue='PRIVATE_TO_JSVAL'/>
<SEEALSOvalue='JSCLASS_HAS_PRIVATE'/>
</ENTRY>
<ENTRYid='PRIVATE_TO_JSVAL'>
<TYPEvalue='Macro'/>
<SUMMARY>
Casts a private data pointer to a JS integer value.
</SUMMARY>
<SYNTAX>
PRIVATE_TO_JSVAL(p)
</SYNTAX>
<DESCRIPTION>
<C>PRIVATE_TO_JSVAL</C> enables you to store a private data pointer, <C>p</C>, as a JS value. The private pointer must be word-aligned. Before passing a pointer to <C>PRIVATE_TO_JSVAL</C>, test it with <C>INT_FITS_IN_JSVAL</C> to be verify that the pointer can be cast to a legal JS integer value.<P/>
<C>PRIVATE_TO_JSVAL</C> casts a pointer to a JS integer value and sets the <C>JSVAL_INT</C> type tag on it. <P/>
</DESCRIPTION>
<SEEALSOvalue='JSVAL_TO_PRIVATE'/>
<SEEALSOvalue='INT_FITS_IN_JSVAL'/>
</ENTRY>
<ENTRYid='JSPROP_ENUMERATE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Public.Flag that indicates a property is visible to <B>for</B> and <B>in</B> loops.
</SUMMARY>
<SYNTAX>
JSPROP_ENUMERATE
</SYNTAX>
<DESCRIPTION>
<C>JSPROP_ENUMERATE</C> is a flag value that indicates a property belonging to a JS object is visible to <B>for</B> and <B>in</B> loops. <C>JSPROP_ENUMERATE</C> is used to set or clear the <C>flags</C> field in a <C>JSPropertySpec</C> structure so that a property can be made visible or invisible to loops.<P/>
</DESCRIPTION>
<NOTE>
Property flags cannot be changed at run time. Instead, you either pass a set of
flags as an argument to <C>JS_DefineProperty</C> to create a single property with
fixed flag values, or you set property flags in a <C>JSPropertySpec</C> struct which is
then passed to the <C>JS_DefineProperties</C> function to create multiple
properties on a single object.
<P/>
</NOTE>
<EXAMPLEdesc='The following code fragment illustrates how JSPROP_ENUMERATE can be set for a property structure before you call JS_DefineProperties:'>
JSPROP_READONLY is a flag value that indicates that the value for a property belonging to a JS object cannot be set at run time. For JavaScript 1.2 and lower, it is an error to attempt to assign a value to a property marked with the <C>JSPROP_READONLY</C> flag. In JavaScript 1.3 and ECMA-Script, attempts to set a value on a read-only property are ignored. You can, however, always check the <C>flags</C> fields to determine if a property is read only.<P/>
</DESCRIPTION>
<NOTE>
Property flags cannot be changed at run time. Instead, you either pass a set of
flags as an argument to <C>JS_DefineProperty</C> to create a single property with
fixed flag values, or you set property flags in a <C>JSPropertySpec</C> struct which is
then passed to the <C>JS_DefineProperties</C> function to create multiple
properties on a single object.
<P/>
</NOTE>
<SEEALSOvalue='JSPROP_ENUMERATE'/>
<SEEALSOvalue='JSPROP_PERMANENT'/>
<SEEALSOvalue='JSPROP_EXPORTED'/>
<SEEALSOvalue='JSPROP_INDEX'/>
<SEEALSOvalue='JSPropertySpec'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineProperties'/>
</ENTRY>
<ENTRYid='JSPROP_PERMANENT'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that indicates a property is permanent and cannot be deleted.
</SUMMARY>
<SYNTAX>
JSPROP_PERMANENT
</SYNTAX>
<DESCRIPTION>
JSPROP_PERMANENT is a flag value that indicates that the property belonging to a JS object is a "permanent" property, one that cannot be deleted from the object at run time. Attempting to delete a permanent property is JavaScript 1.2 or lower results in an error. In JavaScript 1.3 and ECMA-Script, such deletion attempts are ignored. You can, however, always check the <C>flags</C> fields to determine if a property is permanent.<P/>
</DESCRIPTION>
<NOTE>
Property flags cannot be changed at run time. Instead, you either pass a set of
flags as an argument to <C>JS_DefineProperty</C> to create a single property with
fixed flag values, or you set property flags in a <C>JSPropertySpec</C> struct which is
then passed to the <C>JS_DefineProperties</C> function to create multiple
properties on a single object.
<P/>
</NOTE>
<SEEALSOvalue='JSPROP_ENUMERATE'/>
<SEEALSOvalue='JSPROP_READONLY'/>
<SEEALSOvalue='JSPROP_EXPORTED'/>
<SEEALSOvalue='JSPROP_INDEX'/>
<SEEALSOvalue='JSPropertySpec'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineProperties'/>
</ENTRY>
<ENTRYid='JSPROP_EXPORTED'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that indicates a property is exported from a JS object.
</SUMMARY>
<SYNTAX>
JSPROP_EXPORTED
</SYNTAX>
<DESCRIPTION>
JSPROP_EXPORTED is a flag value that indicates that a property can be imported by other scripts or objects, typically to borrow security privileges.<P/>
</DESCRIPTION>
<NOTE>
Property flags cannot be changed at run time. Instead, you either pass a set of
flags as an argument to <C>JS_DefineProperty</C> to create a single property with
fixed flag values, or you set property flags in a <C>JSPropertySpec</C> struct which is
then passed to the <C>JS_DefineProperties</C> function to create multiple
properties on a single object.
<P/>
</NOTE>
<SEEALSOvalue='JSPROP_ENUMERATE'/>
<SEEALSOvalue='JSPROP_READONLY'/>
<SEEALSOvalue='JSPROP_PERMANENT'/>
<SEEALSOvalue='JSPROP_INDEX'/>
<SEEALSOvalue='JSPropertySpec'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineProperties'/>
</ENTRY>
<ENTRYid='JSPROP_INDEX'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that indicates a property's name is actually an index number into an array.
</SUMMARY>
<SYNTAX>
JSPROP_INDEX
</SYNTAX>
<DESCRIPTION>
JSPROP_INDEX is a flag value that indicates a property's name will automatically be cast to an integer value to use as an index into an array of property values (elements).<P/>
</DESCRIPTION>
<NOTE>
Property flags cannot be changed at run time. Instead, you either pass a set of
flags as an argument to <C>JS_DefineProperty</C> to create a single property with
fixed flag values, or you set property flags in a <C>JSPropertySpec</C> struct which is
then passed to the <C>JS_DefineProperties</C> function to create multiple
properties on a single object.
<P/>
</NOTE>
<SEEALSOvalue='JSPROP_ENUMERATE'/>
<SEEALSOvalue='JSPROP_READONLY'/>
<SEEALSOvalue='JSPROP_PERMANENT'/>
<SEEALSOvalue='JSPROP_EXPORTED'/>
<SEEALSOvalue='JSPropertySpec'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineProperties'/>
</ENTRY>
<ENTRYid='JSFUN_BOUND_METHOD'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that indicates a function nominally associated with an object is bound, instead, to that object's parent.
</SUMMARY>
<SYNTAX>
JSFUN_BOUND_METHOD
</SYNTAX>
<DESCRIPTION>
This macro is deprecated. <C>JSFUN_BOUND_METHOD</C> is a flag that indicates a method associated with an object is bound to the object's parent. This macro is no longer needed because the JS engine now supports closures.<P/>
</DESCRIPTION>
<NOTE>
This macro exists only for backward compatibility with existing applications. Its
use is deprecated. Future versions of the JavaScript engine may not support or
recognize this macro.
<P/>
</NOTE>
<SEEALSOvalue='JSFUN_GLOBAL_PARENT'/>
<DEPRECATED/>
</ENTRY>
<ENTRYid='JSFUN_GLOBAL_PARENT'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that indicates a call to a function nominally associated with an object is called with the global object as its scope chain, rather than with the parent of the function.
</SUMMARY>
<SYNTAX>
JSFUN_GLOBAL_PARENT
</SYNTAX>
<DESCRIPTION>
This macro is deprecated. Instead of using it, use <C>JS_CloneFunctionObject</C>. <C>JSFUN_GLOBAL_PARENT</C> is a flag that indicates a call to a function nominally associated with an object is called with the global object as its scope chain, rather than with the parent of the function. This permits the function to operate on free variables in the larger scope when they are found through prototype lookups.<P/>
</DESCRIPTION>
<NOTE>
This macro exists only for backward compatibility with existing applications. Its
use is deprecated. Future versions of the JavaScript engine may not support or
recognize this macro.
<P/>
</NOTE>
<SEEALSOvalue='JSFUN_BOUND_METHOD'/>
<DEPRECATED/>
</ENTRY>
<ENTRYid='JSVAL_VOID'>
<TYPEvalue='Macro'/>
<SUMMARY>
Defines a void JS value.
</SUMMARY>
<SYNTAX>
JSVAL_VOID
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_VOID</C> defines a void JS value. Currently this value is defined as <C>0-JSVAL_INT_POW2(30)</C>. <P/>
</DESCRIPTION>
<SEEALSOvalue='JSVAL_NULL'/>
<SEEALSOvalue='JSVAL_ZERO'/>
<SEEALSOvalue='JSVAL_ONE'/>
<SEEALSOvalue='JSVAL_FALSE'/>
<SEEALSOvalue='JSVAL_TRUE'/>
<SEEALSOvalue='JS_NewContext'/>
</ENTRY>
<ENTRYid='JSVAL_NULL'>
<TYPEvalue='Macro'/>
<SUMMARY>
Defines a null JS value.
</SUMMARY>
<SYNTAX>
JSVAL_NULL
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_NULL</C> defines a null JS value. Currently this value is defined as <C>OBJECT_TO_JSVAL(0)</C>. <P/>
</DESCRIPTION>
<SEEALSOvalue='OBJECT_TO_JSVAL'/>
<SEEALSOvalue='JSVAL_VOID'/>
<SEEALSOvalue='JSVAL_ZERO'/>
<SEEALSOvalue='JSVAL_ONE'/>
<SEEALSOvalue='JSVAL_FALSE'/>
<SEEALSOvalue='JSVAL_TRUE'/>
<SEEALSOvalue='JS_NewContext'/>
</ENTRY>
<ENTRYid='JSVAL_ZERO'>
<TYPEvalue='Macro'/>
<SUMMARY>
Defines a JS value of 0.
</SUMMARY>
<SYNTAX>
JSVAL_ZERO
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_ZERO</C> defines a JS value of 0. Currently this value is defined as <C>INT_TO_JSVAL(0)</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='INT_TO_JSVAL'/>
<SEEALSOvalue='JSVAL_VOID'/>
<SEEALSOvalue='JSVAL_NULL'/>
<SEEALSOvalue='JSVAL_ONE'/>
<SEEALSOvalue='JSVAL_FALSE'/>
<SEEALSOvalue='JSVAL_TRUE'/>
<SEEALSOvalue='JS_NewContext'/>
</ENTRY>
<ENTRYid='JSVAL_ONE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Defines a JS value of 1.
</SUMMARY>
<SYNTAX>
JSVAL_ONE
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_ZERO</C> defines a JS value of 1. Currently this value is defined as <C>INT_TO_JSVAL(1)</C>. <P/>
</DESCRIPTION>
<SEEALSOvalue='INT_TO_JSVAL'/>
<SEEALSOvalue='JSVAL_VOID'/>
<SEEALSOvalue='JSVAL_NULL'/>
<SEEALSOvalue='JSVAL_ZERO'/>
<SEEALSOvalue='JSVAL_FALSE'/>
<SEEALSOvalue='JSVAL_TRUE'/>
<SEEALSOvalue='JS_NewContext'/>
</ENTRY>
<ENTRYid='JSVAL_FALSE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Defines a false JS Boolean value.
</SUMMARY>
<SYNTAX>
JSVAL_FALSE
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_FALSE</C> defines a false JS Boolean value. Currently this value is defined as <C>BOOLEAN_TO_JSVAL(JS_FALSE)</C>. <P/>
</DESCRIPTION>
<NOTE>
Do not compare <C>JSVAL_FALSE</C> with <C>JS_FALSE</C> in logical operations. These
values are not equal.
<P/>
</NOTE>
<SEEALSOvalue='BOOLEAN_TO_JSVAL'/>
<SEEALSOvalue='JSVAL_VOID'/>
<SEEALSOvalue='JSVAL_NULL'/>
<SEEALSOvalue='JSVAL_ZERO'/>
<SEEALSOvalue='JSVAL_ONE'/>
<SEEALSOvalue='JSVAL_TRUE'/>
<SEEALSOvalue='JS_NewContext'/>
</ENTRY>
<ENTRYid='JSVAL_TRUE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Defines a true JS Boolean value.
</SUMMARY>
<SYNTAX>
JSVAL_TRUE
</SYNTAX>
<DESCRIPTION>
<C>JSVAL_TRUE</C> defines a true JS Boolean value. Currently this value is defined as <C>BOOLEAN_TO_JSVAL(JS_TRUE)</C>. <P/>
</DESCRIPTION>
<NOTE>
Do not compare <C>JSVAL_TRUE</C> with <C>JS_TRUE</C> in logical operations. These values
are not equal.
<P/>
</NOTE>
<SEEALSOvalue='BOOLEAN_TO_JSVAL'/>
<SEEALSOvalue='JSVAL_VOID'/>
<SEEALSOvalue='JSVAL_NULL'/>
<SEEALSOvalue='JSVAL_ZERO'/>
<SEEALSOvalue='JSVAL_ONE'/>
<SEEALSOvalue='JSVAL_FALSE'/>
<SEEALSOvalue='JS_NewContext'/>
</ENTRY>
<ENTRYid='JSCLASS_HAS_PRIVATE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that indicates a class instance has a private data slot.
</SUMMARY>
<SYNTAX>
JSCLASS_HAS_PRIVATE
</SYNTAX>
<DESCRIPTION>
<C>JSCLASS_HAS_PRIVATE</C> can be specified in the <C>flags</C> field of a <C>JSClass</C> struct to indicate that a class instance has a private data slot. Set this flag if class instances should be allowed to use the <C>JS_GetPrivate</C> and <C>JS_SetPrivate</C> functions to store and retrieve private data.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSClass'/>
</ENTRY>
<ENTRYid='JSCLASS_NEW_ENUMERATE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that indicates that the <C>JSNewEnumerateOp</C> method is defined for a class.
</SUMMARY>
<SYNTAX>
JSCLASS_NEW_EUMERATE
</SYNTAX>
<DESCRIPTION>
<C>JSCLASS_NEW_ENUMERATE</C> can be specified in the <C>flags</C> field of a <C>JSClass</C> struct to indicate that a class instance defines the <C>JSNewEnumerateOp</C> method. This method is used for property enumerations when a class defines the <C>getObjectOps</C> field.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSCLASS_HAS_PRIVATE'/>
<SEEALSOvalue='JSCLASS_NEW_RESOLVE'/>
<SEEALSOvalue='JSClass'/>
<SEEALSOvalue='JSObjectOps'/>
</ENTRY>
<ENTRYid='JSCLASS_NEW_RESOLVE'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that indicates that the <C>JSNewResolveOp</C> method is defined for a class.
</SUMMARY>
<SYNTAX>
JSCLASS_NEW_RESOLVE
</SYNTAX>
<DESCRIPTION>
<C>JSCLASS_NEW_RESOLVE</C> can be specified inthe <C>flags</C> field of a <C>JSClass</C> struct to indicate that a class instance defines the <C>JSNewResolveOp</C> method. This method is used for property resolutions when a class defines the <C>getObjectOps</C> field.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSCLASS_HAS_PRIVATE'/>
<SEEALSOvalue='JSCLASS_NEW_ENUMERATE'/>
<SEEALSOvalue='JSClass'/>
<SEEALSOvalue='JSObjectOps'/>
</ENTRY>
<ENTRYid='JSPRINCIPALS_HOLD'>
<TYPEvalue='Macro'/>
<SUMMARY>
Increments the reference count for a specified <C>JSPrincipals</C> struct.
</SUMMARY>
<SYNTAX>
JSPRINCIPALS_HOLD(cx, principals)
</SYNTAX>
<DESCRIPTION>
<C>JSPRINCIPALS_HOLD</C> maintains the specified principals in a <C>JSPrincipals</C> struct, <C>principals</C>, for a specified <C>JSContext</C>, <C>cx</C>. Principals are used by the JS security mechanism. The hold is maintained by incrementing the reference count field in the struct by 1.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code increments the principals reference count for the MyPrincipals struct:'>
JSPrincipals MyPrincipals;
JSContext * MyContext;
JSRuntime *rt;
.
.
.
rt = Js_Init(32768);
MyContext = JS_NewContext(rt, 16384);
.
.
.
JSPRINCIPALS_HOLD(MyContext, MyPrincipals);
</EXAMPLE>
<SEEALSOvalue='JSPRINCIPALS_DROP'/>
<SEEALSOvalue='JSPrincipals'/>
<SEEALSOvalue='JS_Init'/>
<SEEALSOvalue='JS_NewContext'/>
</ENTRY>
<ENTRYid='JSPRINCIPALS_DROP'>
<TYPEvalue='Macro'/>
<SUMMARY>
Decrements the reference count for a specified <C>JSPrincipals</C> struct, and destroys the principals if the reference count is 0.
</SUMMARY>
<SYNTAX>
JSPRINCIPALS_DROP(cx, principals)
</SYNTAX>
<DESCRIPTION>
<C>JSPRINCIPALS_DROP</C> decrements the specified principals in a <C>JSPrincipals</C> struct, <C>principals</C>, for a specified <C>JSContext</C>, <C>cx</C>. The principals are dropped by deccrementing the reference count field in the struct by 1. If the reference count drops to zero, then <C>JSPRINCIPALS_DROP</C> also destroys the principals.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code decrements the principals reference count for the MyPrincipals struct, destroying the principals as well:'>
JSPrincipals MyPrincipals;
JSContext * MyContext;
JSRuntime *rt;
.
.
.
rt = Js_Init(32768);
MyContext = JS_NewContext(rt, 16384);
.
.
.
JSPRINCIPALS_HOLD(MyContext, MyPrincipals);
.
.
.
JSPRINCIPALS_DROP(MyContext, MyPrincipals);
</EXAMPLE>
<SEEALSOvalue='JSPRINCIPALS_HOLD'/>
<SEEALSOvalue='JSPrincipals'/>
<SEEALSOvalue='JS_Init'/>
<SEEALSOvalue='JS_NewContext'/>
</ENTRY>
<ENTRYid='JS_NewRuntime'>
<TYPEvalue='Macro'/>
<SUMMARY>
Initializes the JavaScript runtime.
</SUMMARY>
<SYNTAX>
JS_NewRuntime(maxbytes);
</SYNTAX>
<DESCRIPTION>
<C>JS_NewRuntime</C> initializes the JavaScript runtime environment. Call <C>JS_NewRuntime</C> before making any other API calls. <C>JS_NewRuntime</C> allocates memory for the <C>JSRuntime</C>, and initializes certain internal runtime structures. <C>maxbytes</C> specifies the number of allocated bytes after which garbage collection is run.<P/>
Generally speaking, most applications need only one <C>JSRuntime</C>. Each runtime is capable of handling multiple execution threads. You only need multiple runtimes if your application requires completely separate JS engines that cannot share values, objects, and functions.<P/>
If <C>JS_NewRuntime</C> is successful, it returns a pointer to the runtime. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_DestroyRuntime'/>
</ENTRY>
<ENTRYid='JS_DestroyRuntime'>
<TYPEvalue='Macro'/>
<SUMMARY>
Frees the JavaScript runtime.
</SUMMARY>
<SYNTAX>
JS_DestroyRuntime(rt);
</SYNTAX>
<DESCRIPTION>
<C>JS_DestroyRuntime</C> frees the specified the JavaScript runtime environment, <C>rt</C>. Call <C>JS_DestroyRuntime</C> after completing all other JS API calls. <C>JS_DestroyRuntime</C> garbage collects and frees the memory previously allocated by <C>JS_NewRuntime</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewRuntime'/>
</ENTRY>
<ENTRYid='JSRESOLVE_QUALIFIED'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that specifies that a function's identify can be uniquely resolved without examining the function prototype chain.
</SUMMARY>
<SYNTAX>
JSRESOLVE_QUALIFIED
</SYNTAX>
<DESCRIPTION>
<C>JSRESOLVE_QUALIFIED</C> is flag that, if included in a function's <C>flags</C> field, indicates that its identify can be uniquely resolved without reference to its full prototype chain.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSFUN_BOUND_METHOD'/>
<SEEALSOvalue='JSFUN_GLOBAL_PARENT'/>
<SEEALSOvalue='JSRESOLVE_ASSIGNING'/>
</ENTRY>
<ENTRYid='JSRESOLVE_ASSIGNING'>
<TYPEvalue='Macro'/>
<SUMMARY>
Flag that specifies that a function's identify can be uniquely resolved by examining the left side of an assignment statement.
</SUMMARY>
<SYNTAX>
JSRESOLVE_ASSIGNING
</SYNTAX>
<DESCRIPTION>
<C>JSRESOLVE_ASSIGNING</C> is a flag that, if included in a function's flags field, indicates that its identity can be uniquely resolved simply by examing the left side of an assignment statement.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSFUN_BOUND_METHOD'/>
<SEEALSOvalue='JSFUN_GLOBAL_PARENT'/>
<SEEALSOvalue='JSRESOLVE_QUALIFIED'/>
</ENTRY>
<ENTRYid='JSClass'>
<TYPEvalue='Data Structure'/>
<SUMMARY>
Defines a base class for use in building and maintaining JS objects.
</SUMMARY>
<SYNTAX>
struct JSClass {
char *name;
uint32 flags;
/* Mandatory non-null function pointer members. */
JSPropertyOp addProperty;
JSPropertyOp delProperty;
JSPropertyOp getProperty;
JSPropertyOp setProperty;
JSEnumerateOp enumerate;
JSResolveOp resolve;
JSConvertOp convert;
JSFinalizeOp finalize;
/* Optionally non-null members start here. */
JSGetObjectOps getObjectOps;
JSCheckAccessOp checkAccess;
JSNative call;
JSNative construct;
JSXDRObjectOp xdrObject;
JSHasInstanceOp hasInstance;
prword spare[2];
};
<PARAMname='*name'type='char'>
Class name<BR/>
</PARAM>
<PARAMname='flags'type='uint32'>
Class attributes. <C>0</C> indicates no attributes are set. Attributes can be one or both of the following values <C>OR</C>'d together:<BR/>
<C>JSCLASS_HAS_PRIVATE</C>: class can use private data.<BR/>
<C>JSCLASS_NEW_ENUMERATE</C>: class defines <C>getObjectOps</C> to point to a new method for enumerating properties.<BR/>
<C>JSCLASS_NEW_RESOLVE</C>: class defines <C>getObjectOps</C> to point to a new method for property resolution.<BR/>
</PARAM>
<PARAMname='addProperty'type='JSPropertyOp'>
Method for adding a property to the class.<BR/>
</PARAM>
<PARAMname='delProperty'type='JSPropertyOp'>
Method for deleting a property from the class.<BR/>
</PARAM>
<PARAMname='getProperty'type='JSPropertyOp'>
Method for getting a property value.<BR/>
</PARAM>
<PARAMname='setProperty'type='JSPropertyOp'>
Method for setting a property value.<BR/>
</PARAM>
<PARAMname='enumerate'type='JSEnumerateOp'>
Method for enumerating over class properties.<BR/>
</PARAM>
<PARAMname='resolve'type='JSResolveOp'>
Method for resolving property ambiguities.<BR/>
</PARAM>
<PARAMname='convert'type='JSConvertOp'>
Method for converting property values.<BR/>
</PARAM>
<PARAMname='finalize'type='JSFinalizeOp'>
Method for finalizing the class.<BR/>
</PARAM>
<PARAMname='getObjectOps'type='JSGetObjectOps'>
Pointer to an optional structure that defines method overrides for a class. If you do not intend to override the default methods for a class, set <C>getObjectOps</C> to <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='checkAccess'type='JSCheckAccessOp'>
Pointer to an optional custom access control method for a class or object operations structure. If you do not intend to provide custom access control, set this value to <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='call'type='JSNative'>
Pointer to the method for calling into the object that represents this class.<BR/>
</PARAM>
<PARAMname='construct'type='JSNative'>
Pointer to the constructor for the object that represents this <C>class</C><BR/>
</PARAM>
<PARAMname='xdrObject'type='JSXDRObjectOp'>
Pointer to an optional XDR object and its methods. If you do not use XDR, set this value to <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='hasInstance'type='JSHasInstanceOp'>
Pointer to an optional <C>hasInstance</C> method for this object. If you do not provide a method for <C>hasInstance</C>, set this pointer to <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='spare'type='prword'>
Reserved for future use.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
Use <C>JSClass</C> to define a base class used in object creation and manipulation. In your applications, you may use <C>JSClass</C> to declare a constructor function, base properties, methods, and attributes common to a series of objects you create.<P/>
By default, <C>JSClass</C> defines a set of default property access methods that can be used by all objects derived in whole or in part from the class. You can define <C>getObjectOps</C> to point to an optional <C>JSObjectOps</C> struct that contains pointers to an array of methods that override the default access methods. For more information about creating method overrides, see JSObjectOps.<P/>
<P/>
</DESCRIPTION>
<SEEALSOvalue='JSCLASS_HAS_PRIVATE'/>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_EnumerateStub'/>
<SEEALSOvalue='JS_ResolveStub'/>
<SEEALSOvalue='JS_ConvertStub'/>
<SEEALSOvalue='JS_FinalizeStub'/>
<SEEALSOvalue='JS_InitClass'/>
<SEEALSOvalue='JS_GetClass'/>
<SEEALSOvalue='JS_InstanceOf'/>
<SEEALSOvalue='JSObjectOps'/>
</ENTRY>
<ENTRYid='JSObjectOps'>
<TYPEvalue='Data Structure'/>
<SUMMARY>
Defines pointers to custom override methods for a class.
</SUMMARY>
<SYNTAX>
struct JSObjectOps {
/* mandatory non-null function pointer members. */
JSNewObjectMapOp newObjectMap;
JSObjectMapOp destroyObjectMap;
JSLookupPropOp lookupProperty;
JSDefinePropOp defineProperty;
JSPropertyIdOp getProperty;
JSPropertyIdOp setProperty;
JSAttributesOp getAttributes;
JSAttributesOp setAttributes;
JSPropertyIdOp deleteProperty;
JSConvertOp defaultValue;
JSNewEnumerateOp enumerate;
JSCheckAccessIdOp checkAccess;
/* Optionally non-null members. */
JSObjectOp thisObject;
JSPropertyRefOp dropProperty;
JSNative call;
JSNative construct;
JSXDRObjectOp xdrObject;
JSHasInstanceOp hasInstance;
prword spare[2];
};
<PARAMname='newObjectMap'type='JSNewObjectMapOp'>
Pointer to the function that creates the object map for a class. The object map stores property information for the object, and is created when the object is created. This pointer cannot be <C>NULL</C>.<BR/>
Pointer to the function that destroys the object map when it is no longer needed. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='lookupProperty'type='JSLookupPropOp'>
Pointer to a custom property lookup method for the object. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='defineProperty'type='JSDefinePropOp'>
Pointer to a custom property creation method for the object. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='getProperty'type='JSPropertyIdOp'>
Pointer to a custom property value retrieval method for the object. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='setProperty'type='JSPropertyIdOp'>
Pointer to a custom property value assignment method for the object. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='getAttributes'type='JSAttributesOp'>
Pointer to a custom property attributes retrieval method for the object. This pointer cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='setAttributes'type='JSAttributesOp'>
Pointer to a custom property attributes assignment method for this object. This property cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='deleteProperty'type='JSPropertyIdOp'>
Pointer to a custom method for deleting a property belonging to this object. This pointer cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='defaultValue'type='JSConvertOp'>
Pointer to a method for converting a property value. This pointer cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='enumerate'type='JSNewEnumerateOp'>
Pointer to a custom method for enumerating over class properties. This pointer cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='checkAccess'type='JSCheckAccessIdOp'>
Pointer to an optional custom access control method for a this object. This pointer cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='thisObject'type='JSObjectOp'>
Pointer to an optional custom method that retrieves this object. If you do not use this method, set <C>thisObject</C> to <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='dropProperty'type='JSPropertyRefOp'>
Pointer to an optional, custom reference-counting method that can be used to determine whether or not a property can be deleted safely.If you do not use reference counting, set <C>dropProperty</C> to <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='call'type='JSNative'>
Pointer to the method for calling into the object that represents this class.<BR/>
</PARAM>
<PARAMname='construct'type='JSNative'>
Pointer to the constructor for the object that represents this <C>class</C><BR/>
</PARAM>
<PARAMname='xdrObject'type='JSXDRObjectOp'>
Pointer to an optional XDR object and its methods. If you do not use XDR, set this value to <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='hasInstance'type='JSHasInstanceOp'>
Pointer to an optional <C>hasInstance</C> method for this object. If you do not provide an override method for <C>hasInstance</C>, set this pointer to <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='spare'type='prword'>
Reserved for future use.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
Use <C>JSObjectOps</C> to define an optional structure of pointers to custom property methods for a class. If you define <C>JSObjectOps</C>, you can create methods to override the default methods used by <C>JSClass</C>.<P/>
If you create a <C>JSObjectOps</C> structure for a given class, then you must also supply or create methods for creating and destroying the object map used by this object, and you must create custom methods for looking up, defining, getting, setting, and deleting properties. You must also create methods for getting and setting property attributes, checking object access privileges, converting property values, and enumerating properties. All other fields are optional, and if not used, should be set to <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSClass'/>
</ENTRY>
<ENTRYid='JSPropertySpec'>
<TYPEvalue='Data Structure'/>
<SUMMARY>
Defines a single property for an object.
</SUMMARY>
<SYNTAX>
struct JSPropertySpec {
const char *name;
int8 tinyid;
uint8 flags;
JSPropertyOp getter;
JSPropertyOp setter;
};
<PARAMname='*name'type='const char'>
Name to assign to the property.<BR/>
</PARAM>
<PARAMname='tinyid'type='int8'>
Unique ID number for the property to aid in resolving <C>getProperty</C> and <C>setProperty</C> method calls.<BR/>
</PARAM>
<PARAMname='flags'type='uint8'>
Property attributes. If <C>0</C>, no flags are set. Otherwise, the following attributes can be used singly or <C>OR</C>'d together:<BR/>
<C>JSPROP_ENUMERATE</C>: property is visible in for loops.<BR/>
<C>JSPROP_READONLY</C>: property is read-only.<BR/>
<C>JSPROP_PERMANENT</C>: property cannot be deleted.<BR/>
<C>JSPROP_EXPORTED</C>: property can be exported outside its object.<BR/>
<C>JSPROP_INDEX</C>: property is actual an array element.<BR/>
</PARAM>
<PARAMname='getter'type='JSPropertyOp'>
<C>getProperty</C> method for the property.<BR/>
</PARAM>
<PARAMname='setter'type='JSPropertyOp'>
<C>setProperty</C> method for the property. Read-only properties should not have a <C>setProperty</C> method.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JSPropertySpec</C> defines the attributes for a single JS property to associate with an object. Generally, you populate an array of <C>JSPropertySpec</C> to define all the properties for an object, and then call <C>JS_DefineProperties</C> to create the properties and assign them to an object.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSPROP_ENUMERATE'/>
<SEEALSOvalue='JSPROP_READONLY'/>
<SEEALSOvalue='JSPROP_PERMANENT'/>
<SEEALSOvalue='JSPROP_EXPORTED'/>
<SEEALSOvalue='JSPROP_INDEX'/>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_EnumerateStub'/>
<SEEALSOvalue='JS_ResolveStub'/>
<SEEALSOvalue='JS_ConvertStub'/>
<SEEALSOvalue='JS_FinalizeStub'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineProperties'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_GetProperty'/>
<SEEALSOvalue='JS_SetProperty'/>
<SEEALSOvalue='JS_DeleteProperty'/>
</ENTRY>
<ENTRYid='JSFunctionSpec'>
<TYPEvalue='Data Structure'/>
<SUMMARY>
Defines a single function for an object.
</SUMMARY>
<SYNTAX>
struct JSFunctionSpec {
const char *name;
JSNative call;
uint8 nargs;
uint8 flags;
uint16 extra;
};
<PARAMname='*name'type='const char'>
Name to assign to the function.<BR/>
</PARAM>
<PARAMname='call'type='JSNative'>
The built-in JS call wrapped by this function. If the function does not wrap a native JS call, set this value to <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='nargs'type='uint8'>
Number of arguments to pass to this function.<BR/>
</PARAM>
<PARAMname='flags'type='uint8'>
Function attributes. If set to <C>0</C> the function has no attributes. Otherwise, existing applications can set <C>flags</C> to either or both of the following attributes <C>OR</C>'d:<BR/>
<C>JSFUN_BOUND_METHOD</C><BR/>
<C>JSFUN_GLOBAL_PARENT</C><BR/>
Note that these attributes are deprecated, and continue to be supported only for backward compatibility with existing applications. New applications should not use these attributes.<BR/>
</PARAM>
<PARAMname='extra'type='uint16'>
Reserved for future use.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JSFuctionSpec</C> defines the attributes for a single JS function to associate with an object. Generally, you populate an array of <C>JSFunctionSpec</C> to define all the functions for an object, and then call <C>JS_DefineFunctions</C> to create the functions and assign them to an object.<P/>
<C>JSFunctionSpec</C> can also be used to define an array element rather than a named property. Array elements are actually individual properties. To define an array element, cast the element's index value to <B><C>const char*</C></B>, initialize the <C>name</C> field with it, and specify the <C>JSPROP_INDEX</C> attribute in <C>flags</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSFUN_BOUND_METHOD'/>
<SEEALSOvalue='JSFUN_GLOBAL_PARENT'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_GetFunctionName'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_CompileFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JSConstDoubleSpec'>
<TYPEvalue='Data Structure'/>
<SUMMARY>
Describes a double value and assigns it a name.
</SUMMARY>
<SYNTAX>
struct JSConstDoubleSpec {
jsdouble dval;
const char *name;
uint8 flags;
uint8 spare[3];
};
<PARAMname='dval'type='jsdouble'>
Value for the double.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name to assign the double.<BR/>
</PARAM>
<PARAMname='flags'type='uint8'>
Attributes for the double. Currently these can be 0 or more of the following values <C>OR</C>'d:<BR/>
<C>JSPROP_ENUMERATE</C>: property is visible in for loops.<BR/>
<C>JSPROP_READONLY</C>: property is read-only.<BR/>
<C>JSPROP_PERMANENT</C>: property cannot be deleted.<BR/>
<C>JSPROP_EXPORTED</C>: property can be exported outside its object.<BR/>
<C>JSPROP_INDEX</C>: property is actually an array element.<BR/>
</PARAM>
<PARAMname='spare'type='uint8'>
Reserved for future use.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JSConstDoubleSpecs</C> is typically used to define a set of double values that are assigned as properties to an object using <C>JS_DefineConstDoubles</C>. <C>JS_DefineConstDoubles</C> creates one or more double properties for a specified object.<P/>
<C>JS_DefineConstDoubles</C> takes an argument that is a pointer to an array of <C>JSConstDoubleSpecs</C>. Each array element defines a single property name and property value to create. The last element of the array must contain zero-valued values. <C>JS_DefineConstDoubles</C> creates one property for each non-zero element in the array.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSVAL_IS_DOUBLE'/>
<SEEALSOvalue='JSVAL_TO_DOUBLE'/>
<SEEALSOvalue='DOUBLE_TO_JSVAL'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewDoubleValue'/>
<SEEALSOvalue='JS_DefineConstDoubles'/>
</ENTRY>
<ENTRYid='JSPrincipals'>
<TYPEvalue='Data Structure'/>
<SUMMARY>
Defines security information for an object or script.
Flag indicating whether principals are enabled globally.<BR/>
</PARAM>
<PARAMname='refcount'type='uintN'>
Reference count for the principals. Each reference to a principal increments refcount by one. As principals references are dropped, call the <C>destroy</C> method to decrement the reference count and free the principals if they are no longer needed.<BR/>
</PARAM>
<PARAMname='*destroy'type='void'>
Pointer to the function that decrements the reference count and possibly frees the principals if they are no longer in use.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JSPrincipals</C> is a structure that defines the connection to security data for an object or script. Security data is defined independently of the JS engine, but is passed to the engine through the <C>JSPrincipals</C> structure. This structure is passed as an argument to versions of API calls that compile and evaluate scripts and functions that depend on a security model. Some examples of security-enhanced API call are <C>JS_CompileScriptForPrincipals</C>, <C>JS_CompileFunctionForPrincipals</C>, and <C>JS_EvaluateScriptForPrincipals</C>.<P/>
<C>codebase</C> points to the common codebase for this object or script. Only objects and scripts that share a common codebase can interact.<P/>
<C>getPrincipalArray</C> is a pointer to the function that retrieves the principals for this object or script.<P/>
<C>globalPrivilegesEnabled</C> is a flag that indicates whether principals are enabled globally.<P/>
<C>refcount</C> is used to maintain active principals. Each time an object is referenced, <C>refcount</C> must be increased by one. Each time an object is dereferenced, <C>refcount</C> must be decremented by one. When <C>refcount</C> is zero, the principals are no longer in use and are destroyed. Use the <C>JSPRINCIPALS_HOLD</C> macro to increment <C>refcount</C>, and use <C>JS_PRINCIPALS_DROP</C> to decrement <C>refcount</C>.<P/>
Describes the format of a JS error that is used either by the internal error reporting mechanism or by a user-defined error reporting mechanism.
</SUMMARY>
<SYNTAX>
struct JSErrorReport {
const char *filename;
uintN lineno;
const char *linebuf;
const char *tokenptr;
const jschar *uclinebuf;
const jschar *uctokenptr;
};
<PARAMname='*filename'type='const char'>
Indicates the source file or URL that produced the error condition. If <C>NULL</C>, the error is local to the script in the current HTML page.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number in the source that caused the error.<BR/>
</PARAM>
<PARAMname='*linebuf'type='const char'>
Text of the line that caused the error, minus the trailing newline character.<BR/>
</PARAM>
<PARAMname='*tokenptr'type='const char'>
Pointer to the error token in <C>*linebuf</C>.<BR/>
</PARAM>
<PARAMname='*uclinebuf'type='const jschar'>
Unicode line buffer. This is the buffer that contains the original data.<BR/>
</PARAM>
<PARAMname='*uctokenptr'type='const jschar'>
Pointer to the error token in <C>*uclinebuf</C>.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JSErrorReport</C> describes a single error that occurs in the execution of script.<P/>
In the event of an error, <C>filename</C> will either contain the name of the external source file or URL containing the script (<C>SCRIPT SRC=</C>) or <C>NULL</C>, indicating that a script embedded in the current HTML page caused the error.<P/>
<C>lineno</C> indicates the line number of the script containing the error. In the case of an error in a script embedded in the HTML page, <C>lineno</C> indicates the HTML lineno where the script error is located.<P/>
<C>linebuf</C> is a pointer to a user-defined buffer into which JS copies the offending line of the script.<P/>
<C>tokenptr</C> is a pointer into <C>linebuf</C> that identifies the precise location line of the problem within the offending line.<P/>
<C>uclinebuf</C> is a pointer to a user-defined buffer into which JS copies the Unicode (original) version of the offending line of script.<P/>
<C>uctokenptr</C> is a pointer into <C>uclinebuf</C> that identifies the precise location line of the problem within the offending Unicode (original) version of the offending line.<P/>
To use <C>JSErrorReport</C>, your application must define a variable of type <C>JSErrorReport</C> and allocate a buffer to hold the text that generated the error condition. Set <C>linebuf</C> to point at the buffer before your application executes a script. For Unicode scripts, define a second buffer that holds the Unicode version of the text the generated the error. For application that do not use Unicode, set <C>uclinebuf</C> and <C>uctokenptr</C> to <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ReportError'/>
<SEEALSOvalue='JS_ReportOutOfMemory'/>
<SEEALSOvalue='JS_SetErrorReporter'/>
</ENTRY>
<ENTRYid='JSIdArray'>
<TYPEvalue='Data Structure'/>
<SUMMARY>
Internal use only. Describes an array of property IDs to associated with an object.
</SUMMARY>
<SYNTAX>
struct JSIdArray {
jsint length;
jsid vector[1];
};
</SYNTAX>
<DESCRIPTION>
<C>JSIdArray</C> is used internally by the JS engine to hold IDs for enumerated properties associated with an object.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSProperty'/>
</ENTRY>
<ENTRYid='JSProperty'>
<TYPEvalue='Data Structure'/>
<SUMMARY>
Internal use only. Describes a single ID value for a JS property.
</SUMMARY>
<SYNTAX>
struct JSProperty {
jsid id;
};
</SYNTAX>
<DESCRIPTION>
<C>JSProperty</C> is used by the JS engine to hold a unique ID to a property belonging to an object.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSIdArray'/>
</ENTRY>
<ENTRYid='JS_GetNaNValue'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the numeric representation for not-a-number (NaN).
</SUMMARY>
<SYNTAX>
jsval JS_GetNaNValue(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetNanValue</C> retrieves a numeric representation of <C>NaN</C> given a specific JS context, <C>cx</C>. <C>JS_GetNaNValue</C> returns a JS value that corresponds to the IEEE floating point quiet NaN value.<P/>
<C>NaN</C> is typically used in JavaScript to represent numbers that fall outside the valid range for integer or double values. <C>NaN</C> can also be used in error conditions to represent a numeric value that falls outside a prescribed programmatic range, such as an input value for a month variable that is not between 1 and 12.<P/>
Comparing <C>NaN</C> to any other numeric value or to itself always results in an unequal comparison.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetNegativeInfinityValue'/>
<SEEALSOvalue='JS_GetPositiveInfinityValue'/>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
</ENTRY>
<ENTRYid='JS_GetNegativeInfinityValue'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the negative infinity representation.
</SUMMARY>
<SYNTAX>
jsval JS_GetNegativeInfinityValue(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetNegativeInfinityValue</C> retrieves a numeric representation of negative-infinity, given a specific JS context, <C>cx</C>. <C>JS_GetNegativeInfinityValue</C> returns a JS value.<P/>
Negative infinity is typically used in JavaScript to represent numbers that are smaller than the minimum valid integer or double value. <P/>
As a value in mathematical calculations, negative infinity behaves like infinity. For example, anything multiplied by infinity is infinity, and anything divided by infinity is zero.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetNaNValue'/>
<SEEALSOvalue='JS_GetPositiveInfinityValue'/>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
</ENTRY>
<ENTRYid='JS_GetPositiveInfinityValue'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the numeric representation of infinity.
</SUMMARY>
<SYNTAX>
jsval JS_GetPositiveInfinityValue(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetPositiveInfinityValue</C> retrieves the numeric representation of infinity. <C>JS_GetPositiveInfinityValue</C> returns a JS value.<P/>
The infinity representation is typically used in JavaScript to represent numbers that are larger than the maximum valid integer or double value. <P/>
As a value in mathematical calculations infinite values behaves like infinity. For example, anything multiplied by infinity is infinity, and anything divided by infinity is zero.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetNaNValue'/>
<SEEALSOvalue='JS_GetNegativeInfinityValue'/>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
</ENTRY>
<ENTRYid='JS_GetEmptyStringValue'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the representation of an empty string.
</SUMMARY>
<SYNTAX>
jsval JS_GetEmptyStringValue(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetEmptyStringValue</C> retrieves the empty string value.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetNaNValue'/>
<SEEALSOvalue='JS_GetNegativeInfinityValue'/>
<SEEALSOvalue='JS_GetPositiveInfinityValue'/>
</ENTRY>
<ENTRYid='JS_ConvertArguments'>
<TYPEvalue='Function'/>
<SUMMARY>
Converts a series of JS values, passed in an argument array, to their corresponding JS types.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='argc'type='uintN'>
The number of arguments to convert.<BR/>
</PARAM>
<PARAMname='argv'type='jsval *'>
Pointer to the vector of arguments to convert.<BR/>
</PARAM>
<PARAMname='format'type='char *'>
Character array containing the recognized format to which to convert<BR/>
</PARAM>
<PARAMname='...'type='void *'>
A variable number of pointers into which to store the converted types. There should be one pointer for each converted value.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ConvertArguments</C> provides a convenient way to translate a series of JS values into their corresponding JS types with a single function call. It saves you from having to write separate tests and elaborate <B><C>if...else</C></B> statements in your function code to retrieve and translate multiple JS values for use with your own functions.<P/>
<C>cx</C> is the context for the call. <C>argc</C> indicates the number of JS values you are passing in for conversion. <C>argv</C> is a pointer to the array of JS values to convert.<P/>
<C>format</C> is a sequential character array, where each element of the array indicates the JS type into which to convert the next available JS value. <C>format</C> can contain one or more instances of the following characters, as appropriate:
<![CDATA[
<TABLEBORDER="0">
<TR><TDVALIGN='baseline'ALIGN='left'>
<B>Character
</B></TD><TDVALIGN='baseline'ALIGN='left'>
<B>Corresponding JS type to which to convert the value
None. If a slash (/) is present in <CODE>format</CODE>, it tells the conversion routine to turn off checking that the argument vector was passed to JS_ConvertArguments from a valid native JS function.</P>
</TD></TR></TABLE >
]]>
<P/>
For example, if <C>format</C> is "<C>bIfb</C>", then <C>JS_ConvertArguments</C> converts the first JS value in argv into a <C>JSBool</C>, the second value into a <C>jsdouble</C>, the third value into a <C>JSObject</C>, and the last value into a <C>JSBool</C>.<P/>
To skip a given argument, pass an asterisk in the corresponding position in <C>format</C>.<P/>
<C>JS_ConvertArguments</C> expects to be passed an argument vector that belongs to a native JS function, such that every argument passed is already a JS value. By default, when you first call <C>JS_ConvertArguments</C>, it automatically provides built-in error checking to guarantee that the proper number of arguments has been passed. If an improper number of arguments is passed in, <C>JS_ConvertArguments</C> reports an error and terminates. You can turn off this error-checking at any time by passing a slash (/) as a character any place in format where you no longer desire the argument number check to be made.<P/>
When you call <C>JS_ConvertArguments</C>, the arguments you pass in after <C>format</C> must be a series of pointers to storage. You must allocate one storage pointer for each converted value you expect.<P/>
If <C>JS_ConvertArgument</C> successfully converts all arguments, it returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_ValueToECMAInt32'/>
<SEEALSOvalue='JS_ValueToECMAUint32'/>
<SEEALSOvalue='JS_ValueToUint16'/>
<SEEALSOvalue='JS_ValueToBoolean'/>
<SEEALSOvalue='JS_ValueToId'/>
</ENTRY>
<ENTRYid='JS_ConvertValue'>
<TYPEvalue='Function'/>
<SUMMARY>
Converts a JS value to a value of a specific JS type.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAMname='type'type='JSType'>
The type to which to convert the value. type must be one of <C>JSTYPE_VOID</C>, <C>JSTYPE_OBJECT</C>, <C>JSTYPE_FUNCTION</C>, <C>JSTYPE_STRING</C>, <C>JSTYPE_NUMBER</C>, or <C>JSTYPE_BOOLEAN</C>. Otherwise <C>JS_ConvertValue</C> reports an error.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to the JS value that contains the converted value when the function returns.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ConvertValue</C> converts a specified JS value, v, to a specified JS type, <C>type</C>. The converted value is stored in the <C>jsval</C> pointed to by <C>vp</C>. Typically users of this function set <C>vp</C> to point to <C>v</C>, so that if conversion is successful, <C>v</C> now contains the converted value.<P/>
<C>JS_ConvertValue</C> calls other, type-specific conversion routines based on what you specify in type. These include <C>JS_ValueToFunction</C>, <C>JS_ValueToString</C>, <C>JS_ValueToNumber</C>, and <C>JS_ValueToBoolean</C>.<P/>
Converting any JS value to <C>JSTYPE_VOID</C> always succeeds.<P/>
Converting to <C>JSTYPE_OBJECT</C> is successful if the JS value to convert is one of <C>JSVAL_INT</C>, <C>JSVAL_DOUBLE</C>, <C>JSVAL_STRING</C>, <C>JSVAL_BOOLEAN</C>, or <C>JSVAL_OBJECT</C>.<P/>
Converting to <C>JSTYPE_FUNCTION</C> is successful if the JS value to convert is an object for which a function class has been defined, or if the JS value is already a function.<P/>
Converting any JS value to <C>JSTYPE_STRING</C> always succeeds.<P/>
Converting a JS value to <C>JSTYPE_NUMBER</C> succeeds if the JS value to convert is a <C>JSVAL_INT</C>, <C>JSVAL_DOUBLE</C>, or <C>JSVAL_BOOLEAN</C>. If the JS value is a <C>JSVAL_STRING</C> that contains numeric values and signs only, conversion also succeeds. If the JS value is a <C>JSVAL_OBJECT</C>, conversion is successful if the object supports its own conversion function.<P/>
Converting any JS value to <C>JSTYPE_BOOLEAN</C> always succeeds, except when the JS value is a <C>JSVAL_OBJECT</C> that does not support its own conversion routine.<P/>
If the conversion is successful, <C>JS_ConvertValue</C> returns <C>JS_TRUE</C>, and vp points to the converted value. Otherwise, it returns <C>JS_FALSE</C>, and <C>vp</C> is either undefined, or points to the current value of v, depending on how you implement your code.<P/>
</DESCRIPTION>
<NOTE>
Converting a JS value from one type to another does not change the actual data
value stored in the item.
<P/>
</NOTE>
<SEEALSOvalue='JS_ConvertArguments'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_ValueToBoolean'/>
<SEEALSOvalue='JS_TypeOfValue'/>
<SEEALSOvalue='JS_GetTypeName'/>
</ENTRY>
<ENTRYid='JS_ValueToObject'>
<TYPEvalue='Function'/>
<SUMMARY>
Converts a JS value to a JS object.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToObject(JSContext *cx, jsval v,
JSObject **objp);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAMname='objp'type='JSObject **'>
Pointer to the JS object into which to store the converted value.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToObject</C> converts a specified JS value, <C>v</C>, to a JS object. The converted object is stored in the object pointed to by <C>objp</C>. If the conversion is successful, <C>JS_ValueToObject</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
You can successfully convert a JS value to an object if the JS value to convert is one of <C>JSVAL_INT</C>, <C>JSVAL_DOUBLE</C>, <C>JSVAL_STRING</C>, <C>JSVAL_BOOLEAN</C>, or <C>JSVAL_OBJECT</C>. Note that if <C>v</C> is already an object, the object returned in <C>objp</C> represents a converted version of <C>v</C>, rather than original version of <C>v</C>.<P/>
</DESCRIPTION>
<NOTE>
Converting a JS value to an object subjects the resulting object to garbage
collection unless you protect against it using a local root, an object property, or
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToFunction</C> converts a specified JS value, <C>v</C>, to a JS function. The actual conversion is performed by the object's convert operation. <C>JS_ValueToFunction</C> returns a pointer to the converted function.<P/>
Converting a JS value to a function succeeds if the value is an object for which a function class has been defined, or if the JS value is already a function. If conversion fails, <C>JS_ValueToFunction</C> returns <C>NULL</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToString</C> converts a specified JS value, <C>v</C>, to a JS string. The actual conversion is performed by the object's convert operation. <C>JS_ValueToString</C> always returns a pointer to a string. The original value is untouched.<P/>
</DESCRIPTION>
<NOTE>
Converting a JS value to a string subjects the resulting string to garbage
collection unless you protect against it using a local root, an object property, or
the <C>JS_AddRoot</C> function.
<P/>
</NOTE>
<SEEALSOvalue='JS_ConvertArguments'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_ValueToBoolean'/>
<SEEALSOvalue='JS_TypeOfValue'/>
<SEEALSOvalue='JS_GetTypeName'/>
<SEEALSOvalue='JS_AddRoot'/>
</ENTRY>
<ENTRYid='JS_ValueToNumber'>
<TYPEvalue='Function'/>
<SUMMARY>
Converts a JS value to a JS double.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToNumber(JSContext *cx, jsval v,
jsdouble *dp);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAMname='dp'type='jsdouble *'>
Pointer to the JS value that contains the converted double when the function returns.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToNumber</C> converts a specified JS value, <C>v</C>, to a JS double. The converted value is stored in the <C>jsdouble</C> pointed to by <C>dp</C>.<P/>
You can convert a JS value to a number if the JS value to convert is a <C>JSVAL_INT</C>, <C>JSVAL_DOUBLE</C>, or <C>JSVAL_BOOLEAN</C>. If the JS value is a <C>JSVAL_STRING</C> that contains numeric values and signs only, conversion also succeeds. If the JS value is a <C>JSVAL_OBJECT</C>, conversion is successful if the object's convert operation returns a primitive value that can be converted.<P/>
When conversion is successful, <C>JS_ValueToNumber</C> returns <I><C>JS_TRUE</C></I>. Otherwise, it reports an error and returns <I><C>JS_FALSE</C></I>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAMname='ip'type='int32 *'>
Pointer to the JS value that contains the converted integer when the function returns.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToInt32</C> converts a specified JS value, <C>v</C>, to a JS double, and then to a 32-bit integer, if it fits. If the double is out of range, <C>JS_ValueToInt32</C> reports an error and conversion fails. The double rounded to the nearest integer value.<P/>
The actual conversion is performed by the object's convert operation. The converted value is stored in the <C>int32</C> pointed to by <C>ip</C>.<P/>
You can convert a JS value to an integer if the JS value to convert is a <C>JSVAL_INT</C>, <C>JSVAL_DOUBLE</C>, or <C>JSVAL_BOOLEAN</C>. If the JS value is a <C>JSVAL_STRING</C> that contains numeric values and signs only, conversion also succeeds. If the JS value is a <C>JSVAL_OBJECT</C>, conversion is successful if the object's convert operation returns a primitive value that can be converted.<P/>
If the conversion is successful, <C>JS_ValueToInt32</C> returns <I><C>JS_TRUE</C></I>. Otherwise, it reports an error and returns <I><C>JS_FALSE</C></I>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ConvertArguments'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToBoolean'/>
<SEEALSOvalue='JS_TypeOfValue'/>
<SEEALSOvalue='JS_GetTypeName'/>
<SEEALSOvalue='JS_AddRoot'/>
</ENTRY>
<ENTRYid='JS_ValueToECMAInt32'>
<TYPEvalue='Function'/>
<SUMMARY>
Converts a JS value to an ECMA-compliant 32-bit integer.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAMname='ip'type='int32 *'>
Pointer to the JS value that contains the converted integer when the function returns.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToECMAInt32</C> converts a JS value, <C>v</C>, to a JS double, and then to an ECMA-standard, 32-bit, signed integer. The fractional portion of the double is dropped silently during conversion to an integer value. If the double is out of range, the result is computed modulo 2**32; if the result is then greater than or equal to 2**31, this function subtracts 2**32, yielding a negative result.<P/>
You can convert a JS value to an integer if the JS value to convert is a <C>JSVAL_INT</C>, <C>JSVAL_DOUBLE</C>, or <C>JSVAL_BOOLEAN</C>. If the JS value is a <C>JSVAL_STRING</C> that contains a well formed numeric literal (ignoring leading and trailing whitespace) conversion also succeeds. If the JS value is a <C>JSVAL_OBJECT</C>, conversion is successful if the object's convert operation returns a primitive value that can be converted.<P/>
If the conversion is successful, <C>JS_ValueToECMAInt32</C> returns <I><C>JS_TRUE</C></I>. Otherwise, it reports an error and returns <I><C>JS_FALSE</C></I>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ConvertArguments'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_ValueToECMAUint32'/>
<SEEALSOvalue='JS_ValueToUint16'/>
<SEEALSOvalue='JS_ValueToBoolean'/>
<SEEALSOvalue='JS_ValueToId'/>
</ENTRY>
<ENTRYid='JS_ValueToECMAUint32'>
<TYPEvalue='Function'/>
<SUMMARY>
Converts a JS value to an ECMA-compliant, unisgned 32-bit integer.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAMname='ip'type='uint32 *'>
Pointer to the JS value that contains the converted integer when the function returns.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToECMAUint32</C> converts a JS value, <C>v</C>, to a JS double, and then to an ECMA-standard, 32-bit, signed integer. The fractional portion of the double is dropped silently during conversion to an integer value. If the double is out of range, the result is computed modulo 2**32.<P/>
You can convert a JS value to an integer if the JS value to convert is a <C>JSVAL_INT</C>, <C>JSVAL_DOUBLE</C>, or <C>JSVAL_BOOLEAN</C>. If the JS value is a <C>JSVAL_STRING</C> that contains a well formed numeric literal (ignoring leading and trailing whitespace) conversion also succeeds. If the JS value is a <C>JSVAL_OBJECT</C>, conversion is successful if the object's convert operation returns a primitive value that can be converted.<P/>
If the conversion is successful, <C>JS_ValueToECMAInt32</C> returns <I><C>JS_TRUE</C></I>, and <C>ip</C> contains a pointer to the converted value. Otherwise, it reports an error and returns <I><C>JS_FALSE</C></I>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ConvertArguments'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_ValueToECMAInt32'/>
<SEEALSOvalue='JS_ValueToUint16'/>
<SEEALSOvalue='JS_ValueToBoolean'/>
<SEEALSOvalue='JS_ValueToId'/>
</ENTRY>
<ENTRYid='JS_ValueToUint16'>
<TYPEvalue='Function'/>
<SUMMARY>
Converts a JS value to an unsigned, 16-bit integer.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAMname='ip'type='uint16 *'>
Pointer to the JS value that contains the converted integer when the function returns.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToUint16</C> converts a specified JS value, <C>v</C>, to a JS double, and then to a 16-bit integer, if it fits. The fractional portion of the double is dropped silently during conversion to an integer value. If the double is out of range, <C>JS_ValueToUint16</C> reports an error and conversion fails. The converted value is stored in the <C>uint16</C> pointed to by <C>ip</C>.<P/>
You can convert a JS value to an integer if the JS value to convert is a <C>JSVAL_INT</C>, <C>JSVAL_DOUBLE</C>, or <C>JSVAL_BOOLEAN</C>. If the JS value is a <C>JSVAL_STRING</C> that contains numeric values and signs only, conversion also succeeds. If the JS value is a <C>JSVAL_OBJECT</C>, conversion is successful if the object supports its own conversion function.<P/>
If the conversion is successful, <C>JS_ValueToInt32</C> returns <I><C>JS_TRUE</C></I>. Otherwise, it reports an error and returns <I><C>JS_FALSE</C></I>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ConvertArguments'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_ValueToECMAInt32'/>
<SEEALSOvalue='JS_ValueToECMAUint32'/>
<SEEALSOvalue='JS_ValueToBoolean'/>
<SEEALSOvalue='JS_ValueToId'/>
</ENTRY>
<ENTRYid='JS_ValueToBoolean'>
<TYPEvalue='Function'/>
<SUMMARY>
Converts a JS value to a JS Boolean.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToBoolean(JSContext *cx, jsval v,
JSBool *bp);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAMname='bp'type='JSBool *'>
Pointer to the JS value that contains the converted Boolean when the function returns.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToBoolean</C> converts a specified JS value, <C>v</C>, to a JS Boolean. The actual conversion is performed by the object's convert operation. Converting any JS value to a Boolean always succeeds, except when the JS value is a <C>JSVAL_OBJECT</C> that does not support its own conversion routine.<P/>
The converted value is stored in the <C>JSBool</C> pointed to by <C>bp</C>. If the conversion is successful, <C>JS_ValueToBoolean</C> returns <C>JS_TRUE</C>. If the value to convert is an empty string, or conversion is unsuccesful, <C>JS_ValueToBoolean</C> returns <C>JS_FALSE</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAMname='idp'type='jsid *'>
Pointer to the JS ID that contains the converted value when the function returns.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ValueToId</C> converts a specified JS value, <C>v</C>, to a JS ID. If <C>v</C> already contains a <C>JS_INT</C> value, <C>idp</C> is set to point at <C>v</C>. Otherwise, <C>JS_ValueToId</C> attempts to generate an ID value based on the current value of <C>v</C>.<P/>
The converted value is stored in the <C>jsid</C> pointed to by <C>idp</C>. If the conversion is successful, <C>JS_ValueToId</C> returns <C>JS_TRUE</C>. Otherwise, it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ConvertArguments'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_TypeOfValue'/>
<SEEALSOvalue='JS_GetTypeName'/>
<SEEALSOvalue='JS_IdToValue'/>
</ENTRY>
<ENTRYid='JS_IdToValue'>
<TYPEvalue='Function'/>
<SUMMARY>
Converts a JS ID to a JS value.
</SUMMARY>
<SYNTAX>
JSBool JS_IdToValue(JSContext *cx, jsval v,
JSBool *bp);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='id'type='jsid'>
The JS ID to convert.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to the JS value that contains the converted ID when the function returns.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_IdToValue</C> converts a specified JS ID, <C>id</C>, to a JS value. The converted value is stored in the <C>jsval</C> pointed to by <C>vp</C>. If the conversion is successful, <C>JS_IdToValue</C> returns <C>JS_TRUE</C>. Otherwise, it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_ValueToId'/>
<SEEALSOvalue='JS_TypeOfValue'/>
<SEEALSOvalue='JS_GetTypeName'/>
</ENTRY>
<ENTRYid='JS_TypeOfValue'>
<TYPEvalue='Function'/>
<SUMMARY>
Determines the JS data type of a JS value.
</SUMMARY>
<SYNTAX>
JSType JS_TypeOfValue(JSContext *cx, jsval v);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='v'type='jsval'>
The JS value to examine.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_TypeOfValue</C> examines a specified JS value, <C>v</C>, and returns its JS data type. The return value is always one of <C>JSTYPE_VOID</C>, <C>JSTYPE_OBJECT</C>, <C>JSTYPE_FUNCTION</C>, <C>JSTYPE_STRING</C>, <C>JSTYPE_NUMBER</C>, or <C>JSTYPE_BOOLEAN</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_ValueToBoolean'/>
<SEEALSOvalue='JS_GetTypeName'/>
</ENTRY>
<ENTRYid='JS_GetTypeName'>
<TYPEvalue='Macro'/>
<SUMMARY>
Function. Returns a pointer to the string literal description of a specified JS data type.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='type'type='JSType'>
The JS value to examine. <C>type</C> is one of <C>JSTYPE_VOID</C>, <C>JSTYPE_OBJECT</C>, <C>JSTYPE_FUNCTION</C>, <C>JSTYPE_STRING</C>, <C>JSTYPE_NUMBER</C>, or <C>JSTYPE_BOOLEAN</C>.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetTypeName</C> returns a pointer to a string literal description of a specified JS data type, <C>type</C>. The following table lists <C>JSType</C>s and the string literals reported by <C>JS_GetTypeName</C>:
Any other value</TD><TDVALIGN='baseline'ALIGN='left'><P>
<CODE>NULL</CODE></P>
</TD></TR></TABLE >
]]>
<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ValueToNumber'/>
<SEEALSOvalue='JS_ValueToInt32'/>
<SEEALSOvalue='JS_ValueToBoolean'/>
<SEEALSOvalue='JS_TypeOfValue'/>
</ENTRY>
<ENTRYid='JS_Init'>
<TYPEvalue='Function'/>
<SUMMARY>
Deprecated. Initializes the JavaScript runtime.
</SUMMARY>
<SYNTAX>
JSRuntime * JS_Init(uint32 maxbytes);
</SYNTAX>
<DESCRIPTION>
<C>JS_Init</C> is a deprecated function that initializes the JavaScript runtime environment. Use <C>JS_NewRuntime</C> instead of this function.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewRuntime'/>
<SEEALSOvalue='JS_DestroyRuntime'/>
<DEPRECATED/>
</ENTRY>
<ENTRYid='JS_Finish'>
<TYPEvalue='Function'/>
<SUMMARY>
Deprecated. Frees the JavaScript runtime.
</SUMMARY>
<SYNTAX>
void JS_Finish(JSRuntime *rt);
</SYNTAX>
<DESCRIPTION>
<C>JS_Finish</C> is a deprecated function that frees the specified the JavaScript runtime environment, <C>rt</C>. Use <C>JS_DestroyRuntime</C> instead of this function.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_DestroyRuntime'/>
<SEEALSOvalue='JS_NewRuntime'/>
<DEPRECATED/>
</ENTRY>
<ENTRYid='JS_Lock'>
<TYPEvalue='Function'/>
<SUMMARY>
Locks the JS run-time environment.
</SUMMARY>
<SYNTAX>
void JS_Lock(JSRuntime *rt);
</SYNTAX>
<DESCRIPTION>
<C>JS_Lock</C> is an empty, API hook function for developers so that they provide an exclusive locking mechanism for the <C>JSRuntime</C> on a specific platform or for a specific application. Developers must create their own locking function that takes a single argument, <C>rt</C>, the JS run-time environment to lock. Locking the runtime protects critical sections in a threaded environment. After performing one or more exclusive lock operations, the runtime should be unlocked with a call to <C>JS_Unlock</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_Unlock'/>
<SEEALSOvalue='JS_GetRuntime'/>
</ENTRY>
<ENTRYid='JS_Unlock'>
<TYPEvalue='Function'/>
<SUMMARY>
Unlocks a previously locked JS run-time environment.
</SUMMARY>
<SYNTAX>
void JS_Unlock(JSRuntime *rt);
<PARAMname='*rt'type='JSRuntime'>
Pointer to a previously established JS run-time environment with which to associate this context.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_Unlock</C> is an empty, API hook function for developers so that they can provide a mechanism for unlocking the JS run-time environment after having previously locked it with a call to <C>JS_Lock</C>. Developers must create their own unlocking function that takes a single argument, <C>rt</C>, the JS run-time environment to unlock. <C>JS_Unlock</C> must undo the actions taken by the developer's implementation of <C>JS_Lock</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_Lock'/>
<SEEALSOvalue='JS_GetRuntime'/>
</ENTRY>
<!-- XXXXXXXXXXXXXXXXXXX -->
<ENTRYid='JS_SetContextThread'>
<TYPEvalue='Function'/>
<SUMMARY>
Associate a context with the current thread. No other thread should use
the context while the association lasts.
</SUMMARY>
<SYNTAX>
intN JS_SetContextThread(JSContext *cx);
<PARAMname='*cx'type='JSContext'>
Pointer to a previously established JS context.
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetContextThread</C> ties <C>cx</C> to the current thread for
exclusive use. No other thread should attempt to use <C>cx</C> until this
association is removed. Use <C>JS_ClearContextThread</C> to break the
tie.
<P/>
<C>JS_SetContextThread</C> returns the thread ID of the last thread to
be associated with this context.
</DESCRIPTION>
<NOTE>
<C>JS_NewContext</C> performs a <C>JS_SetContextThread</C> implicitly.
</NOTE>
<NOTE>
<C>JS_SetContextThread</C> is available only if the engine is built
with <C>JS_THREADSAFE</C>.
</NOTE>
<SEEALSOvalue='JS_GetContextThread'/>
</ENTRY>
<!-- XXXXXXXXXXXXXXXXXXX -->
<ENTRYid='JS_ClearContextThread'>
<TYPEvalue='Function'/>
<SUMMARY>
Removes the association between a context and the current thread.
</SUMMARY>
<SYNTAX>
intN JS_ClearContextThread(JSContext *cx);
<PARAMname='*cx'type='JSContext'>
Pointer to a previously established JS context.
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ClearContextThread</C> clears any tie <C>cx</C> had with a thread.
The context should not be used until it as associated with another thread
via <C>JS_SetContextThread</C>.
<P/>
<C>JS_ClearContextThread</C> returns the thread ID of the last thread to
be associated with this context.
</DESCRIPTION>
<NOTE>
<C>JS_ClearContextThread</C> is available only if the engine is built
with <C>JS_THREADSAFE</C>.
</NOTE>
<SEEALSOvalue='JS_GetContextThread'/>
</ENTRY>
<!-- XXXXXXXXXXXXXXXXXXX -->
<ENTRYid='JS_GetContextThread'>
<TYPEvalue='Function'/>
<SUMMARY>
Returns the ID of the associated thread for a context.
</SUMMARY>
<SYNTAX>
intN JS_GetContextThread(JSContext *cx);
<PARAMname='*cx'type='JSContext'>
Pointer to a previously established JS context.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetContextThread</C> returns the ID of the thread currently
associated with this context.
</DESCRIPTION>
<NOTE>
<C>JS_GetContextThread</C> is available only if the engine is built
Pointer to a previously established JS run-time environment with which to associate this context.<BR/>
</PARAM>
<PARAMname='stacksize'type='size_t'>
The size, in bytes, of the execution stack space to allocate for the context.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewContext</C> creates a new JavaScript context for an executing script or thread. Each script or thread is associated with its own context, and each context must be associated with a specified <C>JSRuntime</C>, <C>rt</C>. A context specifies a stack size for the script, the amount, in bytes, of private memory to allocate to the execution stack for the script.<P/>
Generally you use <C>JS_NewContext</C> to generate a context for each separate script in a HTML page or frame.<P/>
</DESCRIPTION>
<NOTE>
Once established, a context can be used any number of times for different
scripts or threads so long as it's associated via
<C>JS_SetContextThread</C> with only one thread at a time.
<P/>
</NOTE>
<DESCRIPTION>
If a call to <C>JS_NewContext</C> is successful, it returns a pointer to the new context. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_DestroyContext'/>
<SEEALSOvalue='JS_ContextIterator'/>
</ENTRY>
<ENTRYid='JS_DestroyContext'>
<TYPEvalue='Function'/>
<SUMMARY>
Frees a specified <C>JSContext</C>.
</SUMMARY>
<SYNTAX>
void JS_DestroyContext(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_DestroyContext</C> frees the stack space allocated to a previously created JS context, <C>cx</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewContext'/>
<SEEALSOvalue='JS_ContextIterator'/>
</ENTRY>
<ENTRYid='JS_GetRuntime'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves a pointer to the <C>JSRuntime</C>.
</SUMMARY>
<SYNTAX>
JSRuntime *) JS_GetRuntime(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetRuntime</C> retrieves a pointer to the <C>JSRuntime</C> with which a specified <C>JSContext</C>, <C>cx</C>, is associated. All contexts are associated with a particular <C>JSRuntime</C> when they are first created; <C>JS_GetRuntime</C> provides a convenient, programmatic way to look up the association.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_Init'/>
<SEEALSOvalue='JS_Lock'/>
<SEEALSOvalue='JS_Unlock'/>
<SEEALSOvalue='JS_NewContext'/>
<SEEALSOvalue='JS_Finish'/>
</ENTRY>
<ENTRYid='JS_ContextIterator'>
<TYPEvalue='Function'/>
<SUMMARY>
Cycles through the JS contexts associated with a particular <C>JSRuntime</C>.
</SUMMARY>
<SYNTAX>
JSContext * JS_ContextIterator(JSRuntime *rt,
JSContext **iterp);
<PARAMname='rt'type='JSRuntime *'>
Pointer to a previously established JS run-time environment with which script contexts to iterate through are associated.<BR/>
</PARAM>
<PARAMname='iterp'type='JSContext **'>
Pointer to a JS context pointer that holds current context when <C>JS_ContextIterator</C> is called, and that on return holds the next context to call with a subsequent call to the iterator.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ContextIterator</C> enables you to cycle through all the executable script contexts associated with a specified JS run-time environment, <C>rt</C>. Each call to <C>JS_ContextIterator</C> cycles from the current context to the previous context.<P/>
The first time you call <C>JS_ContextIterator</C>, <C>iterp</C> can point to a null-valued context pointer, or it can point to a known context pointer associated with the specified runtime. If you point <C>iterp</C> at a null-valued context pointer, the function automatically determines the first executable script context for the runtime, and makes it the "current" context for the function. If you set <C>iterp</C> to a valid context pointer, that context becomes the "current" context. If the "current" context matches the starting address of the runtime environment's context list, then there are no context established, and <C>JS_ContextIterator</C> returns <C>NULL</C>. Otherwise <C>JS_ContextIterator</C> points <C>iterp</C> to the previous context pointer in the context chain, and returns that pointer.<P/>
In effect, by making repeated calls to <C>JS_ContextIterator</C> you can cycle through all executable script contexts for a given runtime, and perform common operations on each them.<P/>
</DESCRIPTION>
<EXAMPLEdesc='The following code snippet illustrates how to cycle through the contexts for a given context:'>
JSContext **cxArray, *acx;
JSContext *iterp = NULL;
int i;i = 0;
while ((acx = JSContextIterator(rt, &iterp)) != NULL)
{
printf("%d ". ++1);
}
</EXAMPLE>
<SEEALSOvalue='JS_NewContext'/>
<SEEALSOvalue='JS_DestroyContext'/>
</ENTRY>
<ENTRYid='JS_GetVersion'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the JavaScript version number used within a specified executable script context.
</SUMMARY>
<SYNTAX>
JSVersion JS_GetVersion(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetVersion</C> reports an encapsulated JavaScript version number used within a specified <C>JSContext</C>, <C>cx</C>. The version number is an enumerated value that corresponds to the JavaScript version string with which JS users are familiar.<P/>
The following table lists possible values reported by <C>JS_GetVersion</C>, the enumerated value you can use for the JS version in your code, and provides a translation to the actual JavaScript version string:
If <C>JSVERSION_DEFAULT</C> is returned by <C>JS_GetVersion</C>, it indicates that the current script does not provide a version number and that the script is executed using the last known version number. If that version number is unknown because a script without a specified version is the first to execute, <C>JS_GetVersion</C> still returns <C>JSVERSION_DEFAULT</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_SetVersion'/>
</ENTRY>
<ENTRYid='JS_SetVersion'>
<TYPEvalue='Function'/>
<SUMMARY>
Specifies the version of JavaScript used by a specified executable script context.
<C>JS_SetVersion</C> attempts to set the version of JavaScript to <C>version</C> for a specified executable script context, <C>cx</C>. <C>version</C> must be one of the following values:
<C>JS_SetVersion</C> returns the JS version in effect for the context before you changed it.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetVersion'/>
</ENTRY>
<ENTRYid='JS_GetImplementationVersion'>
<TYPEvalue='Function'/>
<SUMMARY>
Indicates the version number of the JS engine.
</SUMMARY>
<SYNTAX>
const char * JS_GetImplementationVersion;
</SYNTAX>
<DESCRIPTION>
<C>JS_GetImplementationVersion</C> returns a hard-coded, English language string that specifies the version number of the JS engine currently in use, and its release date. <P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetVersion'/>
<SEEALSOvalue='JS_SetVersion'/>
</ENTRY>
<ENTRYid='JS_GetGlobalObject'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves a pointer to the global JS object for an executable script context.
</SUMMARY>
<SYNTAX>
JSObject * JS_GetGlobalObject(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetGlobalObject</C> enables you to retrieve a pointer to the global JS object for a specified <C>JSContext</C>, <C>cx</C>. <P/>
</DESCRIPTION>
<SEEALSOvalue='JS_SetGlobalObject'/>
<SEEALSOvalue='OBJECT_TO_JSVAL'/>
<SEEALSOvalue='JSVAL_TO_OBJECT'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
</ENTRY>
<ENTRYid='JS_SetGlobalObject'>
<TYPEvalue='Function'/>
<SUMMARY>
Specifies the global object for an executable script context.
Pointer to the executable script context for which to set the global object.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to the JS object to set as the global object.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetGlobalObject</C> sets the global object to <C>obj</C> for a specified executable script context, <C>cx</C>. Ordinarily you set a context's global object when you call <C>JS_InitStandardClasses</C> to set up the general JS function and object classes for use by scripts.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_InitStandardClasses'/>
<SEEALSOvalue='JS_GetGlobalObject'/>
<SEEALSOvalue='OBJECT_TO_JSVAL'/>
<SEEALSOvalue='JSVAL_TO_OBJECT'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
</ENTRY>
<ENTRYid='JS_InitStandardClasses'>
<TYPEvalue='Function'/>
<SUMMARY>
Initializes general JS function and object classes, and the built-in object classes used in most scripts.
Pointer to the executable script context for which to initialize JS function and object classes.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to a JS object to set as the global object.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_InitStandardClasses</C> initializes general JS function and object classes, and the built-in object classes used in most scripts. The appropriate constructors for these objects are created in the scope defined for obj. Always call <C>JS_InitStandardClasses</C> before executing scripts that make use of JS objects, functions, and built-in objects.<P/>
As a side effect, <C>JS_InitStandardClasses</C> uses <C>obj</C> to establish a global object for the specified executable context, <C>cx</C>, if one is not already established.<P/>
<C>JS_InitStandardClasses</C> also initializes the general JS function and object classes. Initializing the function class enables building of constructors. Initializing the object classes enables the <I><C><object>.<prototype></C></I> syntax to work in JavaScript.<P/>
Finally, <C>JS_InitStandardClasses</C> initializes the built-in JS objects (<C>Array</C>, <C>Boolean</C>, <C>Date</C>, <C>Math</C>, <C>Number</C>, and <C>String</C>) used by most scripts.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_InitClass'/>
<SEEALSOvalue='JS_GetClass'/>
</ENTRY>
<ENTRYid='JS_GetScopeChain'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the scope chain for a given executable script context.
</SUMMARY>
<SYNTAX>
JSObject * JS_GetScopeChain(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetScopeChain</C> retrieves the scope chain for the currently executing (or "active") script or function in a given context, <C>cx</C>. The scope chain provides a way for JavaScript to resolve unqualified property and variable references. The scope chain can store reference qualifications, so that future lookups are faster.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_InitStandardClasses'/>
</ENTRY>
<ENTRYid='JS_malloc'>
<TYPEvalue='Function'/>
<SUMMARY>
Allocates a region of memory for use.
</SUMMARY>
<SYNTAX>
void * JS_malloc(JSContext *cx, size_t nbytes);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='nbytes'type='size_t'>
Amount of space, in bytes, to allocate.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_malloc</C> allocates a region of memory <C>nbytes</C> in size. If the allocation is successful, <C>JS_malloc</C> returns a pointer to the beginning of the region.<P/>
If the memory cannot be allocated, <C>JS_malloc</C> passes <C>cx</C> to <C>JS_ReportOutOfMemory</C> to report the error, and returns a null pointer. <P/>
As with a standard C call to <C>malloc</C>, the region of memory allocated by this call is uninitialized and should be assumed to contain meaningless information.<P/>
</DESCRIPTION>
<NOTE>
Currently <C>JS_malloc</C> is a wrapper on the standard C <C>malloc</C> call. Do not make assumptions based on this underlying reliance. Future versions of <C>JS_malloc</C> may be implemented in a different manner.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='p'type='void *'>
Pointer to the previously allocated memory<BR/>
</PARAM>
<PARAMname='nbytes'type='size_t'>
Amount of space, in bytes, to reallocate.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_realloc</C> reallocates a region of memory, while preserving its contents. Typically you call <C>JS_realloc</C> because you need to allocate more memory than orginally allocated with a call to <C>JS_malloc</C>, but it can also be called to decrease the amount of allocated memory, and even to deallocate the memory region entirely. <C>p</C> is a pointer to the previously allocated memory region, and <C>nbytes</C> is the size, in bytes, of the region to allocate.<P/>
</DESCRIPTION>
<NOTE>
Currently <C>JS_realloc</C> is a wrapper on the standard C <C>realloc</C> call. Do not make assumptions based on this underlying reliance. Future versions of <C>JS_realloc</C> may be implemented in a different manner.<P/>
If <C>p</C> is null, then <C>JS_realloc</C> behaves like JS_malloc. If <C>p</C> is not null, and <C>nbytes</C> is <C>0</C>, <C>JS_realloc</C> returns null and the region is deallocated. As with <C>JS_malloc</C>, new space is not initialized and should be regarded to contain meaningless information.<P/>
If a reallocation request fails, <C>JS_realloc</C> passes <C>cx</C> to <C>JS_ReportOutOfMemory</C> to report the error.<P/>
</NOTE>
<NOTE>
Whenever the pointer returned by <C>JS_realloc</C> differs from <C>p</C>, the old region of memory is deallocated and should not be used.
<P/>
</NOTE>
<SEEALSOvalue='JS_malloc'/>
<SEEALSOvalue='JS_free'/>
<SEEALSOvalue='JS_ReportOutOfMemory'/>
</ENTRY>
<ENTRYid='JS_free'>
<TYPEvalue='Function'/>
<SUMMARY>
Deallocates a region of memory.
</SUMMARY>
<SYNTAX>
void JS_free(JSContext *cx, void *p);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='p'type='void *'>
Pointer to the previously allocated memory<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_free</C> deallocates a region of memory allocated by previous calls to JS_malloc and JS_realloc. If <C>p</C> is null, <C>JS_free</C> does nothing. Once memory is freed, it should not be used by your application.<P/>
</DESCRIPTION>
<NOTE>
Currently <C>JS_free</C> is a wrapper on the standard C <C>free</C> call. Do not make assumptions based on this underlying reliance. Future versions of <C>JS_free</C> may be implemented in a different manner.<P/>
</NOTE>
<SEEALSOvalue='JS_malloc'/>
<SEEALSOvalue='JS_realloc'/>
</ENTRY>
<ENTRYid='JS_strdup'>
<TYPEvalue='Function'/>
<SUMMARY>
Duplicates a specified string within a specific JS executable script context.
</SUMMARY>
<SYNTAX>
char * JS_strdup(JSContext *cx, const char *s);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='s'type='char *'>
Pointer to an existing string to duplicate.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_strdup</C> duplicates a specified string, <C>s</C>, within a specified <C>JSContext</C>, <C>cx</C>. To duplicate the string, <C>JS_strdup</C> allocates space from the <C>malloc</C> heap for the a copy of the string, and then copies <C>s</C> to the newly allocated location. If the allocation fails, <C>JS_strdup</C> returns a null pointer. Otherwise, it returns a pointer to the duplicate string.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='d'type='jsdouble'>
An existing double value to duplicate.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewDouble</C> creates a copy of a JS double, <C>d</C>, for a given executable script context, <C>cx</C>. Space for the new value is allocated from the JS garbage collection heap.<P/>
If the duplication is successful, <C>JS_NewDouble</C> returns a pointer to the copy of the double. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<NOTE>
After you create it, a JS double is subject to garbage collection until you protect
against it using a local root, an object property, or the <C>JS_AddRoot</C> function.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='d'type='jsdouble'>
An existing double to assign as a value to the <C>jsval</C>.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to a previously declared <C>jsval</C> into which to store the double value.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewDoubleValue</C> creates a <C>jsval</C> containing a double value that corresponds to the double passed in as an argument. <C>cx</C> is the executable script context in which this call is made. <C>d</C> is the double value to assign to the <C>jsval</C>, and <C>rval</C> is the <C>jsval</C> into which the new JS double value is stored. Space for the new value is allocated from the JS garbage collection heap.<P/>
<C>JS_NewDoubleValue</C> attempts to creates a temporary copy of the double value. If the copy is successful, then the jsval is created, and the function returns <C>JS_TRUE</C>.Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<NOTE>
After you create it, a JS double is subject to garbage collection until you protect
against it using a local root, an object property, or the <C>JS_AddRoot</C> function.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='d'type='jsdouble'>
An existing double to assign as a value to the <C>jsval</C>.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to a previously declared <C>jsval</C> into which to store the double value.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewNumberValue</C> creates a <C>jsval</C> containing a numeric value that corresponds to the double passed in as an argument. <C>cx</C> is the executable script context in which this call is made. <C>d</C> is the numeric value to assign to the <C>jsval</C>, and <C>rval</C> is the <C>jsval</C> into which the new JS numeric value is stored. Space for the new value is allocated from the JS garbage collection heap.<P/>
<C>JS_NewNumberValue</C> attempts to creates a temporary copy of the double value. First it copies the value into an integer variable and compares the double and integer values. If they match, then <C>JS_NewNumber</C> converts the integer to a JS value. If they do not match, <C>JS_NewNumber</C> calls <C>JS_NewDouble</C> to create a JS value containing the value of the original double. If the creation of the JS value is successful, the function returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<NOTE>
If <C>JS_NewNumberValue</C> creates a double, be aware that it is subject to garbage
collection unless you protect against it using a local root, an object property, or
the <C>JS_AddRoot</C> function.
<P/>
</NOTE>
<SEEALSOvalue='JS_NewDoubleValue'/>
<SEEALSOvalue='JS_AddRoot'/>
</ENTRY>
<ENTRYid='JS_AddRoot'>
<TYPEvalue='Function'/>
<SUMMARY>
Adds a garbage collection hash table entry for a specified JS item to protect it from garbage collection.
</SUMMARY>
<SYNTAX>
JSBool JS_AddRoot(JSContext *cx, void *rp);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='rp'type='void *'>
Pointer to the item to protect.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_AddRoot</C> protects the GC thing pointed at by a specified pointer, <C>*rp</C>, from garbage collection. <C>rp</C> is a pointer to a pointer to a JS double, string, or object. An entry for <C>rp</C> is added to the garbage collector's table for the <C>JSRuntime</C> of the specified <C>JSContext</C>, <C>cx</C>.<P/>
If the GC thing pointed to by <C>*rp</C> is an object, then any GC things reachable from it's properties are automatically protected from garbage collection, too.<P/>
</DESCRIPTION>
<NOTE>
You should use <C>JS_AddRoot</C> to root only JS objects, JS strings, or JS doubles, and then only if they are derived from calls to their respective <C>JS_New</C><I><C>XXX</C></I> creation functions.<P/>
If the entry in the root table is successfully created, <C>JS_AddRoot</C> returns <C>JS_TRUE</C>. Otherwise it reports an out of memory error and returns <C>JS_FALSE</C>.<P/>
<C>*rp</C> may also be a <C>jsval</C>. If <C>JSVAL_IS_GCTHING</C> evaluates to true for that value, then the GC thing will be protected.
</NOTE>
<SEEALSOvalue='JS_AddNamedRoot'/>
<SEEALSOvalue='JS_DumpNamedRoots'/>
<SEEALSOvalue='JS_RemoveRoot'/>
</ENTRY>
<ENTRYid='JS_AddNamedRoot'>
<TYPEvalue='Function'/>
<SUMMARY>
Adds a garbage collection hash table entry for a named JS item to protect it from garbage collection.
</SUMMARY>
<SYNTAX>
JSBool JS_AddNamedRoot(JSContext *cx, void *rp,
const char *name);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='rp'type='void *'>
Pointer to the item to protect.<BR/>
</PARAM>
<PARAMname='name'type='char *'>
Name of the item to protect<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_AddNamedRoot</C> protects the GC thing pointed at by a specified pointer, <C>*rp</C>, from garbage collection. <C>rp</C> is a pointer to a pointer to a JS double, string, or object. An entry for <C>rp</C> is added to the garbage collector's table for the <C>JSRuntime</C> of the specified <C>JSContext</C>, <C>cx</C>.<P/>
If the GC thing pointed to by <C>*rp</C> is an object, then any GC things reachable from it's properties are automatically protected from garbage collection, too.<P/>
The <C>name</C> parameter is stored in the <C>JSRuntime</C>'s root table entry along with <C>rp</C>. The <C>name</C> string's lifetime must be at least as long as the <C>JSRuntime</C>'s. Typically <C>name</C> is a static string constant, identifying the source location of the call to <C>JS_AddNamedRoot</C>, for debugging purposes. <C>JS_DumpNamedRoots</C> can be used to access this information from a debugger.
</DESCRIPTION>
<NOTE>
You should use <C>JS_AddNamedRoot</C> to root only JS objects, JS strings, or JS doubles, and then only if they are derived from calls to their respective <C>JS_New</C><I><C>XXX</C></I> creation functions.<P/>
If the entry in the root table is successfully created, <C>JS_AddNamedRoot</C> returns <C>JS_TRUE</C>. Otherwise it reports an out of memory error and returns <C>JS_FALSE</C>.<P/>
<C>*rp</C> may also be a <C>jsval</C>. If <C>JSVAL_IS_GCTHING</C> evaluates to true for that value, then the GC thing will be protected.
</NOTE>
<SEEALSOvalue='JS_AddRoot'/>
<SEEALSOvalue='JS_DumpNamedRoots'/>
<SEEALSOvalue='JS_RemoveRoot'/>
</ENTRY>
<ENTRYid='JS_DumpNamedRoots'>
<TYPEvalue='Function'/>
<SUMMARY>
Enumerates the named roots in the garbage collection hash table.
Pointer to a <C>JSRuntime</C> from which to dump named roots<BR/>
</PARAM>
<PARAMname='dump'type='void *'>
Pointer to function that actually dumps the named roots<BR/>
</PARAM>
<PARAMname='data'type='void *'>
Pointer to a storage area into which to put a root's data.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DumpNamedRoots</C> retrieves information from the garbage collection hash table about the named roots associated with a specific <C>JSRuntime</C>, <C>rt</C>.<P/>
<C>dump</C> is the name of the function that actually retrieves the information from the hash table. If you pass a null pointer for this argument, the JS engine defaults to using an internal retrieval function. If you write your own <C>dump</C> function to replace the internal engine function, note that the function you write must accept the following arguments, in order:
Pointer to a storage area into which to put a root's data.</P>
</TD></TR></TABLE >
]]>
<P/>
<C>data</C> is a pointer to the storage structure into which to return retrieved information. If you pass a null pointer for this argument the JS engine defaults to using an internal storage structure for this information. If you write your own <C>dump</C> function, data must be the same as the last argument passed to the <C>dump</C> function.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_AddRoot'/>
<SEEALSOvalue='JS_AddNamedRoot'/>
<SEEALSOvalue='JS_RemoveRoot'/>
</ENTRY>
<ENTRYid='JS_RemoveRoot'>
<TYPEvalue='Function'/>
<SUMMARY>
Removes a garbage collection hash table entry for a specified JS item to enable it to be garbage collected.
</SUMMARY>
<SYNTAX>
JSBool JS_RemoveRoot(JSContext *cx, void *rp);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='rp'type='void *'>
Pointer to the item to remove from the hash table.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_RemoveRoot</C> removes an entry for a a specified item, <C>rp</C>, from the garbage collection hash table. When an item is removed from the hash table, it can be garbage collected. <C>rp</C> is a pointer to a JS double, string, or object. An entry for the item is removed in the garbage collection hash table for the specified executable script context, <C>cx</C>.<P/>
Indicates to the JS engine that the application is starting a thread.
</SUMMARY>
<SYNTAX>
void JS_BeginRequest(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
When your application start a new thread, <C>JS_BeginRequest</C> safely increments the thread counter for the JS engine runtime associated with a given context, <C>cx</C>. In order to increment the counter, this function first checks that garbage collection is not in process. If it is, <C>JS_BeginRequest</C> waits until garbage collection is complete before locking the JS engine runtime and incrementing the thread counter. After incrementing the counter, <C>JS_BeginRequest</C> unlocks the runtime if it previously locked it.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_BeginRequest</C> is only available if you compile the JS engine with <C>JS_THREADSAFE</C> defined. In a default engine compilation, <C>JS_THREADSAFE</C> is undefined.<P/>
</NOTE>
<SEEALSOvalue='JS_EndRequest'/>
<SEEALSOvalue='JS_SuspendRequest'/>
<SEEALSOvalue='JS_ResumeRequest'/>
</ENTRY>
<ENTRYid='JS_EndRequest'>
<TYPEvalue='Function'/>
<SUMMARY>
Indicates to the JS engine that the application no longer requires a thread.
</SUMMARY>
<SYNTAX>
void JS_EndRequest(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
When your application no longer requires a thread, <C>JS_EndRequest</C> safely decrements the thread counter for the JS engine runtime associated with a given context, <C>cx</C>. If decrementing the counter reduces it to zero, <C>JS_EndRequest</C> locks the runtime and notifies the garbage collector so that values no longer in use can be cleaned up. To avoid garbage collection notification, call <C>JS_SuspendRequest</C> instead of <C>JS_EndRequest</C>.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_EndRequest</C> is only available if you compile the JS engine with <C>JS_THREADSAFE</C> defined. In a default engine compilation, <C>JS_THREADSAFE</C> is undefined.<P/>
</NOTE>
<SEEALSOvalue='JS_BeginRequest'/>
<SEEALSOvalue='JS_SuspendRequest'/>
<SEEALSOvalue='JS_ResumeRequest'/>
</ENTRY>
<ENTRYid='JS_SuspendRequest'>
<TYPEvalue='Function'/>
<SUMMARY>
Indicates to the JS engine that the application is temporarily suspending a thread.
</SUMMARY>
<SYNTAX>
void JS_SuspendRequest(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
When your application suspends use of a thread, <C>JS_SuspendRequest</C> safely decrements the thread counter for the JS engine runtime associated with a given context, <C>cx</C>. <P/>
</DESCRIPTION>
<NOTE>
<C>JS_SuspendRequest</C> is only available if you compile the JS engine with <C>JS_THREADSAFE</C> defined. In a default engine compilation, <C>JS_THREADSAFE</C> is undefined.<P/>
</NOTE>
<SEEALSOvalue='JS_BeginRequest'/>
<SEEALSOvalue='JS_EndRequest'/>
<SEEALSOvalue='JS_ResumeRequest'/>
</ENTRY>
<ENTRYid='JS_ResumeRequest'>
<TYPEvalue='Function'/>
<SUMMARY>
Restarts a previously suspended thread.
</SUMMARY>
<SYNTAX>
void JS_ResumeRequest(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
When your application restart a previously suspended thread, <C>JS_BeginRequest</C> safely increments the thread counter for the JS engine runtime associated with a given context, <C>cx</C>. In order to increment the counter, this function first checks that garbage collection is not in process. If it is, <C>JS_ResumeRequest</C> waits until garbage collection is complete before locking the JS engine runtime and incrementing the thread counter. After incrementing the counter, <C>JS_ResumeRequest</C> unlocks the runtime if it previously locked it.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_ResumeRequest</C> is only available if you compile the JS engine with <C>JS_THREADSAFE</C> defined. In a default engine compilation, <C>JS_THREADSAFE</C> is undefined.<P/>
</NOTE>
<SEEALSOvalue='JS_BeginRequest'/>
<SEEALSOvalue='JS_EndRequest'/>
<SEEALSOvalue='JS_SuspendRequest'/>
</ENTRY>
<ENTRYid='JS_LockGCThing'>
<TYPEvalue='Function'/>
<SUMMARY>
Protects a specified JS item from garbage collection.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='thing'type='void *'>
Pointer to the item to protect.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_LockGCThing</C> is a deprecated function that protects a specified item, <C>thing</C>, associated with an executable script context, <C>cx</C>, from garbage collection. <C>thing</C> is a JS double, string, or object. This function is available only for backward compatibility with existing applications. Use <C>JS_AddRoot</C> instead of this function.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_UnlockGCThing'/>
<SEEALSOvalue='JS_AddRoot'/>
<DEPRECATED/>
</ENTRY>
<ENTRYid='JS_UnlockGCThing'>
<TYPEvalue='Function'/>
<SUMMARY>
Reenables garbage collection of a specified JS item.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='thing'type='void *'>
Pointer to the item to unlock.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_LockGCThing</C> removes a lock from a specified item, <C>thing</C>, enabling it to be garbage collected. Unlocking occurs within a specified executable script context, <C>cx</C>. <C>thing</C> is a JS double, string, or object.This function is available only for backward compatibility with existing applications. Use <C>JS_RemoveRoot</C> instead.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_LockGCThing'/>
<SEEALSOvalue='JS_RemoveRoot'/>
<DEPRECATED/>
</ENTRY>
<ENTRYid='JS_GC'>
<TYPEvalue='Function'/>
<SUMMARY>
Performs garbage collection in the JS memory pool.
</SUMMARY>
<SYNTAX>
void JS_GC(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_GC</C> performs garbage collection, if necessary, of JS objects, doubles, and strings that are no longer needed by a script executing in a specified <C>JSContext</C>, <C>cx</C>. Garbage collection frees space in the memory pool so that it can be reused by the JS engine.<P/>
When you use <C>JS_malloc</C> and <C>JS_realloc</C> to allocate memory for executable script contexts, these routines automatically invoke the garbage collection routine.<P/>
When your scripts create many objects, you may want to call <C>JS_GC</C> directly in your code, particularly when request ends or a script terminates. To run garbage collection only when a certain amount of memory has been allocated, you can call <C>JS_MaybeGC</C> instead of <C>JS_GC</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_malloc'/>
<SEEALSOvalue='JS_realloc'/>
<SEEALSOvalue='JS_MaybeGC'/>
</ENTRY>
<ENTRYid='JS_MaybeGC'>
<TYPEvalue='Function'/>
<SUMMARY>
Invokes conditional garbage collection on the JS memory pool.
</SUMMARY>
<SYNTAX>
void JS_MaybeGC(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_MaybeGC</C> performs a conditional garbage collection of JS objects, doubles, and strings that are no longer needed by a script executing in a specified <C>JSContext</C>, <C>cx</C>. This function checks that about 75% of available space has already been allocated to objects before peforming garbage collection. To force garbage collection regardless of the amount of allocated space, call <C>JS_GC</C> instead of <C>JS_MaybeGC</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_malloc'/>
<SEEALSOvalue='JS_realloc'/>
<SEEALSOvalue='JS_GC'/>
</ENTRY>
<ENTRYid='JS_SetGCCallback'>
<TYPEvalue='Function'/>
<SUMMARY>
Specifies a new callback function for the garbage collector.
<C>JS_SetGCCallback</C> enables you to specify the function is called by the garbage collector to return control to the calling program when garbage collection is complete. <C>cx</C> is the context in which you specify the callback. <C>cb</C> is a pointer to the new callback function to use.<P/>
<C>JS_SetGCCallback</C> returns a pointer to the previously used callback function upon completion. Your application should store this return value in order to restore the original callback when the new callback is no longer needed.<P/>
To restore the original callback, simply call <C>JS_SetGCCallback</C> a second time, and pass the old callback in as the <C>cb</C> argument.<P/>
<C>JS_DestroyIdArray</C> frees the JS ID array structure pointed to by <C>ida</C>. <C>cx</C> is the context in which the freeing of the array takes place.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewIdArray'/>
<SEEALSOvalue='JSIdArray'/>
</ENTRY>
<ENTRYid='JS_NewIdArray'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new JS ID array structure.
</SUMMARY>
<SYNTAX>
JSIdArray JS_NewIdArray(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_NewIdArray</C> allocates memory for a new JS ID array structure. On success, it returns a pointer to the newly allocated structure. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_DestroyIdArray'/>
<SEEALSOvalue='JSIdArray'/>
</ENTRY>
<ENTRYid='JS_PropertyStub'>
<TYPEvalue='Function'/>
<SUMMARY>
Provides a dummy property argument for API routines that requires property information.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to the object for this stub.<BR/>
</PARAM>
<PARAMname='id'type='jsval'>
The ID for the stub.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to a jsval for the stub.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_PropertyStub</C> provides a convenient way to pass a property to an API function that requires one without requiring you to create an actual property definition. This is especially useful for internal operations, such as class definitions. A property stub is a place holder for an actual property assignment function.<P/>
As designed, <C>JS_PropertyStub</C> does not use the arguments you pass to it, and simply returns <C>JS_TRUE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_EnumerateStub'/>
<SEEALSOvalue='JS_ResolveStub'/>
<SEEALSOvalue='JS_ConvertStub'/>
<SEEALSOvalue='JS_FinalizeStub'/>
</ENTRY>
<ENTRYid='JS_EnumerateStub'>
<TYPEvalue='Function'/>
<SUMMARY>
Provides a dummy enumeration object for API routines that requires it.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to the object for this stub.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_EnumerateStub</C> provides a convenient way to pass an enumeration object to an API function that requires one without requiring you to create an actual enumeration object. This is especially useful for internal operations, such as class definitions. An enumeration stub is a placeholder for an actual enumeration function.<P/>
As designed, <C>JS_EnumerationStub</C> does not use the arguments you pass to it, and simply returns <C>JS_TRUE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_ResolveStub'/>
<SEEALSOvalue='JS_ConvertStub'/>
<SEEALSOvalue='JS_FinalizeStub'/>
</ENTRY>
<ENTRYid='JS_ResolveStub'>
<TYPEvalue='Function'/>
<SUMMARY>
Provides a dummy resolution object for API routines that requires it.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to the object for this stub.<BR/>
</PARAM>
<PARAMname='id'type='jsval'>
The ID for the stub.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ResolveStub</C> provides a convenient way to pass a resolution object to an API function that requires one without requiring you to create an actual resolution object. This is especially useful for internal operations, such as class definitions. A resolution stub is a placeholder for an actual resolution assignment function.<P/>
As designed, <C>JS_ResolveStub</C> does not use the arguments you pass to it, and simply returns <C>JS_TRUE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_EnumerateStub'/>
<SEEALSOvalue='JS_ConvertStub'/>
<SEEALSOvalue='JS_FinalizeStub'/>
</ENTRY>
<ENTRYid='JS_ConvertStub'>
<TYPEvalue='Function'/>
<SUMMARY>
Provides a dummy conversion object for API routines that requires it.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to the object for this stub.<BR/>
</PARAM>
<PARAMname='type'type='JSType'>
The type to which to convert this object.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to the JS value in which to store the conversion.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ConvertStub</C> provides a convenient way to pass a conversion object to an API function that requires one without requiring you to create an actual conversion object. This is especially useful for internal operations, such as class definitions. A conversion stub is a placeholder for an actual conversion function.<P/>
As designed, <C>JS_ConvertStub</C> does not use the arguments you pass to it, and simply returns <C>JS_TRUE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_EnumerateStub'/>
<SEEALSOvalue='JS_ResolveStub'/>
<SEEALSOvalue='JS_FinalizeStub'/>
</ENTRY>
<ENTRYid='JS_FinalizeStub'>
<TYPEvalue='Function'/>
<SUMMARY>
Provides a dummy finalization object for API routines that requires it.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to the object for this stub.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_FinalizeStub</C> provides a convenient way to pass a finalization object to an API function that requires one without requiring you to create an actual finalization object. This is especially useful for internal operations, such as class definitions. A conversion stub is a placeholder for an actual finalization function.<P/>
As designed, <C>JS_FinalizeStub</C> does not use the arguments you pass to it, and simply returns <C>JS_TRUE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_EnumerateStub'/>
<SEEALSOvalue='JS_ResolveStub'/>
<SEEALSOvalue='JS_ConvertStub'/>
</ENTRY>
<ENTRYid='JS_InitClass'>
<TYPEvalue='Function'/>
<SUMMARY>
Initializes a class structure, its prototype, properties, and functions.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to the object to use for initializing the class.<BR/>
</PARAM>
<PARAMname='parent_proto'type='JSObject *'>
Pointer to a prototype object for the class.<BR/>
</PARAM>
<PARAMname='clasp'type='JSClass *'>
Pointer to the class structure to initialize. This structure defines the class for use by other API functions.<BR/>
</PARAM>
<PARAMname='constructor'type='JSNative'>
The constructor for the class. Its scope matches that of the <C>obj</C> argument. If constructor is <C>NULL</C>, then <C>static_ps</C> and <C>static_fs</C> are also <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='nargs'type='uintN'>
Number of arguments for the constructor.<BR/>
</PARAM>
<PARAMname='ps'type='JSPropertySpec *'>
Pointer to the properties structure for the prototype object, <C>parent_proto</C>.<BR/>
</PARAM>
<PARAMname='fs'type='JSFunctionSpec *'>
Pointer to the functions structure for the prototype object, <C>parent_proto</C>.<BR/>
</PARAM>
<PARAMname='static_ps'type='JSPropertySpec *'>
Pointer to the properties structure for the constructor object, if it is not <C>NULL</C>.<BR/>
</PARAM>
<PARAMname='static_fs'type='JSFunctionSpec *'>
Pointer to the functions structure for the constructor object, if it is not <C>NULL</C>.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_InitClass</C> builds a class structure, its object constructor, its prototype, its properties, and its methods. A class is an internal JS structure that is not exposed outside the JS engine. You can use a class, its properties, methods, and prototypes to build other objects that are exposed outside the engine.<P/>
<C>JS_InitClass</C> returns a pointer to a JS object that is the prototype for the newly initialized class. If <C>JS_InitClass</C> fails, then the pointer returned is <C>NULL</C>.<P/>
A class is comprised of a class structure, a constructor, a prototype object, and properties and functions. The class structure specifies the name of the class, its flags, and its property functions. These include functions for adding and deleting properties, getting and setting property values, and enumerating converting, resolving, and finalizing its properties.<P/>
The constructor for the class is built in the same context as <C>cx</C>, and in the same scope as <C>obj</C>. If you pass <C>NULL</C> to <C>JS_InitClass</C>, then a constructor is not built, and you cannot specify static properties and functions for the class.<P/>
If you provide a constructor for the class, then you should also pass an object to <C>parent_proto</C>. <C>JS_InitClass</C> uses <C>parent_proto</C> to build a prototype accessor object for the class. The accessor object is modeled on the prototype object you provide. If the accessor object is successfully created, <C>JS_InitClass</C> returns a pointer to the JS object. Otherwise it returns <C>NULL</C>, indicating failure to create the accessor object, and therefore failure to create the class itself.<P/>
After building the constructor and prototype, <C>JS_InitClass</C> adds the properties and methods of the constructor and prototype, if any, to the class definition. Properties and methods are either "dynamic," based on the properties and methods of the prototype object, or "static," based on the properties and methods of the constructor.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetClass'/>
<SEEALSOvalue='JS_InstanceOf'/>
<SEEALSOvalue='JSClass'/>
<SEEALSOvalue='JSPropertySpec'/>
<SEEALSOvalue='JSFunctionSpec'/>
</ENTRY>
<ENTRYid='JS_GetClass'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the class associated with an object.
</SUMMARY>
<SYNTAX>
JSClass * JS_GetClass(JSObject *obj);
Alternative syntax when JS_THREADSAFE is defined in a multithreaded environment:
<C>JS_GetClass</C> returns a pointer to the class associated with a specified JS object, <C>obj</C>. The class is an internal JS data structure that you can create for objects as needed. Generally you do not expose a class in your applications, but use it behind the scenes.<P/>
If your application runs in a multithreaded environment, define <C>JS_THREADSAFE</C>, and pass a thread context as the first argument to <C>JS_GetClass</C>.<P/>
If an object has a class, <C>JS_GetClass</C> returns a pointer to the class structure. Otherwise, it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_InitClass'/>
<SEEALSOvalue='JS_InstanceOf'/>
<SEEALSOvalue='JSClass'/>
</ENTRY>
<ENTRYid='JS_InstanceOf'>
<TYPEvalue='Function'/>
<SUMMARY>
Determines if an object is an instance of a specified JS class.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to test.<BR/>
</PARAM>
<PARAMname='clasp'type='JSClass *'>
Class against which to test the object.<BR/>
</PARAM>
<PARAMname='argv'type='jsval *'>
Optional argument vector. If you do not want to pass an argument vector, pass <C>NULL</C> for this argument.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_InstanceOf</C> determines if a specified JS object, <C>obj</C>, has a JS class struct, <C>clasp</C>. If the object's internal class pointer corresponds to <C>clasp</C>, this function returns <C>JS_TRUE</C>, indicating that the object is an instance of the class. Otherwise, <C>JS_InstanceOf</C> returns <C>JS_FALSE</C>.<P/>
If you pass a non-null argument vector, <C>argv</C>, to <C>JS_InstanceOf</C>, and <C>obj</C> is not an instance of <C>clasp</C>, this function may report a class mismatch before returning. To do so, <C>JS_InstanceOf</C> tests whether or not there is a function name associated with the argument vector, and if there is, reports the name in an error message using the <C>JS_ReportError</C> function.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_InitClass'/>
<SEEALSOvalue='JS_GetClass'/>
<SEEALSOvalue='JSClass'/>
</ENTRY>
<ENTRYid='JS_GetPrivate'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the private data associated with an object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to retrieve private data.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetPrivate</C> retrieves the private data associated with a specified object, <C>obj</C>. To retrieve private data, an object must be an instance of a class, and that class must include the <C>JSCLASS_HAS_PRIVATE </C>flag.<P/>
If successful, <C>JS_GetPrivate</C> returns a pointer to the private data. Otherwise it returns <C>NULL</C> which can mean either that there is no private data currently associated with the object, or that the object cannot have private data.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to set private data.<BR/>
</PARAM>
<PARAMname='data'type='void *'>
Private data for the object.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetPrivate</C> sets the private data pointer for a specified object, <C>obj</C>. To set private data for an object, the object must be an instance of a class, and the class must include <C>JSCLASS_HAS_PRIVATE</C> in its flag set.<P/>
Only a pointer to data is stored with the object. The data pointer is converted to a jsval for storage purposes. You must free this pointer in your finalization code if you allocated storage for it. It is up to your application to maintain the actual data.<P/>
If successful, <C>JS_SetPrivate</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='PRIVATE_TO_JSVAL'/>
<SEEALSOvalue='JSCLASS_HAS_PRIVATE'/>
<SEEALSOvalue='JS_InitClass'/>
<SEEALSOvalue='JS_GetPrivate'/>
<SEEALSOvalue='JS_GetInstancePrivate'/>
<SEEALSOvalue='JSClass'/>
</ENTRY>
<ENTRYid='JS_GetContextPrivate'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the private data associated with a context.
</SUMMARY>
<SYNTAX>
void * JS_GetContextPrivate(JSContext *cx);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context for which to retrieve data.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetContextPrivate</C> retrieves the private data associated with a specified <C>JSContext</C>, <C>cx</C>. If successful, <C>JS_GetContextPrivate</C> returns a pointer to the private data. Otherwise it returns <C>NULL</C> which means that there is no private data currently associated with the context.<P/>
Pointer to a JS context for which to set private data.<BR/>
</PARAM>
<PARAMname='data'type='void *'>
Pointer to the private data for the context.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetContextPrivate</C> sets the private data pointer for a specified <C>JSContext</C>, <C>cx</C>.<P/>
Only a pointer to data is stored with the context. The data pointer is converted to a jsval for storage purposes. You must free this pointer in your finalization code if you allocated storage for it. It is up to your application to maintain the actual data.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetContextPrivate'/>
</ENTRY>
<ENTRYid='JS_GetInstancePrivate'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the private data associated with an object if that object is an instance of a class.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to retrieve private data.<BR/>
</PARAM>
<PARAMname='clasp'type='JSClass *'>
Class against which to test the object.<BR/>
</PARAM>
<PARAMname='argv'type='jsval *'>
Optional argument vector. If you do not want to pass an argument vector, pass <C>NULL</C> for this argument.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetInstancePrivate</C> determines if a specified JS object, <C>obj</C>, is an instance of a JS class, <C>clasp</C>, and if it is, returns a pointer to the object's private data. If the object's internal class pointer corresponds to <C>clasp</C>, and you do not also pass an optional argument vector, <C>argv</C>, this function attempts to retrieve a pointer to the private data. Otherwise, it returns <C>NULL</C>.<P/>
If you pass a non-null argument vector, <C>argv</C>, to <C>JS_GetInstancePrivate</C>, and <C>obj</C> is not an instance of <C>clasp</C>, this function reports a class mismatch before returning <C>NULL</C>. In this case, <C>JS_GetInstancePrivate</C> tests whether or not there is a function name associated with the argument vector, and if there is, reports the name in an error message using the <C>JS_ReportError</C> function.<P/>
</DESCRIPTION>
<NOTE>
If <C>obj</C> is an instance of <C>clasp</C>, but there is no private data currently associated with the object, or the object cannot have private data, <C>JS_GetInstancePrivate</C> also returns <C>NULL</C>.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to retrieve the prototype.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetPrototype</C> retrieves the prototype object for a specified object, <C>obj</C>. A prototype object provides properties shared by similar JS objects.<P/>
If an object has a prototype, <C>JS_GetPrototype</C> returns a pointer to the prototype. If the object does not have a prototype, or the object finalize function is active, <C>JS_GetPrototype</C> returns <C>NULL</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to the object for which to set the prototype.<BR/>
</PARAM>
<PARAMname='proto'type='JSObject *'>
Pointer to the prototype to use.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetPrototype</C> enables you to set the prototype object for a specified object. A prototype object provides properties that are shared by similar JS object instances. Ordinarily you set a prototype for an object when you create the object with <C>JS_NewObject</C>, but if you do not set a prototype at that time, you can later call <C>JS_SetPrototype</C> to do so.<P/>
<C>obj</C> is a pointer to an existing JS object, and <C>proto</C> is a pointer to second existing object upon which the first object is based.<P/>
</DESCRIPTION>
<NOTE>
Take care not to create a circularly-linked list of prototypes using this function,
because such a set of prototypes cannot be resolved by the JS engine.
<P/>
</NOTE>
<DESCRIPTION>
If <C>JS_SetPrototype</C> is successful, it returns <C>JS_TRUE</C>. Otherwise, if it cannot create and fill a prototype slot for the object, it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetPrototype'/>
<SEEALSOvalue='JS_NewObject'/>
</ENTRY>
<ENTRYid='JS_GetParent'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the parent object for a specified object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to retrieve the parent.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetParent</C> retrieves the parent object for a specified object, <C>obj</C>. If an object has a parent, <C>JS_GetParent</C> returns a pointer to the parent object. If the object does not have a parent, or the object finalize function is active, <C>JS_GetParent</C> returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_SetParent'/>
<SEEALSOvalue='JS_GetConstructor'/>
</ENTRY>
<ENTRYid='JS_SetParent'>
<TYPEvalue='Function'/>
<SUMMARY>
Sets the parent for an object.
</SUMMARY>
<SYNTAX>
JSBool JS_SetParent(JSContext *cx, JSObject *obj,
JSObject *parent);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Pointer to the object for which to set the parent.<BR/>
</PARAM>
<PARAMname='parent'type='JSObject *'>
Pointer to the parent object to use.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetParent</C> enables you to set the parent object for a specified object. A parent object is part of the enclosing scope chain for an object. Ordinarily you set a parent for an object when you create the object with <C>JS_NewObject</C>, but if you do not set a parent at that time, you can later call <C>JS_SetParent</C> to do so.<P/>
<C>obj</C> is a pointer to an existing JS object, and <C>parent</C> is a pointer to a second existing object of which the first object is a child. If <C>JS_SetParent</C> is successful, it returns <C>JS_TRUE</C>. Otherwise, if it cannot create and fill a parent slot for the object, it returns <C>JS_FALSE</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='proto'type='JSObject *'>
Pointer to the object for which to retrieve a constructor.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetConstructor</C> retrieves the constructor for a specified object, <C>proto</C>. The constructor is a function that builds the object. If successful, <C>JS_GetConstructor</C> returns a pointer to the constructor object.<P/>
If <C>proto</C> does not have any properties, <C>JS_GetConstructor</C> returns <C>NULL</C>. If <C>proto</C> has properties, but it does not have an associated constructor function, <C>JS_GetConstructor</C> reports the lack of a constructor function and then returns <C>NULL</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='clasp'type='JSClass *'>
Pointer to the class to use for the new object.<BR/>
</PARAM>
<PARAMname='proto'type='JSObject *'>
Pointer to the prototype object to use for the new class.<BR/>
</PARAM>
<PARAMname='parent'type='JSObject *'>
Pointer to which to set the new object's __parent__ property.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewObject</C> instantiates a new object based on a specified class, prototype, and parent object. <C>cx</C> is a pointer to a context associated with the runtime in which to establish the new object. <C>clasp</C> is a pointer to an existing class to use for internal methods, such as <C>finalize</C>. <C>proto</C> is an optional pointer to the prototype object with which to associate the new object.<P/>
Set proto to <C>NULL</C> to force JS to assign a prototype object for you. In this case, <C>JS_NewObject</C> attempts to assign the new object the prototype object belonging to clasp, if one is defined there. Otherwise, it creates an empty object stub for the prototype.<P/>
<C>parent</C> is an optional pointer to an existing object to which to set the new object's parent object property. You can set <C>parent</C> to <C>NULL</C> if you do not want to set the parent property.<P/>
On success, <C>JS_NewObject</C> returns a pointer to the newly instantiated object. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<NOTE>
To create a new object that is a property of an existing object, use
<C>JS_DefineObject</C>.
<P/>
</NOTE>
<SEEALSOvalue='JS_ConstructObject'/>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
</ENTRY>
<ENTRYid='JS_ConstructObject'>
<TYPEvalue='Function'/>
<SUMMARY>
Instantiates a new object and invokes its constructor.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='clasp'type='JSClass *'>
Pointer to the class to use for the new object.<BR/>
</PARAM>
<PARAMname='proto'type='JSObject *'>
Pointer to the prototype object to use for the new class.<BR/>
</PARAM>
<PARAMname='parent'type='JSObject *'>
Pointer to which to set the new object's __parent__ property.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ConstructObject</C> instantiates a new object based on a specified class, prototype, and parent object, and then invokes its constructor function. <C>cx</C> is a pointer to a context associated with the runtime in which to establish the new object. <C>clasp</C> is a pointer to an existing class to use for internal methods, such as <C>finalize</C>. <C>proto</C> is an optional pointer to the prototype object with which to associate the new object.<P/>
Set proto to <C>NULL</C> to force JS to assign a prototype object for you. In this case, <C>JS_NewObject</C> attempts to assign the new object the prototype object belonging to clasp, if one is defined there. Otherwise, it creates an empty object stub for the prototype.<P/>
<C>parent</C> is an optional pointer to an existing object to which to set the new object's parent object property. You can set <C>parent</C> to <C>NULL</C> if you do not want to set the parent property.<P/>
On success, <C>JS_ConstructObject</C> returns a pointer to the newly instantiated object. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
</ENTRY>
<ENTRYid='JS_DefineObject'>
<TYPEvalue='Function'/>
<SUMMARY>
Instantiates an object that is a property of another object.
Pointer to a JS context from which to derive runtime information for error reporting.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to which this new object belongs as a property.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the property that encapsulates the new object in <C>obj</C>.<BR/>
</PARAM>
<PARAMname='clasp'type='JSClass *'>
Class to use for the new object.<BR/>
</PARAM>
<PARAMname='proto'type='JSObject *'>
Prototype object to use for the new object.<BR/>
</PARAM>
<PARAMname='flags'type='uintN'>
Property flags for the new object.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefineObject</C> instantiates and names a new object for an existing object, <C>obj</C>. <C>name</C> is the property name to assign to <C>obj</C> to hold the new object, and <C>flags</C> contains the property flags to set for the newly created property. The following table lists possible values you can pass in <C>flags</C>, either singly, or <C>OR</C>'d together:
Property is actually an index into an array of properties, and is cast to a <CODE>const char *</CODE>.</P>
</TD></TR></TABLE >
]]>
<P/>
<C>clasp</C> is a pointer to the base class to use when creating the new object, and <C>proto</C> is an pointer to the prototype upon which to base the new object. If you set <C>proto</C> to <C>NULL</C>, JS sets the prototype object for you. The parent object for the new object is set to <C>obj</C>.<P/>
<C>JS_DefineObject</C> returns a pointer to the newly created property object if successful. If the property already exists, or cannot be created, <C>JS_DefineObject</C> returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_ValueToObject'/>
<SEEALSOvalue='JS_DefineConstDoubles'/>
<SEEALSOvalue='JS_DefineProperties'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_DefineElement'/>
</ENTRY>
<ENTRYid='JS_DefineConstDoubles'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates one or more constant double-valued properties for an object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to create new properties.<BR/>
</PARAM>
<PARAMname='*cds'type='JSConstDoubleSpec *'>
Pointer to an array of structs containing double property values and property names to create. The last array element must contain zero-valued members.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefineConstDoubles</C> creates one or more properties for a specified object, <C>obj</C>, where each property consists of a double value. Each property is automatically assigned attributes as specified in the <C>flags</C> field of the <C>JSConstDoubleSpec</C> struct pointed to by <C>cds</C>. If flags is set to zero, the attributes for the property are automatically set to <C>JSPROP_PERMANENT | JSPROP_READONLY</C>.<P/>
<C>cds</C> is a pointer to the first element of an array of <C>JSConstDoubleSpecs</C>. Each array element defines a single property name and property value to create. The <C>name</C> field of last element of the array must contain a zero value. <C>JS_DefineConstDoubles</C> creates one property for each element in the array what contains a non-zero <C>name</C> field.<P/>
If successful, <C>JS_DefineConstDoubles</C> returns <C>JS_TRUE</C>, indicating it has created all properties listed in the array. Otherwise it returns <C>JS_FALSE</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to create new properties.<BR/>
</PARAM>
<PARAMname='ps'type='JSPropertySpec *'>
Pointer to an array containing names, ids, flags, and getProperty and setProperty method for the properties to create. The last array element must contain zero-valued members.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefineProperties</C> creates one or more properties in a specified object, <C>obj</C>. <P/>
<C>ps</C> is a pointer to the first element of an array of <C>JSPropertySpec</C> structures. Each array element defines a single property: its name, id, flags, and getProperty and setProperty methods. The <C>name</C> field of the last array element must contain zero-valued members. <C>JS_DefineProperties</C> creates one property for each element in the array with a non-zero <C>name</C> field.<P/>
If successful, <C>JS_DefineProperties</C> returns <C>JS_TRUE</C>, indicating it has created all properties listed in the array. Otherwise it returns <C>JS_FALSE</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to create the new property.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name for the property to create.<BR/>
</PARAM>
<PARAMname='value'type='jsval'>
Initial value to assign to the property.<BR/>
</PARAM>
<PARAMname='getter'type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current property value.<BR/>
</PARAM>
<PARAMname='setter'type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new property value.<BR/>
</PARAM>
<PARAMname='flags'type='uintN'>
Property flags.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefineProperty</C> defines a single property in a specified object, <C>obj</C>.<P/>
<C>name</C> is the name to assign to the property in the object. <C>value</C> is a jsval that defines the property's data type and initial value. <C>getter</C> and <C>setter</C> identify the <C>getProperty</C> and <C>setProperty</C> methods for the property, respectively. If you pass null values for these entries, <C>JS_DefineProperties</C> assigns the default <C>getProperty</C> and <C>setProperty</C> methods to this property. <C>flags</C> contains the property flags to set for the newly created property. The following table lists possible values you can pass in <C>flags</C>, either singly, or <C>OR</C>'d together:
Property is actually an index into an array of properties, and is cast to a <CODE>const char *</CODE>.</P>
</TD></TR></TABLE >
]]>
<P/>
</DESCRIPTION>
<NOTE>
While you can assign a <C>setProperty</C> method to a property and set flags to
<C>JSPROP_READONLY</C>, the setter method will not be called on this property.
<P/>
</NOTE>
<DESCRIPTION>
If it successfully creates the property, <C>JS_DefineProperty</C> returns <C>JS_TRUE</C>. If the property already exists, or cannot be created, <C>JS_DefineProperty</C> returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_DefineUCProperty'/>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_DefineConstDoubles'/>
<SEEALSOvalue='JS_DefineProperties'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_DefineElement'/>
</ENTRY>
<ENTRYid='JS_DefineUCProperty'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a single Unicode-encoded property for a specified object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to create the new property.<BR/>
</PARAM>
<PARAMname='name'type='const jschar *'>
Name for the property to create.<BR/>
</PARAM>
<PARAMname='namelen'type='size_t'>
Length of <C>name</C>, in bytes.<BR/>
</PARAM>
<PARAMname='value'type='jsval'>
Initial value to assign to the property.<BR/>
</PARAM>
<PARAMname='getter'type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current property value.<BR/>
</PARAM>
<PARAMname='setter'type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new property value.<BR/>
</PARAM>
<PARAMname='attrs'type='uintN'>
Property flags.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefineUCProperty</C> defines a single Unicode-encoded property in a specified object, <C>obj</C>.<P/>
<C>name</C> is the Unicode-encoded name to assign to the property in the object. <C>namelen</C> is the length, in bytes, of <C>name</C>. <C>value</C> is a jsval that defines the property's data type and initial value. <C>getter</C> and <C>setter</C> identify the <C>getProperty</C> and <C>setProperty</C> methods for the property, respectively. If you pass null values for these entries, <C>JS_DefineUCProperties</C> assigns the default <C>getProperty</C> and <C>setProperty</C> methods to this property. <C>attrs</C> contains the property flags to set for the newly created property. The following table lists possible values you can pass in <C>attrs</C>, either singly, or <C>OR</C>'d together:
Property is actually an index into an array of properties, and is cast to a <CODE>const char *</CODE>.</P>
</TD></TR></TABLE >
]]>
<P/>
</DESCRIPTION>
<NOTE>
While you can assign a <C>setProperty</C> method to a property and set <C>attrs</C> to
<C>JSPROP_READONLY</C>, the setter method will not be called on this property.
<P/>
</NOTE>
<DESCRIPTION>
If it successfully creates the property, <C>JS_DefineUCProperty</C> returns <C>JS_TRUE</C>. If the property already exists, or cannot be created, <C>JS_DefineUCProperty</C> returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_DefineConstDoubles'/>
<SEEALSOvalue='JS_DefineProperties'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_DefineElement'/>
</ENTRY>
<ENTRYid='JS_DefinePropertyWithTinyId'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a single property for a specified object and assigns it an ID number.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to create the new property.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name for the property to create.<BR/>
</PARAM>
<PARAMname='tinyid'type='int8'>
8-bit ID to aid in sharing <C>getProperty</C>/<C>setProperty</C> methods among properties.<BR/>
</PARAM>
<PARAMname='value'type='jsval'>
Initial value to assign to the property.<BR/>
</PARAM>
<PARAMname='getter'type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current property value.<BR/>
</PARAM>
<PARAMname='setter'type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new property value.<BR/>
</PARAM>
<PARAMname='flags'type='uintN'>
Property flags.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefinePropertyWithTinyId</C> defines a single property for a specified object, <C>obj</C>.<P/>
<C>name</C> is the name to assign to the property in the object. <C>value</C> is a jsval that defines the property's data type and initial value.<P/>
<C>tinyid</C> is an 8-bit value that simplifies determining which property to access, and is especially useful in <C>getProperty</C> and <C>setProperty</C> methods that are shared by a number of different properties.<P/>
<C>getter</C> and <C>setter</C> identify the <C>getProperty</C> and <C>setProperty</C> methods for the property, respectively. If you pass null values for these entries, <C>JS_DefinePropertyWithTinyId</C> assigns the default <C>getProperty</C> and <C>setProperty</C> methods to this property. <C>flags</C> contains the property flags to set for the newly created property. The following table lists possible values you can pass in <C>flags</C>, either singly, or <C>OR</C>'d together:
Property is actually an index into an array of properties, and is cast to a <CODE>const char *</CODE>.</P>
</TD></TR></TABLE >
]]>
<P/>
</DESCRIPTION>
<NOTE>
While you can assign a <C>setProperty</C> method to a property and set flags to
<C>JSPROP_READONLY</C>, the setter method will not be called on this property.
<P/>
</NOTE>
<DESCRIPTION>
If it successfully creates the property, <C>JS_DefinePropertyWithTinyId</C> returns <C>JS_TRUE</C>. If the property already exists, or cannot be created, it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_DefineConstDoubles'/>
<SEEALSOvalue='JS_DefineProperties'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineUCProperty'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_DefineUCPropertyWithTinyID'/>
</ENTRY>
<ENTRYid='JS_DefineUCPropertyWithTinyID'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a single, Unicode-encoded property for a specified object and assigns it an ID number.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to create the new property.<BR/>
</PARAM>
<PARAMname='name'type='const jschar *'>
Name for the property to create.<BR/>
</PARAM>
<PARAMname='namelen'type='size_t'>
Length, in bytes, of <C>name</C>.<BR/>
</PARAM>
<PARAMname='tinyid'type='int8'>
8-bit ID to aid in sharing <C>getProperty</C>/<C>setProperty</C> methods among properties.<BR/>
</PARAM>
<PARAMname='value'type='jsval'>
Initial value to assign to the property.<BR/>
</PARAM>
<PARAMname='getter'type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current property value.<BR/>
</PARAM>
<PARAMname='setter'type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new property value.<BR/>
</PARAM>
<PARAMname='attrs'type='uintN'>
Property flags.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefineUCPropertyWithTinyId</C> defines a single, Unicode-encoded property for a specified object, <C>obj</C>.<P/>
<C>name</C> is the Unicode-encoded name to assign to the property in the object. <C>namelen</C> is the length, in bytes, of <C>name</C>. <C>value</C> is a jsval that defines the property's data type and initial value.<P/>
<C>tinyid</C> is an 8-bit value that simplifies determining which property to access, and is especially useful in <C>getProperty</C> and <C>setProperty</C> methods that are shared by a number of different properties.<P/>
<C>getter</C> and <C>setter</C> identify the <C>getProperty</C> and <C>setProperty</C> methods for the property, respectively. If you pass null values for these entries, <C>JS_DefineUCPropertyWithTinyId</C> assigns the default <C>getProperty</C> and <C>setProperty</C> methods to this property. <C>attrs</C> contains the property flags to set for the newly created property. The following table lists possible values you can pass in <C>sttrs</C>, either singly, or <C>OR</C>'d together:
Property is actually an index into an array of properties, and is cast to a <CODE>const char *</CODE>.</P>
</TD></TR></TABLE >
]]>
<P/>
</DESCRIPTION>
<NOTE>
While you can assign a <C>setProperty</C> method to a property and set <C>attrs</C> to
<C>JSPROP_READONLY</C>, the setter method will not be called on this property.
<P/>
</NOTE>
<DESCRIPTION>
If it successfully creates the property, <C>JS_DefineUCPropertyWithTinyId</C> returns <C>JS_TRUE</C>. If the property already exists, or cannot be created, it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_DefineConstDoubles'/>
<SEEALSOvalue='JS_DefineProperties'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineUCProperty'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
</ENTRY>
<ENTRYid='JS_AliasProperty'>
<TYPEvalue='Function'/>
<SUMMARY>
Deprecated. Create an alias for a native property.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to create the alias.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the property for which to create an alias.<BR/>
</PARAM>
<PARAMname='alias'type='const char *'>
Alias name to assign to the property.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_AliasProperty</C> assigns an alternate name for a property associated with a native object. <C>obj</C> is the object to which the property belongs. <C>name</C> is the property's current name in the object, and <C>alias</C> is the alternate name to assign to the property.<P/>
</DESCRIPTION>
<NOTE>
This feature is deprecated, meaning that it is currently supported only for backward compatibility with existing applications. Future versions of the engine may no longer support this function.<P/>
An alias does not replace a property's name; it supplements it, providing a second way to reference a property. If the alias is successfully created and associated with the property, <C>JS_AliasProperty</C> returns <C>JS_TRUE</C>. Creating an alias does not change the length of the property array.<P/>
If the property name you specify does not exist, <C>JS_AliasProperty</C> reports an error, and returns <C>JS_FALSE</C>. If the property is currently out of scope, already exists, or the alias itself cannot be assigned to the property, <C>JS_AliasProperty</C> does not report an error, but returns <C>JS_FALSE</C>.<P/>
Once you create an alias, you can reassign it to other properties as needed. Aliases can also be deleted. Deleting an alias does not delete the property to which it refers.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to search on for the property.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the property to look up.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to a variable into which to store the last retrieved value of the property if it exists. If not, <C>vp</C> is set to <C>JSVAL_VOID</C>.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_LookupProperty</C> examines a specified JS object, <C>obj</C>, for a property named <C>name</C>. If the property exists, <C>vp</C> is set either to the last retrieved value of the property if it exists, or to <C>JSVAL_VOID</C> if it does not, and <C>JS_LookupProperty</C> returns <C>JS_TRUE</C>. On error, such as running out of memory during the search, <C>JS_LookupProperty</C> returns <C>JS_FALSE</C>, and <C>vp</C> is undefined.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_LookupProperty</C> does not distunguish between a property with a value of <C>undefined</C> and a property that does not exist. Use <C>JS_GetPropertyAttributes</C> to distinguish these cases.
</NOTE>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineUCProperty'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineUCPropertyWithTinyID'/>
<SEEALSOvalue='JS_AliasProperty'/>
<SEEALSOvalue='JS_GetProperty'/>
<SEEALSOvalue='JS_SetProperty'/>
<SEEALSOvalue='JS_DeleteProperty'/>
</ENTRY>
<ENTRYid='JS_LookupUCProperty'>
<TYPEvalue='Function'/>
<SUMMARY>
Determines if a specified, Unicode-encoded property exists.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to search on for the property.<BR/>
</PARAM>
<PARAMname='name'type='const jschar *'>
Name of the property to look up.<BR/>
</PARAM>
<PARAMname='namelen'type='size_t'>
Length, in bytes, of <C>name</C>.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to a variable into which to store the last retrieved value of the property if it exists. If not, <C>vp</C> is set to <C>JSVAL_VOID</C>.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_LookupUCProperty</C> examines a specified JS object, <C>obj</C>, for a Unicode-encoded property named <C>name</C>. <C>namelen</C> indicates the size, in bytes, of <C>name</C>. If the property exists, <C>vp</C> is set either to the last retrieved value of the property if it exists, or to <C>JSVAL_VOID</C> if it does not, and <C>JS_LookupProperty</C> returns <C>JS_TRUE</C>. On error, such as running out of memory during the search, <C>JS_LookupProperty</C> returns <C>JS_FALSE</C>, and <C>vp</C> is undefined.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_LookupUCProperty</C> does not distunguish between a property with a value of <C>undefined</C> and a property that does not exist.
</NOTE>
<SEEALSOvalue='JS_LookupProperty'/>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineUCProperty'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineUCPropertyWithTinyID'/>
<SEEALSOvalue='JS_AliasProperty'/>
<SEEALSOvalue='JS_GetProperty'/>
<SEEALSOvalue='JS_SetProperty'/>
<SEEALSOvalue='JS_DeleteProperty'/>
</ENTRY>
<ENTRYid='JS_GetProperty'>
<TYPEvalue='Function'/>
<SUMMARY>
Finds a specified property and retrieves its value.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to search on for the property.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the property to look up.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to a variable into which to store the current value of the property if it exists. If not, <C>vp</C> is set to <C>JSVAL_VOID</C>.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetProperty</C> examines a specified JS object, <C>obj</C>, its scope and prototype links, for a property named <C>name</C>. If the property is not defined on the object in its scope, or in its prototype links, <C>vp</C> is set to <C>JSVAL_VOID</C>.<P/>
If the property exists, <C>JS_GetProperty</C> sets <C>vp</C> to the current value of the property, and returns <C>JS_TRUE</C>. If an error occurs during the search, <C>JS_GetProperty</C> returns <C>JS_FALSE</C>, and <C>vp</C> is undefined.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineUCProperty'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineUCPropertyWithTinyID'/>
<SEEALSOvalue='JS_AliasProperty'/>
<SEEALSOvalue='JS_LookupProperty'/>
<SEEALSOvalue='JS_GetUCProperty'/>
<SEEALSOvalue='JS_SetProperty'/>
<SEEALSOvalue='JS_SetUCProperty'/>
<SEEALSOvalue='JS_DeleteProperty'/>
<SEEALSOvalue='JS_DeleteProperty2'/>
<SEEALSOvalue='JS_DeleteUCProperty2'/>
</ENTRY>
<ENTRYid='JS_GetUCProperty'>
<TYPEvalue='Function'/>
<SUMMARY>
Finds a specified, Unicode-encoded property and retrieves its value.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to search on for the property.<BR/>
</PARAM>
<PARAMname='name'type='const jschar *'>
Name of the property to look up.<BR/>
</PARAM>
<PARAMname='namelen'type='size_t'>
Length, in bytes of the the property name to look up.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to a variable into which to store the current value of the property if it exists. If not, <C>vp</C> is set to <C>JSVAL_VOID</C>.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetUCProperty</C> examines a specified JS object, <C>obj</C>, its scope and prototype links, for a property named <C>name</C>. <C>namelen</C> indicates the size, in bytes, of <C>name</C>. If the property is not defined on the object in its scope, or in its prototype links, <C>vp</C> is set to <C>JSVAL_VOID</C>.<P/>
If the property exists, <C>JS_GetUCProperty</C> sets <C>vp</C> to the current value of the property, and returns <C>JS_TRUE</C>. If an error occurs during the search, <C>JS_GetUCProperty</C> returns <C>JS_FALSE</C>, and <C>vp</C> is undefined.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineUCProperty'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineUCPropertyWithTinyID'/>
<SEEALSOvalue='JS_AliasProperty'/>
<SEEALSOvalue='JS_LookupProperty'/>
<SEEALSOvalue='JS_GetProperty'/>
<SEEALSOvalue='JS_SetProperty'/>
<SEEALSOvalue='JS_SetUCProperty'/>
<SEEALSOvalue='JS_DeleteProperty'/>
<SEEALSOvalue='JS_DeleteProperty2'/>
<SEEALSOvalue='JS_DeleteUCProperty2'/>
</ENTRY>
<ENTRYid='JS_SetProperty'>
<TYPEvalue='Function'/>
<SUMMARY>
Sets the current value of a property belonging to a specified object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to which the property to set belongs.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the property to set.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to the value to set for the property.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetProperty</C> sets the current value of a property for a specified object. If the property does not exist, this function creates it, and inherits its attributes from a like-named property in the object's prototype chain. For properties it creates, <C>JS_SetProperty</C> sets the <C>JSPROP_ENUMERATE</C> attribute in the property's <C>flags</C> field; all other values for the property are undefined.<P/>
<C>name</C> is the property to set, and <C>vp</C> is a pointer to the new value to set for the property. On successfully setting a property to a new value, <C>JS_SetProperty</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
If you attempt to set the value for a read-only property using JavaScript 1.2 or earlier, <C>JS_SetProperty</C> reports an error and returns <C>JS_FALSE</C>. For JavaScript 1.3 and greater, such an attempt is silently ignored.<P/>
If you attempt to set the value for a property that does not exist, and there is a like-named read-only property in the object's prototype chain, <C>JS_SetProperty</C> creates a new read-only property on the object, sets its value to <C>JSVAL_VOID</C>, and reports a read-only violation error.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineUCProperty'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineUCPropertyWithTinyID'/>
<SEEALSOvalue='JS_AliasProperty'/>
<SEEALSOvalue='JS_LookupProperty'/>
<SEEALSOvalue='JS_GetProperty'/>
<SEEALSOvalue='JS_GetUCProperty'/>
<SEEALSOvalue='JS_SetUCProperty'/>
<SEEALSOvalue='JS_DeleteProperty'/>
<SEEALSOvalue='JS_DeleteProperty2'/>
<SEEALSOvalue='JS_DeleteUCProperty2'/>
</ENTRY>
<ENTRYid='JS_SetUCProperty'>
<TYPEvalue='Function'/>
<SUMMARY>
Sets the current value of a Unicode-encoded property belonging to a specified object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to which the property to set belongs.<BR/>
</PARAM>
<PARAMname='name'type='const jschar *'>
Name of the property to set.<BR/>
</PARAM>
<PARAMname='namelen'type='size_t'>
Length, in bytes, of the name of the property to set.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to the value to set for the property.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetUCProperty</C> sets the current value of a property for a specified object. If the property does not exist, this function creates it, and inherits its attributes from a like-named property in the object's prototype chain. For properties it creates, <C>JS_SetUCProperty</C> sets the <C>JSPROP_ENUMERATE</C> attribute in the property's <C>flags</C> field; all other values for the property are undefined.<P/>
<C>name</C> is the property to set, <C>namelen</C> indicates the size, in bytes, of <C>name</C>, and <C>vp</C> is a pointer to the new value to set for the property. On successfully setting a property to a new value, <C>JS_SetUCProperty</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
If you attempt to set the value for a read-only property using JavaScript 1.2 or earlier, <C>JS_SetUCProperty</C> reports an error and returns <C>JS_FALSE</C>. For JavaScript 1.3 and greater, such an attempt is silently ignored.<P/>
If you attempt to set the value for a property that does not exist, and there is a like-named read-only property in the object's prototype chain, <C>JS_SetUCProperty</C> creates a new read-only property on the object, sets its value to <C>JSVAL_VOID</C>, and reports a read-only violation error.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object from which to delete a property.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the property to delete.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DeleteProperty</C> removes a specified property, <C>name</C>, from an object, <C>obj</C>. If an object references a property belonging to a prototype, the property reference is removed from the object, but the prototype's property is not deleted. If deletion is successful, <C>JS_DeleteProperty</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<NOTE>
Per the ECMA standard, <C>JS_DeleteProperty</C> removes read-only properties from objects as long as those properties are not also permanent.<P/>
For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent property, <C>JS_DeleteProperty</C> reports the error before returning <C>JS_FALSE</C>. For JavaScript 1.3, the attempt is silently ignored.<P/>
</NOTE>
<NOTE>
To remove all properties from an object, call <C>JS_ClearScope</C>.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object from which to delete a property.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the property to delete.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to the deleted value.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DeleteProperty2</C> removes a specified property, <C>name</C>, from an object, <C>obj</C>, and stores a pointer to the deleted property in <C>rval</C>. If <C>rval</C> is <C>NULL</C>, the property is deleted. If an object references a property belonging to a prototype, the property reference is removed from the object, but the prototype's property is not deleted. If deletion is successful, <C>JS_DeleteProperty2</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<NOTE>
Per the ECMA standard, <C>JS_DeleteProperty2</C> removes read-only properties from objects as long as those properties are not also permanent.<P/>
For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent property, <C>JS_DeleteProperty2</C> reports the error before returning <C>JS_FALSE</C>. For JavaScript 1.3, the attempt is silently ignored. In both these cases, <C>rval</C> will contain a non-<C>NULL</C> pointer to the undeleted property.<P/>
</NOTE>
<NOTE>
To remove all properties from an object, call <C>JS_ClearScope</C>.
<P/>
</NOTE>
<SEEALSOvalue='JS_PropertyStub'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefineUCProperty'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineUCPropertyWithTinyID'/>
<SEEALSOvalue='JS_AliasProperty'/>
<SEEALSOvalue='JS_LookupProperty'/>
<SEEALSOvalue='JS_GetProperty'/>
<SEEALSOvalue='JS_SetProperty'/>
<SEEALSOvalue='JS_LookupUCProperty'/>
<SEEALSOvalue='JS_GetUCProperty'/>
<SEEALSOvalue='JS_SetUCProperty'/>
<SEEALSOvalue='JS_DeleteProperty'/>
<SEEALSOvalue='JS_DeleteUCProperty2'/>
<SEEALSOvalue='JS_ClearScope'/>
</ENTRY>
<ENTRYid='JS_DeleteUCProperty2'>
<TYPEvalue='Function'/>
<SUMMARY>
Removes a specified Unicode-encoded property from an object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object from which to delete a property.<BR/>
</PARAM>
<PARAMname='name'type='const jschar *'>
Name of the property to delete.<BR/>
</PARAM>
<PARAMname='namelen'type='size_t'>
Length, in bytes, of the property name.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to the deleted value.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DeleteUCProperty2</C> removes a specified property, <C>name</C>, from an object, <C>obj</C>, and stores a pointer to the deleted property in <C>rval</C>. If <C>rval</C> is <C>NULL</C>, the property is deleted. <C>namelen</C> is the size, in bytes, of the property name to delete. If an object references a property belonging to a prototype, the property reference is removed from the object, but the prototype's property is not deleted. If deletion is successful, <C>JS_DeleteUCProperty2</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<NOTE>
Per the ECMA standard, <C>JS_DeleteUCProperty2</C> removes read-only properties from objects as long as those properties are not also permanent.<P/>
For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent property, <C>JS_DeleteUCProperty2</C> reports the error before returning <C>JS_FALSE</C>. For JavaScript 1.3, the attempt is silently ignored. In both these cases, <C>rval</C> will contain a non-<C>NULL</C> pointer to the undeleted property.<P/>
</NOTE>
<NOTE>
To remove all properties from an object, call <C>JS_ClearScope</C>.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object from which to retrieve property attributes.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the property from which to retrieve attributes.<BR/>
</PARAM>
<PARAMname='uintN'type='attrsp *'>
Pointer to the storage area into which to place retrieves attributes.<BR/>
</PARAM>
<PARAMname='foundp'type='JSBool *'>
Flag indicating whether or not the specified property was located.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetPropertyAttributes</C> retrieves the attributes for a specified property, <C>name</C>. <C>cx</C> is the context, and <C>obj</C> is a pointer to the object that owns the property. <C>attrsp</C> is a pointer to the unsigned integer storage area into which to retrieve the attributes.<P/>
If <C>JS_GetPropertyAttributes</C> cannot locate an object with the specified property, it returns <C>JS_FALSE</C>, and both <C>attrsp</C> and <C>foundp</C> are undefined.<P/>
If the specified property or the specified object does not exist, <C>foundp</C> is set to <C>JS_FALSE</C>. If the property exists, but belongs to another object, <C>JS_GetPropertyAttributes</C> then returns <C>JS_FALSE</C>, and <C>attrsp</C> is undefined. If the property exists and it belongs to the object you specify, then foundp is set to <C>JS_TRUE</C>. If <C>JS_GetPropertyAttributes</C> can actually read the current property values, it returns <C>JS_TRUE</C>. Otherwise, it returns <C>JS_FALSE</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to set property attributes.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the property for which to set attributes.<BR/>
</PARAM>
<PARAMname='uintN'type='attrsp'>
Attribute values to set.<BR/>
</PARAM>
<PARAMname='foundp'type='JSBool *'>
Flag indicating whether or not the specified property was located.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetPropertyAttributes</C> sets the attributes for a specified property, <C>name</C>. <C>cx</C> is the context, and <C>obj</C> is a pointer to the object that owns the property. <C>attrsp</C> is an unsigned integer containing the attribute value to set, and can contain 0 or more of the following values <C>OR</C>'d:<P/>
<![CDATA[
<ul><P><LI>
<CODE>JSPROP_ENUMERATE</CODE>: property is visible in for loops.</LI>
<CODE>JSPROP_READONLY</CODE>: property is read-only.<P>
<CODE>JSPROP_PERMANENT</CODE>: property cannot be deleted.<P>
<CODE>JSPROP_EXPORTED</CODE>: property can be exported outside its object.<P>
<CODE>JSPROP_INDEX</CODE>: property is actually an array element.<P></ul>
]]>
If <C>JS_SetPropertyAttributes</C> cannot locate an object with the specified property, it returns <C>JS_FALSE</C>, and <C>foundp</C> is undefined.<P/>
If the specified property or the specified object does not exist, <C>foundp</C> is set to <C>JS_FALSE</C>. Then, iff the property exists, but is associated with a different object, <C>JS_SetPropertyAttributes</C> returns <C>JS_TRUE</C>. Otherwise, it sets <C>foundp</C> to <C>JS_TRUE</C>, and attempts to set the attributes as specified. If the attributes can be set, <C>JS_SetPropertyAttributes</C> returns <C>JS_TRUE</C>. If not, it returns <C>JS_FALSE</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='length'type='jsint'>
Number of elements to include in the array.<BR/>
</PARAM>
<PARAMname='vector'type='jsval *'>
Pointer to the initial values for the array's elements.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewArrayObject</C> creates a new array object in the <C>JSRuntime</C> of the specified <C>JSContext</C>, <C>cx</C>. If array creation is successful, <C>JS_NewArrayObject</C> initializes each element identified by index <C>i</C> from 0 to <C>length - 1</C> to have the value <C>vector[i]</C>, and then returns a pointer to the new object. Otherwise <C>JS_NewArrayObject</C> returns <C>NULL</C>.<P/>
<C>length</C> specifies the number of elements in the array. If <C>length</C> is <C>0</C>, <C>JS_NewArrayObject</C> creates an array object of length 0 and ignores <C>vector</C>.
</DESCRIPTION>
<NOTE>
It is often better to call <C>JS_NewArrayObject(cx, 0, NULL)</C>, store the returned object in a GC root, and then populate its elements with <C>JS_SetElement</C> or <C>JS_DefineElement</C>. This avoids unrooted <C>jsval</C>s in <C>vector</C> from being subject to garbage collection until the new object has been populated.
</NOTE>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
</ENTRY>
<ENTRYid='JS_IsArrayObject'>
<TYPEvalue='Function'/>
<SUMMARY>
Determines if a specified object is of the Array class.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to examine.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_IsArrayObject</C> determines if a specified object, <C>obj</C>, is of the Array class. If the object is of the Array class, <C>JS_IsArrayObject</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
</ENTRY>
<ENTRYid='JS_GetArrayLength'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the number of elements in an array object.
Array object for which the number of array elements.<BR/>
</PARAM>
<PARAMname='lengthp'type='jsint *'>
Variable in which to report the number of array elements.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetArrayLength</C> reports the number of elements in an array object, <C>obj</C>. If the number of elements can be determined, <C>JS_GetArrayLength</C> reports the number of elements in <C>lengthp</C> and returns <C>JS_TRUE</C>. Otherwise, it sets <C>lengthp</C> to <C>NULL</C> and returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
</ENTRY>
<ENTRYid='JS_SetArrayLength'>
<TYPEvalue='Function'/>
<SUMMARY>
Specifies the number of elements for an array object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Array object for which to set the number of array elements.<BR/>
</PARAM>
<PARAMname='length'type='jsint'>
Number of array elements to set.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetArrayLength</C> specifies the number of elements for an array object, <C>obj</C>. <C>length</C> indicates the number of elements. If <C>JS_SetArrayLength</C> successfully sets the number of elements, it returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
You can call <C>JS_SetArrayLength</C> either to set the number of elements for an array object you created without specifying an initial number of elements, or to change the number of elements allocated for an array. If you set a shorter array length on an existing array, the elements that no longer fit in the array are destroyed.<P/>
</DESCRIPTION>
<NOTE>
Setting the number of array elements does not initialize those elements. To
initialize an element call <C>JS_DefineElement</C>. If you call <C>JS_SetArrayLength</C>
on an existing array, and <C>length</C> is less than the highest index number for
previously defined elements, all elements greater than or equal to <C>length</C> are
automatically deleted.
<P/>
</NOTE>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
</ENTRY>
<ENTRYid='JS_HasArrayLength'>
<TYPEvalue='Function'/>
<SUMMARY>
Determines if an object has an array length property.
<C>JS_HasArrayLength</C> determines if an object, <C>obj</C>, has a length property. If the property exists, <C>JS_HasArrayLength</C> returns the current value of the property in <C>lengthp</C>.<P/>
On success, <C>JS_HasArrayLength</C> returns <C>JS_TRUE</C>, and <C>lengthp</C> indicates the current value of the array property. On failure, <C>JS_HasArrayLength</C> returns <C>JS_FALSE</C>, and <C>lengthp</C> is undefined.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
</ENTRY>
<ENTRYid='JS_DefineElement'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a single element or numeric property for a specified object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to create the new element.<BR/>
</PARAM>
<PARAMname='index'type='jsint'>
Array index number for the element to define.<BR/>
</PARAM>
<PARAMname='value'type='jsval'>
Initial value to assign to the element.<BR/>
</PARAM>
<PARAMname='getter'type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current element value.<BR/>
</PARAM>
<PARAMname='setter'type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new element value.<BR/>
</PARAM>
<PARAMname='flags'type='uintN'>
Property flags.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefineElement</C> defines a single element or numeric property for a specified object, <C>obj</C>.<P/>
<C>index</C> is the slot number in the array for which to define an element. It may be an valid jsval integer. <C>value</C> is a jsval that defines the element's data type and initial value. <C>getter</C> and <C>setter</C> identify the <C>getProperty</C> and <C>setProperty</C> methods for the element, respectively. If you pass null values for these entries, <C>JS_DefineElement</C> assigns the default <C>getProperty</C> and <C>setProperty</C> methods to this element. <C>flags</C> contains the property flags to set for the newly created element. The following table lists possible values you can pass in <C>flags</C>, either singly, or <C>OR</C>'d together:
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to create the alias.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the element for which to create an alias. This name corresponds to a string representation of the element's current index number.<BR/>
</PARAM>
<PARAMname='alias'type='jsint'>
Alias number to assign to the element.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_AliasElement</C> assigns an alternate index number for an element or numeric property associated with a native object. <C>obj</C> is the object to which the element belongs. <C>name</C> is the element's current index in the object, and <C>alias</C> is the alternate index to assign to the element.<P/>
</DESCRIPTION>
<NOTE>
This feature is deprecated, meaning that it is currently supported only for backward compatibility with existing applications. Future versions of the engine may no longer support this function.<P/>
An alias does not replace an element's current index number; it supplements it, providing a second way to reference the element. If the alias is successfully created and associated with the property, <C>JS_AliasElement</C> returns <C>JS_TRUE</C>. Adding an alias element does not change the element array length.<P/>
If the property name you specify does not exist, <C>JS_AliasElement</C> reports an error, and returns <C>JS_FALSE</C>. If the element is currently out of scope, already exists, or the alias itself cannot be assigned to the element, <C>JS_AliasElement</C> does not report an error, but returns <C>JS_FALSE</C>.<P/>
Once you create an alias, you can reassign it to other elements as needed. Aliases can also be deleted. Deleting an alias does not delete the element to which it refers.<P/>
</NOTE>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
<DEPRECATED/>
</ENTRY>
<ENTRYid='JS_LookupElement'>
<TYPEvalue='Function'/>
<SUMMARY>
Determines if a specified element or numeric property exists.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object to search on for the element.<BR/>
</PARAM>
<PARAMname='index'type='jsint'>
Index number of the element to look up.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to a variable into which to store the current value of the element if it has a value. If not, <C>vp</C> is set to <C>JSVAL_VOID</C>.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_LookupElement</C> examines a specified JS object, <C>obj</C>, for an element or numeric property numbered <C>index</C>. If the element exists, <C>vp</C> is set either to the current value of the property if it has a value, or to <C>JSVAL_VOID</C> if it does not, and <C>JS_LookupElement</C> returns <C>JS_TRUE</C>. On error, such as running out of memory during the search, <C>JS_LookupElement</C> returns <C>JS_FALSE</C>, and <C>vp</C> is undefined.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_LookupElement</C> does not distunguish between a property with a value of <C>undefined</C> and a property that does not exist.
</NOTE>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
</ENTRY>
<ENTRYid='JS_GetElement'>
<TYPEvalue='Function'/>
<SUMMARY>
Finds specified element or numeric property associated with an object or the object's class and retrieves its current value.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Array object to search on for the element.<BR/>
</PARAM>
<PARAMname='index'type='jsint'>
Index number of the element to look up.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to a variable into which to store the current value of the element if it has a value. If not, <C>vp</C> is set to <C>JSVAL_VOID</C>.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_GetElement</C> examines a specified JS object, <C>obj</C>, its scope and prototype links, for an element or numeric property numbered <C>index</C>. <P/>
If the element exists, <C>JS_GetElement</C> sets <C>vp</C> to the current value of the element if it has a value, or to <C>JSVAL_VOID</C> if it does not, and returns <C>JS_TRUE</C>. If an error occurs during the search, <C>JS_GetElement</C> returns <C>JS_FALSE</C>, and <C>vp</C> is undefined.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
</ENTRY>
<ENTRYid='JS_SetElement'>
<TYPEvalue='Function'/>
<SUMMARY>
Sets the current value of an element or numeric property belonging to a specified object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Array object to which the element to set belongs.<BR/>
</PARAM>
<PARAMname='index'type='jsint'>
Index number of the element to set.<BR/>
</PARAM>
<PARAMname='vp'type='jsval *'>
Pointer to the value to set for the element.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetElement</C> sets the current value of an element or numeric property for a specified object. If the element does not exist, this function creates it, and inherits its attributes from a like-named element in the object's prototype chain. For elements it creates, <C>JS_SetElement</C> sets the <C>JSPROP_ENUMERATE</C> attribute in the element's <C>flags</C> field; all other values for the property are undefined.<P/>
<C>index</C> is element number to set, and <C>vp</C> is a pointer to the new value to set for the element. On successfully setting an element to a new value, <C>JS_SetElement</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
If you attempt to set the value for a read-only element using JavaScript 1.2 or earlier, <C>JS_SetElement</C> reports an error and returns <C>JS_FALSE</C>. For JavaScript 1.3 and greater, such an attempt is silently ignored.<P/>
If you attempt to set the value for an element that does not exist, and there is a like-named read-only element in the object's prototype chain, <C>JS_SetElement</C> creates a new read-only element on the object, sets its value to <C>JSVAL_VOID</C>, and reports a read-only violation error.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
</ENTRY>
<ENTRYid='JS_DeleteElement'>
<TYPEvalue='Function'/>
<SUMMARY>
Public. Removes a specified element or numeric property from an object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object from which to delete an element.<BR/>
</PARAM>
<PARAMname='index'type='jsint'>
Index number of the element to delete.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DeleteElement</C> removes a specified element or numeric property, <C>index</C>, from an object, <C>obj</C>. If an object references an element belonging to a prototype, the element reference is removed from the object, but the prototype's element is not deleted. If deletion is successful, <C>JS_DeleteElement</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent or read-only element, <C>JS_DeleteProperty</C> reports the error before returning <C>JS_FALSE</C>. For JavaScript 1.3, the attempt is silently ignored.<P/>
</DESCRIPTION>
<NOTE>
To remove all elements and properties from an object, call <C>JS_ClearScope</C>.
<P/>
</NOTE>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement2'/>
<SEEALSOvalue='JS_ClearScope'/>
</ENTRY>
<ENTRYid='JS_DeleteElement2'>
<TYPEvalue='Function'/>
<SUMMARY>
Removes a specified element or numeric property from an object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object from which to delete an element.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name of the element to delete.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to the deleted value.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DeleteElement2</C> removes a specified element, <C>name</C>, from an object, <C>obj</C>, and stores a pointer to the deleted element in <C>rval</C>. If <C>rval</C> is <C>NULL</C>, the element is deleted. If an object references an element belonging to a prototype, the element reference is removed from the object, but the prototype's element is not deleted. If deletion is successful, <C>JS_DeleteElement2</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<NOTE>
Per the ECMA standard, <C>JS_DeleteElement2</C> removes read-only elements from objects as long as those elements are not also permanent.<P/>
For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent element, <C>JS_DeleteElement2</C> reports the error before returning <C>JS_FALSE</C>. For JavaScript 1.3, the attempt is silently ignored. In both these cases, <C>rval</C> will contain a non-<C>NULL</C> pointer to the undeleted element.<P/>
</NOTE>
<NOTE>
To remove all elements and properties from an object, call <C>JS_ClearScope</C>.
<P/>
</NOTE>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_IsArrayObject'/>
<SEEALSOvalue='JS_GetArrayLength'/>
<SEEALSOvalue='JS_SetArrayLength'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_AliasElement'/>
<SEEALSOvalue='JS_LookupElement'/>
<SEEALSOvalue='JS_GetElement'/>
<SEEALSOvalue='JS_SetElement'/>
<SEEALSOvalue='JS_DeleteElement'/>
<SEEALSOvalue='JS_ClearScope'/>
</ENTRY>
<ENTRYid='JS_ClearScope'>
<TYPEvalue='Function'/>
<SUMMARY>
Removes all properties associated with an object.
</SUMMARY>
<SYNTAX>
void JS_ClearScope(JSContext *cx, JSObject *obj);
<PARAMname='cx'type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object from which to delete all properties.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ClearScope</C> removes all properties and elements from <C>obj</C> in a single operation. To remove a single property from an object, call <C>JS_DeleteProperty</C>, and to remove a single array object element, call <C>JS_DeleteElement</C>.<P/>
<C>JS_Enumerate</C> enumerates all properties of a specified object, <C>obj</C>, and returns an array of property IDs for them. Enumeration occurs in a specified <C>JSContext</C>, <C>cx</C>.<P/>
On success, <C>JS_Enumerate</C> returns a pointer to an array of property IDs. On failure, it returns <C>NULL</C>.<P/>
<C>JS_CheckAccess</C> determines the scope of access to an object, <C>obj</C>, and its scope chain. Checking occurs in a specified <C>JSContext</C>, <C>cx</C>.<P/>
<C>id</C> is the JS ID of a property belonging to the object. <C>mode</C> determines the scope of the access check, and can be one or more of the following enumerated values <C>OR</C>'d:<P/>
<![CDATA[
<ul><P><LI>
<CODE>JSACC_PROTO</CODE>: Permission is granted to check both the object itself and its underlying propotype object.</LI>
<P><LI>
<CODE>JSACC_PARENT</CODE>: Permission is granted to check both the object itself and its underlying parent object.</LI>
<P><LI>
<CODE>JSACC_IMPORT</CODE>: Permission is granted to check an imported object.</LI>
<P><LI>
<CODE>JSACC_WATCH</CODE>: Permission is granted to check a debugger watch object.</LI>
</ul>
]]>
On success, <C>JS_CheckAccess</C> returns <C>JS_TRUE</C>, <C>vp</C> points to the current value of the specified property, identified by <C>id</C>, and <C>attrsp</C> points to the value of the attribute flag for that property. On failure, <C>JS_CheckAccess</C> returns <C>JS_FALSE</C>, and both <C>vp</C> and <C>attrsp</C> are undefined.<P/>
</DESCRIPTION>
</ENTRY>
<ENTRYid='JS_NewFunction'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new JS function that wraps a native C function.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='call'type='JSNative'>
Native C function call wrapped by this function. <BR/>
</PARAM>
<PARAMname='nargs'type='uintN'>
Number of arguments that are passed to the underlying C function.<BR/>
</PARAM>
<PARAMname='flags'type='uintN'>
Function attributes. <BR/>
</PARAM>
<PARAMname='parent'type='JSObject *'>
Pointer to the parent object for this function.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name to assign to the new function. If you do not assign a name to the function, it is assigned the name "anonymous".<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewFunction</C> creates a new JS function based on the parameters you pass. <C>call</C> is a native C function call that this function wraps. If you are not wrapping a native function, use <C>JS_DefineFunction</C>, instead. <C>nargs</C> is the number of arguments passed to the underlying C function. JS uses this information to allocate space for each argument.<P/>
<C>flags</C> lists the attributes to apply to the function. Currently documented attributes, <C>JSFUN_BOUND_METHOD</C> and <C>JSFUN_GLOBAL_PARENT</C>, are deprecated and should no longer be used. They continue to be supported only for existing applications that already depend on them.<P/>
<C>parent</C> is the parent object for this function. If a function has no parent, you can set <C>parent</C> to <C>NULL</C>. <C>name</C> is the name to assign to the function. If you pass an empty value, JS sets the function's name to <C>anonymous</C>.<P/>
If <C>JS_NewFunction</C> is successful, it returns a pointer to the newly created function. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSFUN_BOUND_METHOD'/>
<SEEALSOvalue='JSFUN_GLOBAL_PARENT'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_GetFunctionName'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_CompileFunction'/>
<SEEALSOvalue='JS_CompileUCFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JS_GetFunctionObject'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the object for a specified function.
</SUMMARY>
<SYNTAX>
JSObject * JS_GetFunctionObject(JSFunction *fun);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetFunctionObject</C> retrieves the object for a specified function pointer, <C>fun</C>. All functions are associated with an underlying object. For functions you create with <C>JS_NewFunction</C>, the object is automatically created for you. For functions you define with <C>JS_DefineFunction</C> and <C>JS_DefineFunctions</C>, you specify the object(s) as a parameter.<P/>
<C>JS_GetFunctionObject</C> always returns a pointer to an object.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSFUN_BOUND_METHOD'/>
<SEEALSOvalue='JSFUN_GLOBAL_PARENT'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionName'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_CompileFunction'/>
<SEEALSOvalue='JS_CompileUCFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JS_GetFunctionName'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the given name for a specified function.
</SUMMARY>
<SYNTAX>
const char * JS_GetFunctionName(JSFunction *fun);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetFunctionName</C> retrieves the function name associated with a function pointer, <C>fun</C>. The return value is either the name of a function, or the string "anonymous", which indicates that the function was not assigned a name when created.<P/>
</DESCRIPTION>
<NOTE>
The pointer returned by this function is valid only as long as the specified
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to define functions.<BR/>
</PARAM>
<PARAMname='fs'type='JSFunctionSpec *'>
A null-terminated array of function specifications. Each element of the array defines an individual function, its name, the built-in native C call it wraps, the number of arguments it takes, and its attribute flag.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefineFunctions</C> creates one or more functions and makes them properties (methods) of a specified object, <C>obj</C>. <P/>
<C>fs</C> is a pointer to the first element of an array of <C>JSFunctionSpec</C>. Each array element defines a single function: its name, the native C call wrapped by the function, the number of arguments passed to the function, and its attribute flags. The last element of the array must contain zero values. <C>JS_DefineFunctions</C> creates one function for each non-zero element in the array.<P/>
<C>JS_DefineFunctions</C> always returns <C>JS_TRUE</C>, indicating it has created all functions specified in the array.<P/>
</DESCRIPTION>
<NOTE>
To define only a single function for an object, call <C>JS_DefineFunction</C>.
<P/>
</NOTE>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_DefineConstDoubles'/>
<SEEALSOvalue='JS_DefineProperties'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_GetFunctionName'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_CompileFunction'/>
<SEEALSOvalue='JS_CompileUCFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JS_DefineFunction'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a function and assigns it as a property to a specified JS object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object for which to define a function as a property (method).<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name to assign to the function.<BR/>
</PARAM>
<PARAMname='call'type='JSNative'>
Indicates the built-in, native C call wrapped by this function.<BR/>
</PARAM>
<PARAMname='nargs'type='uintN'>
Number of arguments that are passed to the function when it is called.<BR/>
</PARAM>
<PARAMname='flags'type='uintN'>
Function attributes.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DefineFunction</C> defines a single function and assigns it as a property (method) to a specified object, <C>obj</C>.<P/>
<C>name</C> is the name to assign to the function in the object. <C>call</C> is a built-in, native C call that is wrapped by your function. <C>nargs</C> indicates the number of arguments the function expects to receive. JS uses this information to allocate storage space for each argument.<P/>
<C>flags</C> lists the attributes to apply to the function. Currently documented attributes, <C>JSFUN_BOUND_METHOD</C> and <C>JSFUN_GLOBAL_PARENT</C>, are deprecated and should no longer be used. They continue to be supported only for existing applications that already depend on them.<P/>
If it succesfully creates the property, <C>JS_DefineFunction</C> returns a pointer to the function. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_DefineObject'/>
<SEEALSOvalue='JS_DefineConstDoubles'/>
<SEEALSOvalue='JS_DefineProperties'/>
<SEEALSOvalue='JS_DefineProperty'/>
<SEEALSOvalue='JS_DefinePropertyWithTinyId'/>
<SEEALSOvalue='JS_DefineElement'/>
<SEEALSOvalue='JSFUN_BOUND_METHOD'/>
<SEEALSOvalue='JSFUN_GLOBAL_PARENT'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_CompileFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JS_CloneFunctionObject'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new function object from an existing function structure.
</SUMMARY>
<SYNTAX>
JSObject * JS_CloneFunctionObject(JSContext *cx,
JSObject *funobj, JSObject *parent);
</SYNTAX>
<DESCRIPTION>
<C>JS_CloneFunctionObject</C> creates a new function object. The new object shares an underlying function structure with <C>funobj</C>. <C>funobj</C> becomes the prototype for the newly cloned object, which means that its argument properties are not copied. The cloned object has <C>parent</C> as its parent object.<P/>
On success, <C>JS_CloneFunctionObject</C> returns a pointer to the newly created object. On failure, it returns <C>NULL</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAMname='bytes'type='const char *'>
String containing the script to compile.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Size, in bytes, of the script to compile.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CompileScript</C> compiles a script, <C>bytes</C>, for execution. The script is associated with a JS object. <C>bytes</C> is the string containing the text of the script. <C>length</C> indicates the size of the text version of the script in bytes.<P/>
</DESCRIPTION>
<NOTE>
To compile a script using a Unicode character set, call <C>JS_CompileUCScript</C>
instead of this function.
<P/>
</NOTE>
<DESCRIPTION>
<C>filename</C> is the name of the file (or URL) containing the script. This information in included in error messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the script or file where an error occurred during compilation.<P/>
If a script compiles successfully, <C>JS_CompileScript</C> returns a pointer to the compiled script. Otherwise <C>JS_CompileScript</C> returns <C>NULL</C>, and reports an error.<P/>
</DESCRIPTION>
<NOTE>
To compile a script from an external file source rather than passing the actual
script as an argument, use <C>JS_CompileFile</C> instead of <C>JS_CompileScript</C>.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAMname='principals'type='JSPrincipals *'>
Pointer to the structure holding the security information for this script.<BR/>
</PARAM>
<PARAMname='bytes'type='const char *'>
String containing the script to compile.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Size, in bytes, of the script to compile.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CompileScriptForPrincipals</C> compiles a security-enabled script, <C>bytes</C>, for execution. The script is associated with a JS object.<P/>
<C>principals</C> is a pointer to the <C>JSPrincipals</C> structure that contains the security information to associate with this script.<P/>
<C>bytes</C> is the string containing the text of the script. <C>length</C> indicates the size of the text version of the script in bytes.<P/>
</DESCRIPTION>
<NOTE>
To compile a secure script using a Unicode character set, call
<C>JS_CompileUCScriptForPrincipals</C> instead of this function.
<P/>
</NOTE>
<DESCRIPTION>
<C>filename</C> is the name of the file (or URL) containing the script. This information in included in error messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the script or file where an error occurred during compilation.<P/>
If a script compiles successfully, <C>JS_CompileScriptForPrincipals</C> returns a pointer to the compiled script. Otherwise <C>JS_CompileScriptForPrincipals</C> returns <C>NULL</C>, and reports an error.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAMname='chars'type='const jschar *'>
String containing the script to compile.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Number of Unicode characters in the script to compile.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CompileUCScript</C> compiles a script using a Unicode character set, <C>chars</C>, for execution. The script is associated with a JS object. <C>chars</C> is the Unicode string containing the text of the script. <C>length</C> indicates the size of the script in characters.<P/>
<C>filename</C> is the name of the file (or URL) containing the script. This information in included in error messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the script or file where an error occurred during compilation.<P/>
If a script compiles successfully, <C>JS_CompileUCScript</C> returns a pointer to the compiled script. Otherwise <C>JS_UCCompileScript</C> returns <C>NULL</C>, and reports an error.<P/>
</DESCRIPTION>
<NOTE>
To compile a script from an external file source rather than passing the actual
script as an argument, use <C>JS_CompileFile</C> instead of <C>JS_CompileScript</C>.
<P/>
</NOTE>
<SEEALSOvalue='JS_CompileScript'/>
<SEEALSOvalue='JS_CompileFile'/>
<SEEALSOvalue='JS_DestroyScript'/>
<SEEALSOvalue='JS_DecompileScript'/>
<SEEALSOvalue='JS_ExecuteScript'/>
<SEEALSOvalue='JS_EvaluateScript'/>
</ENTRY>
<ENTRYid='JS_CompileUCScriptForPrincipals'>
<TYPEvalue='Function'/>
<SUMMARY>
Compiles a security-enabled, Unicode-encoded script for execution.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAMname='principals'type='JSPrincipals *'>
Pointer to the structure holding the security information for this script.<BR/>
</PARAM>
<PARAMname='chars'type='const jschar *'>
String containing the script to compile.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Number of Unicode characters in the script to compile.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CompileUCScriptForPrincipals</C> compiles a security-enabled script using a Unicode character set, <C>chars</C>, for execution. The script is associated with a JS object.<P/>
<C>principals</C> is a pointer to the <C>JSPrincipals</C> structure that contains the security information to associate with this script.<P/>
<C>chars</C> is the Unicode string containing the text of the script. <C>length</C> indicates the size of the script in characters.<P/>
<C>filename</C> is the name of the file (or URL) containing the script. This information in messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the script or file where an error occurred during compilation.<P/>
If a script compiles successfully, <C>JS_CompileUCScriptForPrincipals</C> returns a pointer to the compiled script. Otherwise <C>JS_CompileUCScriptForPrincipals</C> returns <C>NULL</C>, and reports an error.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the script to compile.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CompileFile</C> compiles the text of script in an external file location for execution by the JS engine.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_CompileFile</C> is only available if you compile the JS engine with the <C>JSFILE</C> macro defined.<P/>
<C>filename</C> is the name of the file (or URL) containing the script to compile.<P/>
If a script compiles successfully, <C>JS_CompileFile</C> returns a pointer to the compiled script. Otherwise <C>JS_CompileFile</C> returns <C>NULL</C>.<P/>
</NOTE>
<NOTE>
To pass a script as an argument to a function rather than having to specify a file
location, use <C>JS_CompileScript</C> instead of <C>JS_CompileFile</C>.
<P/>
</NOTE>
<SEEALSOvalue='JS_CompileScript'/>
<SEEALSOvalue='JS_DestroyScript'/>
<SEEALSOvalue='JS_DecompileScript'/>
<SEEALSOvalue='JS_ExecuteScript'/>
<SEEALSOvalue='JS_EvaluateScript'/>
</ENTRY>
<ENTRYid='JS_NewScriptObject'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new object and associates a script with it.
<C>JS_NewScriptObject</C> creates a new object, assigns <C>script</C> to the object, and sets the script's object to the newly created object. Object creation occurs in a specified <C>JSContext</C>, <C>cx</C>.<P/>
On success, <C>JS_NewScriptObject</C> returns a pointer to the newly created object. On failure, it returns <C>NULL</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='script'type='JSScript *'>
Compiled script to destroy.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DestroyScript</C> destroys the compiled script object, <C>script</C>, thereby freeing the space allocated to it for other purposes. Generally, after you compile a script you do not want to call <C>JS_DestroyScript</C> until you no longer need to use the script. Othewise you will have to recompile the script to use it again.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the function is associated.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name to assign the newly compiled function.<BR/>
</PARAM>
<PARAMname='nargs'type='uintN'>
Number of arguments to pass to the function.<BR/>
</PARAM>
<PARAMname='argnames'type='const char **'>
Names to assign to the arguments passed to the function.<BR/>
</PARAM>
<PARAMname='bytes'type='const char *'>
String containing the function to compile.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Size, in bytes, of the function to compile.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the function. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CompileFunction</C> compiles a function from a text string, <C>bytes</C>, and associated it with a JS object, <C>obj</C>.<P/>
<C>name</C> is the name to assign to the newly created function. <C>nargs</C> is the number of arguments the function takes, and <C>argnames</C> is a pointer to an array of names to assign each argument. The number of argument names should match the number of arguments specified in <C>nargs</C>.<P/>
<C>bytes</C> is the string containing the text of the function. <C>length</C> indicates the size of the text version of the function in bytes.<P/>
<C>filename</C> is the name of the file (or URL) containing the function. This information in messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the function or file where an error occurred during compilation.<P/>
If a function compiles successfully, <C>JS_CompileFunction</C> returns a pointer to the function. Otherwise <C>JS_CompileFunction</C> returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JSFUN_BOUND_METHOD'/>
<SEEALSOvalue='JSFUN_GLOBAL_PARENT'/>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JS_CompileFunctionForPrincipals'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a security-enabled JS function from a text string.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the function is associated.<BR/>
</PARAM>
<PARAMname='principals'type='JSPrincipals *'>
Pointer to the structure holding the security information for this function.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name to assign the newly compiled function.<BR/>
</PARAM>
<PARAMname='nargs'type='uintN'>
Number of arguments to pass to the function.<BR/>
</PARAM>
<PARAMname='argnames'type='const char **'>
Names to assign to the arguments passed to the function.<BR/>
</PARAM>
<PARAMname='bytes'type='const char *'>
String containing the function to compile.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Size, in bytes, of the function to compile.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the function. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CompileFunctionForPrincipals</C> compiles a security-enabled function from a text string, <C>bytes</C>, and associated it with a JS object, <C>obj</C>.<P/>
<C>principals</C> is a pointer to the <C>JSPrincipals</C> structure that contains the security information to associate with this function.<P/>
<C>name</C> is the name to assign to the newly created function. <C>nargs</C> is the number of arguments the function takes, and <C>argnames</C> is a pointer to an array of names to assign each argument. The number of argument names should match the number of arguments specified in <C>nargs</C>.<P/>
<C>bytes</C> is the string containing the text of the function. <C>length</C> indicates the size of the text version of the function in bytes.<P/>
<C>filename</C> is the name of the file (or URL) containing the function. This information in messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the function or file where an error occurred during compilation.<P/>
If a function compiles successfully, <C>JS_CompileFunctionForPrincipals</C> returns a pointer to the function. Otherwise <C>JS_CompileFunctionForPrincipals</C> returns <C>NULL</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the function is associated.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name to assign the newly compiled function.<BR/>
</PARAM>
<PARAMname='nargs'type='uintN'>
Number of arguments to pass to the function.<BR/>
</PARAM>
<PARAMname='argnames'type='const char **'>
Names to assign to the arguments passed to the function.<BR/>
</PARAM>
<PARAMname='chars'type='const jschar *'>
Unicode string containing the function to compile.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Size, in Unicode characters, of the function to compile.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the function. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CompileUCFunction</C> compiles a function from a Unicode-encoded character string, <C>chars</C>, and associated it with a JS object, <C>obj</C>.<P/>
<C>name</C> is the name to assign to the newly created function. <C>nargs</C> is the number of arguments the function takes, and <C>argnames</C> is a pointer to an array of names to assign each argument. The number of argument names should match the number of arguments specified in <C>nargs</C>.<P/>
<C>chars</C> is the Unicode-encoded string containing the function. <C>length</C> indicates the size of the function in Unicode characters.<P/>
<C>filename</C> is the name of the file (or URL) containing the function. This information in messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the function or file where an error occurred during compilation.<P/>
If a function compiles successfully, <C>JS_CompileUCFunction</C> returns a pointer to the function. Otherwise <C>JS_CompileUCFunction</C> returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_CompileFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JS_CompileUCFunctionForPrincipals'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a JS function with security informtion from a Unicode-encoded character string.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the function is associated.<BR/>
</PARAM>
<PARAMname='principals'type='JSPrincipals *'>
Pointer to the structure holding the security information for this function.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
Name to assign the newly compiled function.<BR/>
</PARAM>
<PARAMname='nargs'type='uintN'>
Number of arguments to pass to the function.<BR/>
</PARAM>
<PARAMname='argnames'type='const char **'>
Names to assign to the arguments passed to the function.<BR/>
</PARAM>
<PARAMname='chars'type='const jschar *'>
Unicode string containing the function to compile.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Size, in Unicode characters, of the function to compile.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the function. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CompileUCFunctionForPrincipals</C> compiles a security-enabled function from a Unicode-encoded character string, <C>chars</C>, and associated it with a JS object, <C>obj</C>.<P/>
<C>principals</C> is a pointer to the <C>JSPrincipals</C> structure that contains the security information to associate with this function.<P/>
<C>name</C> is the name to assign to the newly created function. <C>nargs</C> is the number of arguments the function takes, and <C>argnames</C> is a pointer to an array of names to assign each argument. The number of argument names should match the number of arguments specified in <C>nargs</C>.<P/>
<C>chars</C> is the Unicode-encoded string containing the function. <C>length</C> indicates the size of the function in Unicode characters.<P/>
<C>filename</C> is the name of the file (or URL) containing the function. This information is included in messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the function or file where an error occurred during compilation.<P/>
If a function compiles successfully, <C>JS_CompileUCFunctionForPrincipals</C> returns a pointer to the function. Otherwise <C>JS_CompileUCFunctionForPrincipals </C>returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_CompileUCFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
</ENTRY>
<ENTRYid='JS_DecompileScript'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates the source code of a script from a script's compiled form.
<C>JS_DecompileScript</C> creates the source code version of a script from a script's compiled form, <C>script</C>. <C>name</C> is the name you assign to the text version of the script; it is used only for debugging the source code version produced by this function.<P/>
If successful, <C>JS_DecompileScript</C> returns a string containing the source code of the script. Otherwise, it returns <C>NULL</C>. The source code generated by this function is accurate but lacks function declarations. In order to make it suitable for recompiling, you must edit the code to add the function declarations, or call <C>JS_DecompileFunction</C> on a compiled version of each function to generate the function declarations.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_CompileScript'/>
<SEEALSOvalue='JS_CompileFile'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DestroyScript'/>
<SEEALSOvalue='JS_ExecuteScript'/>
<SEEALSOvalue='JS_EvaluateScript'/>
</ENTRY>
<ENTRYid='JS_DecompileFunction'>
<TYPEvalue='Function'/>
<SUMMARY>
Generates the complete source code of a function declaration from a compiled function.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='fun'type='JSFunction *'>
Function to decompile.<BR/>
</PARAM>
<PARAMname='indent'type='uintN'>
Number of spaces to use for indented code.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DecompileFunction</C> generates the complete source code of a function declaration from a function's compiled form, <C>fun</C>.<P/>
If successful, <C>JS_DecompileFunction</C> returns a string containing the text of the function. Otherwise, it returns <C>NULL</C>.<P/>
If you decompile a function that does not make a native C call, then the text created by <C>JS_DecompileFunction</C> is a complete function declaration suitable for re-parsing. If you decompile a function that makes a native C call, the body of the function contains the text "[native code]" and cannot be re-parsed.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_CompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JS_DecompileFunctionBody'>
<TYPEvalue='Function'/>
<SUMMARY>
Generates the source code representing the body of a function, minus the <C>function</C> keyword, name, parameters, and braces.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='fun'type='JSFunction *'>
Function to decompile.<BR/>
</PARAM>
<PARAMname='indent'type='uintN'>
Number of spaces to use for indented code.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_DecompileFunctionBody</C> generates the source code of a function's body, minus the <C>function</C> keyword, name, parameters, and braces, from a function's compiled form, <C>fun</C>.<P/>
If successful, <C>JS_DecompileFunctionBody</C> returns a string containing the source code of the function body. Otherwise, it returns <C>NULL</C>.<P/>
The source code generated by this function is accurate but unadorned and is not suitable for recompilation without providing the function's declaration. If you decompile a function that makes a native C call, the body of the function only contains the text "[native code]".<P/>
</DESCRIPTION>
<NOTE>
To decompile a complete function, including its body and declaration, call
<C>JS_DecompileFunction</C> instead of <C>JS_DecompileFunctionBody</C>.
Pointer to the value from the last executed expression statement processed in the script.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ExecuteScript</C> executes a previously compiled script, <C>script</C>. On successful completion, <C>rval</C> is a pointer to a variable that holds the value from the last executed expression statement processed in the script.<P/>
If a script executes successfully, <C>JS_ExecuteScript</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>. On failure, your application should assume that <C>rval</C> is undefined.<P/>
</DESCRIPTION>
<NOTE>
To execute an uncompiled script, compile it with <C>JS_CompileScript</C>, and
then call <C>JS_ExecuteScript</C>, or call <C>JS_EvaluateScript</C> to both compile and
JS context in which the script compiles and executes.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAMname='bytes'type='const char *'>
String containing the script to compile and execute.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Size, in bytes, of the script to compile and execute.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to the value from the last executed expression statement processed in the script.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_EvaluateScript</C> compiles and executes a script associated with a JS object, <C>obj</C>. On successful completion, <C>rval</C> is a pointer to a variable that holds the value from the last executed expression statement processed in the script.<P/>
<C>bytes</C> is the string containing the text of the script. <C>length</C> indicates the size of the text version of the script in bytes.<P/>
<C>filename</C> is the name of the file (or URL) containing the script. This information in messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the script or file where an error occurred during compilation.<P/>
If a script compiles and executes successfully, <C>JS_EvaluateScript</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>. On failure, your application should assume that <C>rval</C> is undefined.<P/>
JS context in which the script compiles and executes.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAMname='chars'type='const jschar *'>
Unicode character array ontaining the script to compile and execute.<BR/>
</PARAM>
<PARAMname='length'type='uintN'>
Size, in Unicode characters, of the script to compile and execute.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to the value from the last executed expression statement processed in the script.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_EvaluateUCScript</C> compiles and executes a script associated with a JS object, <C>obj</C>. On successful completion, <C>rval</C> is a pointer to a variable that holds the value from the last executed expression statement processed in the script.<P/>
<C>chars</C> is the Unicode character array containing the text of the script. <C>length</C> indicates the size of the text version of the script in Unicode characters.<P/>
<C>filename</C> is the name of the file (or URL) containing the script. This information is included in messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the script or file where an error occurred during compilation.<P/>
If a script compiles and executes successfully, <C>JS_EvaluateUCScript</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>. On failure, your application should assume that <C>rval</C> is undefined.<P/>
JS context in which the script compiles and executes.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAMname='principals'type='JSPrincipals *'>
Pointer to the structure holding the security information for this script.<BR/>
</PARAM>
<PARAMname='bytes'type='const char *'>
String containing the script to compile and execute.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Size, in bytes, of the script to compile and execute.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to the value from the last executed expression statement processed in the script.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_EvaluateScriptForPrincipals</C> compiles and executes a script associated with a JS object, <C>obj</C>. On successful completion, <C>rval</C> is a pointer to a variable that holds the value from the last executed expression statement processed in the script.<P/>
<C>principals</C> is a pointer to the <C>JSPrincipals</C> structure that contains the security information to associate with this script.<P/>
<C>bytes</C> is the string containing the text of the script. <C>length</C> indicates the size of the text version of the script in bytes.<P/>
<C>filename</C> is the name of the file (or URL) containing the script. This information in messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the script or file where an error occurred during compilation.<P/>
If a secure script compiles and executes successfully, <C>JS_EvaluateScriptForPrincipals</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>. On failure, your application should assume that <C>rval</C> is undefined.<P/>
JS context in which the script compiles and executes.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAMname='principals'type='JSPrincipals *'>
Pointer to the structure holding the security information for this script.<BR/>
</PARAM>
<PARAMname='chars'type='const jschar *'>
Unicode-encoded character array containing the script to compile and execute.<BR/>
</PARAM>
<PARAMname='length'type='uintN'>
Size, in Unicode characters, of the script to compile and execute.<BR/>
</PARAM>
<PARAMname='filename'type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAMname='lineno'type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to the value from the last executed expression statement processed in the script.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_EvaluateUCScriptForPrincipals</C> compiles and executes a Unicode-encoded script associated with a JS object, <C>obj</C>. On successful completion, <C>rval</C> is a pointer to a variable that holds the value from the last executed expression statement processed in the script.<P/>
<C>principals</C> is a pointer to the <C>JSPrincipals</C> structure that contains the security information to associate with this script.<P/>
<C>chars</C> is the Unicode-encoded character array containing the text of the script. <C>length</C> indicates the number of characters in the text version of the script.<P/>
<C>filename</C> is the name of the file (or URL) containing the script. This information is included in messages if an eror occurs during compilation. Similarly, <C>lineno</C> is used to report the line number of the script or file where an error occurred during compilation.<P/>
If a secure script compiles and executes successfully, <C>JS_EvaluateUCScriptForPrincipals</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>. On failure, your application should assume that <C>rval</C> is undefined.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
The "current" object on which the function operates; the object specified here is "this" when the function executes.<BR/>
</PARAM>
<PARAMname='*fun'type='JSFunction *'>
Pointer to the function to call.<BR/>
</PARAM>
<PARAMname='argc'type='uintN'>
Number of arguments you are passing to the function.<BR/>
</PARAM>
<PARAMname='argv'type='jsval *'>
Pointer to the array of argument values to pass to the function.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to a variable to hold the return value from the function call.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CallFunction</C> calls a specified function, <C>fun</C>, on an object, <C>obj</C>. In terns of function execution, the object is treated as <B>this</B>.<P/>
</DESCRIPTION>
<NOTE>
To call a method on an object, use <C>JS_CallFunctionName</C>.
<P/>
</NOTE>
<DESCRIPTION>
In <C>argc</C>, indicate the number of arguments passed to the function. In <C>argv</C>, pass a pointer to the actual argument values to use. There should be one value for each argument you pass to the function; the number of arguments you pass may be different from the number of arguments defined for the function.by the function.<P/>
<C>rval</C> is a pointer to a variable that will hold the function's return value, if any, on successful function execution.<P/>
If the called function executes successfully, <C>JS_CallFunction</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>, and <C>rval</C> is undefined.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_CompileFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_CallFunctionValue'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JS_CallFunctionName'>
<TYPEvalue='Function'/>
<SUMMARY>
Calls a function-valued property belonging to an object.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
The object containing the method to execute.<BR/>
</PARAM>
<PARAMname='name'type='const char *'>
The name of the function to execute.<BR/>
</PARAM>
<PARAMname='argc'type='uintN'>
Number of arguments you are passing to the function.<BR/>
</PARAM>
<PARAMname='argv'type='jsval *'>
Pointer to the array of argument values to pass to the function.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to a variable to hold the return value from the function call.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CallFunctionName</C> executes a function-valued property, <C>name</C>, belonging to a specified JS object, <C>obj</C>.<P/>
</DESCRIPTION>
<NOTE>
To call a function stored in a <C>jsval</C>, use <C>JS_CallFunctionValue</C>.
<P/>
</NOTE>
<DESCRIPTION>
In <C>argc</C>, indicate the number of arguments passed to the function. In <C>argv</C>, pass a pointer to the actual argument values to use. There should be one value for each argument you pass to the function; the number of arguments you pass may be different from the number of arguments defined for the function.by the function.<P/>
<C>rval</C> is a pointer to a variable that will hold the function's return value, if any, on successful function execution.<P/>
If the called function executes successfully, <C>JS_CallFunctionName</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>, and <C>rval</C> is undefined.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='obj'type='JSObject *'>
The "current" object on which the function operates; the object specified here is "this" when the function executes.<BR/>
</PARAM>
<PARAMname='fval'type='jsval'>
The jsval containing the function to execute.<BR/>
</PARAM>
<PARAMname='argc'type='uintN'>
Number of arguments you are passing to the function.<BR/>
</PARAM>
<PARAMname='argv'type='jsval *'>
Pointer to the array of argument values to pass to the function.<BR/>
</PARAM>
<PARAMname='rval'type='jsval *'>
Pointer to a variable to hold the return value from the function call.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_CallFunctionValue</C> executes a function referenced by a <C>jsval</C>, <C>fval</C>, on an object, <C>obj</C>. In terns of function execution, the object is treated as <B>this</B>.<P/>
In <C>argc</C>, indicate the number of arguments passed to the function. In <C>argv</C>, pass a pointer to the actual argument values to use. There should be one value for each argument you pass to the function; the number of arguments you pass may be different from the number of arguments defined for the function.by the function.<P/>
<C>rval</C> is a pointer to a variable that will hold the function's return value, if any, on successful function execution.<P/>
If the called function executes successfully, <C>JS_CallFunctionValue</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>, and <C>rval</C> is undefined.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ValueToFunction'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_GetFunctionObject'/>
<SEEALSOvalue='JS_DefineFunctions'/>
<SEEALSOvalue='JS_DefineFunction'/>
<SEEALSOvalue='JS_CompileFunction'/>
<SEEALSOvalue='JS_DecompileFunction'/>
<SEEALSOvalue='JS_DecompileFunctionBody'/>
<SEEALSOvalue='JS_CallFunction'/>
<SEEALSOvalue='JS_CallFunctionName'/>
<SEEALSOvalue='JS_SetBranchCallback'/>
</ENTRY>
<ENTRYid='JS_SetBranchCallback'>
<TYPEvalue='Function'/>
<SUMMARY>
Specifies a callback function that is automatically called when a script branches backward during execution, when a function returns, and at the end of the script.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='cb'type='JSBranchCallback'>
The object that encapsulates the callback function.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetBranchCallback</C> specifies a callback function that is automatically called when a script branches backward during execution, when a function returns, and at the end of the script. One typical use for a callback is in a client application to enable a user to abort an operation.<P/>
</DESCRIPTION>
</ENTRY>
<ENTRYid='JS_IsRunning'>
<TYPEvalue='Function'/>
<SUMMARY>
Indicates whether or not a script or function is currently executing in a given context.
</SUMMARY>
<SYNTAX>
JSBool JS_IsRunning(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_IsRunning</C> determines if a script or function is currently executing in a specified <C>JSContext</C>, <C>cx</C>. If a script is executing, <C>JS_IsRunning</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_Init'/>
<SEEALSOvalue='JS_Finish'/>
<SEEALSOvalue='JS_NewContext'/>
<SEEALSOvalue='JS_DestroyContext'/>
<SEEALSOvalue='JS_GetRuntime'/>
<SEEALSOvalue='JS_ContextIterator'/>
</ENTRY>
<ENTRYid='JS_IsConstructing'>
<TYPEvalue='Function'/>
<SUMMARY>
Indicates the current constructor status of a given context.
</SUMMARY>
<SYNTAX>
JSBool JS_IsConstructing(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_IsConstructing</C> determines whether or not a function constructor is in action within a given context, <C>cx</C>. If it is, <C>JS_IsConstructing</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='bytes'type='char *'>
Pointer to the byte array containing the text for the JS string to create.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Number of characters in the text string.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewString</C> uses the memory starting at <C>bytes</C> and ending at <C>bytes + length</C> as storage for the JS string it returns. The char array, <C>bytes</C>, must be allocated on the heap using <C>JS_malloc</C>. This means that your application is permitting the JS engine to handle this memory region. Your application should not free or otherwise manipulate this region of memory. <P/>
Using <C>JS_NewString</C> is analogous to assigning <C>char *</C> variables in C, and can save needless copying of data. If successful, <C>JS_NewString</C> returns a pointer to the JS string. Otherwise it returns <C>NULL</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='chars'type='jschar *'>
Pointer to the Unicode-encoded character array containing the text for the JS string to create.<BR/>
</PARAM>
<PARAMname='length'type='size_t'>
Number of characters in the text string.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewUCString</C> uses the memory starting at <C>chars</C> and ending at <C>chars + length</C> as storage for the Unicode-encoded JS string it returns. This means that your application is permitting the JS engine to handle this memory region. Your application should not free or otherwise manipulate this region of memory. <P/>
Using <C>JS_NewUCString</C> is analogous to assigning <C>char *</C> variables in C, and can save needless copying of data. If successful, <C>JS_NewUCString</C> returns a pointer to the JS string. Otherwise it returns <C>NULL</C>.<P/>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='s'type='const char *'>
Pointer to the character array containing the text for the JS string to create.<BR/>
</PARAM>
<PARAMname='n'type='size_t'>
Maximum number of characters to copy from <C>s</C> into the JS string.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewStringCopyN</C> allocates space for a JS string and its underlying storage, and copies as many characters from a C character array, <C>s</C>, as possible, up to <C>n</C> bytes, into the new JS string. If the number of bytes in <C>s</C> is greater than the number of characters specified in <C>n</C>, the new JS string contains a truncated version of the original string. If the number of characters in <C>s</C> is less than the number of bytes specified in <C>n</C>, the new JS string is padded with nulls to the specified length.<P/>
You can use <C>JS_NewStringCopyN</C> to copy binary data, which may contain ASCII 0 characters. You can also use this function when you want to copy only a certain portion of a C string into a JS string.<P/>
If the allocation is successful, <C>JS_NewStringCopyN</C> returns a pointer to the JS string. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewUCString'/>
<SEEALSOvalue='JS_NewUCStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_NewUCStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_InternUCString'/>
<SEEALSOvalue='JS_InternUCStringN'/>
<SEEALSOvalue='JS_GetStringChars'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_GetStringLength'/>
<SEEALSOvalue='JS_CompareStrings'/>
<SEEALSOvalue='JS_malloc'/>
</ENTRY>
<ENTRYid='JS_NewUCStringCopyN'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new Unicode-encoded JS string of a specified size.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='s'type='const jschar *'>
Pointer to the Unicode character array containing the text for the JS string to create.<BR/>
</PARAM>
<PARAMname='n'type='size_t'>
Maximum number of Unicode characters to copy from <C>s</C> into the JS string.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewUCStringCopyN</C> allocates space for a JS string and its underlying storage, and copies as many characters from a Unicode-encoded character array, <C>s</C>, as possible, up to <C>n</C> characters, into the new JS string. If the number of characters in <C>s</C> is greater than the number of characters specified in <C>n</C>, the new JS string contains a truncated version of the original string. If the number of characters in <C>s</C> is less than the number of bytes specified in <C>n</C>, the new JS string is padded with nulls to the specified length.<P/>
You can use <C>JS_NewUCStringCopyN</C> to copy binary data, which may contain ASCII 0 characters. You can also use this function when you want to copy only a certain portion of a Unicode-encoded string into a JS string.<P/>
If the allocation is successful, <C>JS_NewUCStringCopyN</C> returns a pointer to the JS string. Otherwise it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewUCString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_NewUCStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_InternUCString'/>
<SEEALSOvalue='JS_InternUCStringN'/>
<SEEALSOvalue='JS_GetStringChars'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_GetStringLength'/>
<SEEALSOvalue='JS_CompareStrings'/>
<SEEALSOvalue='JS_malloc'/>
</ENTRY>
<ENTRYid='JS_NewStringCopyZ'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new JS string and ensures that the resulting string is null-terminated.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='s'type='const char *'>
Pointer to the character array containing the text for the JS string to create.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewStringCopyZ</C> allocates space for a new JS string and its underlying storage, and then copies the contents of a C character array, <C>s</C>, into the new string. The new JS string is guaranteed to be null-terminated.<P/>
If the allocation is successful, <C>JS_NewStringCopyZ</C> returns a pointer to the JS string. Otherwise it returns an empty string.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewUCString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewUCStringCopyN'/>
<SEEALSOvalue='JS_NewUCStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_InternUCString'/>
<SEEALSOvalue='JS_InternUCStringN'/>
<SEEALSOvalue='JS_GetStringChars'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_GetStringLength'/>
<SEEALSOvalue='JS_CompareStrings'/>
<SEEALSOvalue='JS_malloc'/>
</ENTRY>
<ENTRYid='JS_NewUCStringCopyZ'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new Unicode-encoded JS string and ensures that the resulting string is null-terminated.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='s'type='const jschar *'>
Pointer to the character array containing the text for the JS string to create.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_NewUCStringCopyZ</C> allocates space for a new, Unicode-encoded JS string and its underlying storage, and then copies the contents of a character array, <C>s</C>, into the new string. The new JS string is guaranteed to be null-terminated.<P/>
If the allocation is successful, <C>JS_NewUCStringCopyZ</C> returns a pointer to the JS string. Otherwise it returns an empty string.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewUCString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewUCStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_InternUCString'/>
<SEEALSOvalue='JS_InternUCStringN'/>
<SEEALSOvalue='JS_GetStringChars'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_GetStringLength'/>
<SEEALSOvalue='JS_CompareStrings'/>
<SEEALSOvalue='JS_malloc'/>
</ENTRY>
<ENTRYid='JS_InternString'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new, static JS string whose value is automatically shared by all string literals that are identical.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='s'type='const char *'>
Pointer to the character array containing the text for the JS string to create.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_InternString</C> creates a new JS string with a specified value, <C>s</C>, if it does not already exist. The char array, <C>s</C>, must be allocated on the heap. The JS string is an interned, Unicode version of <C>s</C>, meaning that independent C variables that define a matching string will, when translated to a JS string value using <C>JS_InternString</C>, share the same internal copy of the JS string, rather than define their own, separate copies in memory. Use this function to save space allocation on the heap.<P/>
If it creates or reuses an interned string, <C>JS_InternString</C> returns a pointer to the string. Otherwise, on error, it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewUCString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewUCStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_NewUCStringCopyZ'/>
<SEEALSOvalue='JS_InternUCString'/>
<SEEALSOvalue='JS_InternUCStringN'/>
<SEEALSOvalue='JS_GetStringChars'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_GetStringLength'/>
<SEEALSOvalue='JS_CompareStrings'/>
</ENTRY>
<ENTRYid='JS_InternUCString'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new, static, Unicode-encoded JS string whose value is automatically shared by all string literals that are identical.
<C>JS_InternUCString</C> creates a new, Unicode-encoded JS string with a specified value, <C>s</C>, if it does not already exist. The char array, <C>s</C>, must be allocated on the heap. The JS string is an interned, Unicode version of <C>s</C>, meaning that independent C variables that define a matching string will, when translated to a JS string value using <C>JS_InternUCString</C>, share the same internal copy of the JS string, rather than define their own, separate copies in memory. Use this function to save space allocation on the heap.<P/>
If it creates or reuses an interned string, <C>JS_InternUCString</C> returns a pointer to the string. Otherwise, on error, it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewUCString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewUCStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_NewUCStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_InternUCStringN'/>
<SEEALSOvalue='JS_GetStringChars'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_GetStringLength'/>
<SEEALSOvalue='JS_CompareStrings'/>
</ENTRY>
<ENTRYid='JS_InternUCStringN'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a new, static, Unicode-encoded, JS string of a specified size whose value is automatically shared by all string literals that are identical.
<C>JS_InternUCStringN</C> creates a new, Unicode-encoded JS string with a specified value, <C>s</C>, up to <C>length</C> characters in size, if it does not already exist. If the number of characters in <C>s</C> is greater than the number of characters specified in <C>length</C>, the new JS string contains a truncated version of the original string. If the number of characters in <C>s</C> is less than the number of bytes specified in <C>length</C>, the new JS string is padded with nulls to the specified length. <P/>
The char array, <C>s</C>, must be allocated on the heap. The JS string is an interned, Unicode version of <C>s</C>, meaning that independent C variables that define a matching string will, when translated to a JS string value using <C>JS_InternUCStringN</C>, share the same internal copy of the JS string, rather than define their own, separate copies in memory. Use this function to save space allocation on the heap.<P/>
If it creates or reuses an interned string, <C>JS_InternUCStringN</C> returns a pointer to the string. Otherwise, on error, it returns <C>NULL</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewUCString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewUCStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_NewUCStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_InternUCString'/>
<SEEALSOvalue='JS_GetStringChars'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_GetStringLength'/>
<SEEALSOvalue='JS_CompareStrings'/>
</ENTRY>
<ENTRYid='JS_GetStringChars'>
<TYPEvalue='Function'/>
<SUMMARY>
Retrieves the pointer to a specified string.
</SUMMARY>
<SYNTAX>
jschar * JS_GetStringChars(JSString *str);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetStringChars</C> provides a Unicode-enabled pointer to a JS string, <C>str</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewUCString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewUCStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_NewUCStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_InternUCString'/>
<SEEALSOvalue='JS_InternUCStringN'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_GetStringLength'/>
<SEEALSOvalue='JS_CompareStrings'/>
</ENTRY>
<ENTRYid='JS_GetStringBytes'>
<TYPEvalue='Function'/>
<SUMMARY>
Translates a JS string into a C character array.
</SUMMARY>
<SYNTAX>
char * JS_GetStringBytes(JSString *str);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetStringBytes</C> translates a specified JS string, <C>str</C>, into a C character array. If successful, <C>JS_GetStringBytes</C> returns a pointer to the array. The array is automatically freed when <C>str</C> is finalized by the JavaScript garbage collection mechanism.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_GetStringLength'/>
<SEEALSOvalue='JS_CompareStrings'/>
</ENTRY>
<ENTRYid='JS_GetStringLength'>
<TYPEvalue='Function'/>
<SUMMARY>
Determines the length, in characters, of a JS string.
</SUMMARY>
<SYNTAX>
size_t JS_GetStringLength(JSString *str);
</SYNTAX>
<DESCRIPTION>
<C>JS_GetStringLength</C> reports the length, in characters, of a specified JS string, <C>str</C>. Note that JS strings are stored in Unicode format, so <C>JS_GetStringLength</C> does not report the number of bytes allocated to a string, but the number of characters in the string.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_CompareStrings'/>
</ENTRY>
<ENTRYid='JS_CompareStrings'>
<TYPEvalue='Function'/>
<SUMMARY>
Compares two JS strings, and reports the results of the comparison.
<C>JS_CompareStrings</C> compares two JS strings, <C>str1</C> and <C>str2</C>. If the strings are identical in content and size, <C>JS_CompareStrings</C> returns <C>0</C>.<P/>
If <C>str1</C> is greater than <C>str2</C>, either in terms of its internal alphabetic sort order, or because it is longer in length, <C>JS_CompareStrings</C> returns a positive value.<P/>
If <C>str1</C> is less than <C>str2</C>, either in terms of its internal alphabetic sort order, or because it is shorter in length, <C>JS_CompareStrings</C> returns a negative value.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_GetEmptyStringValue'/>
<SEEALSOvalue='JS_ValueToString'/>
<SEEALSOvalue='JS_ConvertValue'/>
<SEEALSOvalue='JS_NewDouble'/>
<SEEALSOvalue='JS_NewObject'/>
<SEEALSOvalue='JS_NewArrayObject'/>
<SEEALSOvalue='JS_NewFunction'/>
<SEEALSOvalue='JS_NewString'/>
<SEEALSOvalue='JS_NewStringCopyN'/>
<SEEALSOvalue='JS_NewStringCopyZ'/>
<SEEALSOvalue='JS_InternString'/>
<SEEALSOvalue='JS_GetStringBytes'/>
<SEEALSOvalue='JS_GetStringLength'/>
</ENTRY>
<ENTRYid='JS_ReportError'>
<TYPEvalue='Function'/>
<SUMMARY>
Creates a formatted error message to pass to a user-defined error reporting function.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='format'type='const char *'>
Format string to convert into an error message using a standard C sprintf conversion routine.<BR/>
</PARAM>
<PARAMname='...'type=''>
Error message variables to insert into the format string.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_ReportError</C> converts a format string and its arguments, <C>format</C>, into an error message using a sprintf-like conversion routine. The resulting string is automatically passed to the user-defined error reporting mechanism. That mechanism might display the error message in a console or dialog box window (as in Navigator 2.0 and greater), or might write the error message to an error log file maintained by the application.<P/>
Specify an error reporting mechanism for your application using <C>JS_SetErrorReporter</C>.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ReportOutOfMemory'/>
<SEEALSOvalue='JS_SetErrorReporter'/>
</ENTRY>
<ENTRYid='JS_ReportOutOfMemory'>
<TYPEvalue='Function'/>
<SUMMARY>
Reports a memory allocation error for a specified JS execution context.
</SUMMARY>
<SYNTAX>
void JS_ReportOutOfMemory(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
<C>JS_ReportOutOfMemory</C> calls <C>JS_ReportError</C> with a format string set to "out of memory". This function is called by the JS engine when a memory allocation in the JS memory pool fails.<P/>
</DESCRIPTION>
<SEEALSOvalue='JS_ReportError'/>
<SEEALSOvalue='JS_SetErrorReporter'/>
</ENTRY>
<ENTRYid='JS_SetErrorReporter'>
<TYPEvalue='Function'/>
<SUMMARY>
Specifies the error reporting mechanism for an application.
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAMname='er'type='JSErrorReporter'>
The user-defined error reporting function to use in your application.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<C>JS_SetErrorReporter</C> enables you to define and use your own error reporting mechanism in your applications. The reporter you define is automatically passed a <C>JSErrorReport</C> structure when an error occurs and has been parsed by <C>JS_ReportError</C>.<P/>
Typically, the error reporting mechanism you define should log the error where appropriate (such as to a log file), and display an error to the user of your application. The error you log and display can make use of the information passed about the error condition in the <C>JSErrorReport</C> structure.<P/>
