gecko-dev/js/docs/jsref.xml
2004-04-15 16:20:34 +00:00

6919 lines
350 KiB
XML

<?xml version='1.0' encoding='ISO-8859-1' standalone='yes'?>
<!DOCTYPE api>
<API id='JavaScript-1.5'>
<EXTERNALREF name='LXR ID Search' value='http://lxr.mozilla.org/seamonkey/ident?i={e}'/>
<ENTRY id='JSVAL_IS_OBJECT'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSVAL_IS_NUMBER'/>
<SEEALSO value='JSVAL_IS_INT'/>
<SEEALSO value='JSVAL_IS_DOUBLE'/>
<SEEALSO value='JSVAL_IS_STRING'/>
<SEEALSO value='JSVAL_IS_BOOLEAN'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
<SEEALSO value='JSVAL_IS_NULL'/>
<SEEALSO value='JSVAL_IS_VOID'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRY id='JSVAL_IS_NUMBER'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSVAL_IS_OBJECT'/>
<SEEALSO value='JSVAL_IS_INT'/>
<SEEALSO value='JSVAL_IS_DOUBLE'/>
<SEEALSO value='JSVAL_IS_STRING'/>
<SEEALSO value='JSVAL_IS_BOOLEAN'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
<SEEALSO value='JSVAL_IS_NULL'/>
<SEEALSO value='JSVAL_IS_VOID'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRY id='JSVAL_IS_INT'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSVAL_IS_OBJECT'/>
<SEEALSO value='JSVAL_IS_NUMBER'/>
<SEEALSO value='JSVAL_IS_DOUBLE'/>
<SEEALSO value='JSVAL_IS_STRING'/>
<SEEALSO value='JSVAL_IS_BOOLEAN'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
<SEEALSO value='JSVAL_IS_NULL'/>
<SEEALSO value='JSVAL_IS_VOID'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRY id='JSVAL_IS_DOUBLE'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSVAL_IS_OBJECT'/>
<SEEALSO value='JSVAL_IS_NUMBER'/>
<SEEALSO value='JSVAL_IS_INT'/>
<SEEALSO value='JSVAL_IS_STRING'/>
<SEEALSO value='JSVAL_IS_BOOLEAN'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
<SEEALSO value='JSVAL_IS_NULL'/>
<SEEALSO value='JSVAL_IS_VOID'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRY id='JSVAL_IS_STRING'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSVAL_IS_OBJECT'/>
<SEEALSO value='JSVAL_IS_NUMBER'/>
<SEEALSO value='JSVAL_IS_INT'/>
<SEEALSO value='JSVAL_IS_DOUBLE'/>
<SEEALSO value='JSVAL_IS_BOOLEAN'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
<SEEALSO value='JSVAL_IS_NULL'/>
<SEEALSO value='JSVAL_IS_VOID'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRY id='JSVAL_IS_BOOLEAN'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSVAL_IS_OBJECT'/>
<SEEALSO value='JSVAL_IS_NUMBER'/>
<SEEALSO value='JSVAL_IS_INT'/>
<SEEALSO value='JSVAL_IS_DOUBLE'/>
<SEEALSO value='JSVAL_IS_STRING'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
<SEEALSO value='JSVAL_IS_NULL'/>
<SEEALSO value='JSVAL_IS_VOID'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRY id='JSVAL_IS_NULL'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSVAL_IS_OBJECT'/>
<SEEALSO value='JSVAL_IS_NUMBER'/>
<SEEALSO value='JSVAL_IS_INT'/>
<SEEALSO value='JSVAL_IS_DOUBLE'/>
<SEEALSO value='JSVAL_IS_STRING'/>
<SEEALSO value='JSVAL_IS_BOOLEAN'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
<SEEALSO value='JSVAL_IS_VOID'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRY id='JSVAL_IS_PRIMITIVE'>
<TYPE value='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>
<SEEALSO value='JSVAL_IS_OBJECT'/>
<SEEALSO value='JSVAL_IS_NUMBER'/>
<SEEALSO value='JSVAL_IS_INT'/>
<SEEALSO value='JSVAL_IS_DOUBLE'/>
<SEEALSO value='JSVAL_IS_STRING'/>
<SEEALSO value='JSVAL_IS_BOOLEAN'/>
<SEEALSO value='JSVAL_IS_VOID'/>
<SEEALSO value='JSVAL_IS_NULL'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRY id='JSVAL_IS_VOID'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSVAL_IS_OBJECT'/>
<SEEALSO value='JSVAL_IS_NUMBER'/>
<SEEALSO value='JSVAL_IS_INT'/>
<SEEALSO value='JSVAL_IS_DOUBLE'/>
<SEEALSO value='JSVAL_IS_STRING'/>
<SEEALSO value='JSVAL_IS_BOOLEAN'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
<SEEALSO value='JSVAL_IS_NULL'/>
<SEEALSO value='JSVAL_IS_PRIMITIVE'/>
</ENTRY>
<ENTRY id='JSVAL_IS_GCTHING'>
<TYPE value='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>
<SEEALSO value='JSVAL_TO_GCTHING'/>
</ENTRY>
<ENTRY id='JSVAL_TO_GCTHING'>
<TYPE value='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>
<SEEALSO value='JSVAL_IS_GCTHING'/>
</ENTRY>
<ENTRY id='JSVAL_TO_OBJECT'>
<TYPE value='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>
<SEEALSO value='JSVAL_TO_GCTHING'/>
<SEEALSO value='JSVAL_TO_DOUBLE'/>
<SEEALSO value='JSVAL_TO_STRING'/>
<SEEALSO value='OBJECT_TO_JSVAL'/>
<SEEALSO value='DOUBLE_TO_JSVAL'/>
<SEEALSO value='STRING_TO_JSVAL'/>
<SEEALSO value='JS_ValueToObject'/>
</ENTRY>
<ENTRY id='JSVAL_TO_DOUBLE'>
<TYPE value='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>
<SEEALSO value='JSVAL_TO_GCTHING'/>
<SEEALSO value='JSVAL_TO_OBJECT'/>
<SEEALSO value='JSVAL_TO_STRING'/>
<SEEALSO value='OBJECT_TO_JSVAL'/>
<SEEALSO value='DOUBLE_TO_JSVAL'/>
<SEEALSO value='STRING_TO_JSVAL'/>
<SEEALSO value='JS_ValueToNumber'/>
</ENTRY>
<ENTRY id='JSVAL_TO_STRING'>
<TYPE value='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>
<SEEALSO value='JSVAL_TO_GCTHING'/>
<SEEALSO value='JSVAL_TO_OBJECT'/>
<SEEALSO value='JSVAL_TO_STRING'/>
<SEEALSO value='OBJECT_TO_JSVAL'/>
<SEEALSO value='DOUBLE_TO_JSVAL'/>
<SEEALSO value='STRING_TO_JSVAL'/>
<SEEALSO value='JS_ValueToString'/>
</ENTRY>
<ENTRY id='OBJECT_TO_JSVAL'>
<TYPE value='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>
<SEEALSO value='DOUBLE_TO_JSVAL'/>
<SEEALSO value='STRING_TO_JSVAL'/>
</ENTRY>
<ENTRY id='DOUBLE_TO_JSVAL'>
<TYPE value='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>
<SEEALSO value='OBJECT_TO_JSVAL'/>
<SEEALSO value='STRING_TO_JSVAL'/>
</ENTRY>
<ENTRY id='STRING_TO_JSVAL'>
<TYPE value='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>
<SEEALSO value='OBJECT_TO_JSVAL'/>
<SEEALSO value='DOUBLE_TO_JSVAL'/>
</ENTRY>
<ENTRY id='JSVAL_LOCK'>
<TYPE value='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>
<SEEALSO value='JS_AddRoot'/>
<SEEALSO value='JSVAL_IS_GCTHING'/>
<SEEALSO value='JSVAL_TO_GCTHING'/>
<SEEALSO value='JSVAL_UNLOCK'/>
<SEEALSO value='JS_LockGCThing'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JSVAL_UNLOCK'>
<TYPE value='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>
<SEEALSO value='JS_AddRoot'/>
<SEEALSO value='JSVAL_IS_GCTHING'/>
<SEEALSO value='JSVAL_TO_GCTHING'/>
<SEEALSO value='JSVAL_LOCK'/>
<SEEALSO value='JS_LockGCThing'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='INT_FITS_IN_JSVAL'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSVAL_TO_INT'/>
<SEEALSO value='INT_TO_JSVAL'/>
</ENTRY>
<ENTRY id='JSVAL_TO_INT'>
<TYPE value='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>
<SEEALSO value='INT_TO_JSVAL'/>
<SEEALSO value='JSVAL_TO_BOOLEAN'/>
<SEEALSO value='JSVAL_TO_PRIVATE'/>
</ENTRY>
<ENTRY id='INT_TO_JSVAL'>
<TYPE value='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>
<SEEALSO value='JSVAL_TO_INT'/>
<SEEALSO value='BOOLEAN_TO_JSVAL'/>
<SEEALSO value='PRIVATE_TO_JSVAL'/>
</ENTRY>
<ENTRY id='JSVAL_TO_BOOLEAN'>
<TYPE value='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>
<SEEALSO value='BOOLEAN_TO_JSVAL'/>
<SEEALSO value='JSVAL_TO_INT'/>
<SEEALSO value='JSVAL_TO_PRIVATE'/>
</ENTRY>
<ENTRY id='BOOLEAN_TO_JSVAL'>
<TYPE value='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>
<SEEALSO value='JSVAL_TO_BOOLEAN'/>
<SEEALSO value='INT_TO_JSVAL'/>
<SEEALSO value='PRIVATE_TO_JSVAL'/>
</ENTRY>
<ENTRY id='JSVAL_TO_PRIVATE'>
<TYPE value='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>
<SEEALSO value='PRIVATE_TO_JSVAL'/>
<SEEALSO value='JSCLASS_HAS_PRIVATE'/>
</ENTRY>
<ENTRY id='PRIVATE_TO_JSVAL'>
<TYPE value='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>
<SEEALSO value='JSVAL_TO_PRIVATE'/>
<SEEALSO value='INT_FITS_IN_JSVAL'/>
</ENTRY>
<ENTRY id='JSPROP_ENUMERATE'>
<TYPE value='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>
<EXAMPLE desc='The following code fragment illustrates how JSPROP_ENUMERATE can be set for a property structure before you call JS_DefineProperties:'>
JSPropertySpec MyProperty;
.
.
.
MyProperty.flags = MyProperty.flags | JSPROP_ENUMERATE;
</EXAMPLE>
<SEEALSO value='JSPROP_READONLY'/>
<SEEALSO value='JSPROP_PERMANENT'/>
<SEEALSO value='JSPROP_EXPORTED'/>
<SEEALSO value='JSPROP_INDEX'/>
<SEEALSO value='JSPropertySpec'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineProperties'/>
</ENTRY>
<ENTRY id='JSPROP_READONLY'>
<TYPE value='Macro'/>
<SUMMARY>
Flag that indicates a property is read only.
</SUMMARY>
<SYNTAX>
JSPROP_READONLY
</SYNTAX>
<DESCRIPTION>
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>
<SEEALSO value='JSPROP_ENUMERATE'/>
<SEEALSO value='JSPROP_PERMANENT'/>
<SEEALSO value='JSPROP_EXPORTED'/>
<SEEALSO value='JSPROP_INDEX'/>
<SEEALSO value='JSPropertySpec'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineProperties'/>
</ENTRY>
<ENTRY id='JSPROP_PERMANENT'>
<TYPE value='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>
<SEEALSO value='JSPROP_ENUMERATE'/>
<SEEALSO value='JSPROP_READONLY'/>
<SEEALSO value='JSPROP_EXPORTED'/>
<SEEALSO value='JSPROP_INDEX'/>
<SEEALSO value='JSPropertySpec'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineProperties'/>
</ENTRY>
<ENTRY id='JSPROP_EXPORTED'>
<TYPE value='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>
<SEEALSO value='JSPROP_ENUMERATE'/>
<SEEALSO value='JSPROP_READONLY'/>
<SEEALSO value='JSPROP_PERMANENT'/>
<SEEALSO value='JSPROP_INDEX'/>
<SEEALSO value='JSPropertySpec'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineProperties'/>
</ENTRY>
<ENTRY id='JSPROP_INDEX'>
<TYPE value='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>
<SEEALSO value='JSPROP_ENUMERATE'/>
<SEEALSO value='JSPROP_READONLY'/>
<SEEALSO value='JSPROP_PERMANENT'/>
<SEEALSO value='JSPROP_EXPORTED'/>
<SEEALSO value='JSPropertySpec'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineProperties'/>
</ENTRY>
<ENTRY id='JSFUN_BOUND_METHOD'>
<TYPE value='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 method's parent, the object on which the method is called.<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>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JSFUN_GLOBAL_PARENT'>
<TYPE value='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>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JSVAL_VOID'>
<TYPE value='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>
<SEEALSO value='JSVAL_NULL'/>
<SEEALSO value='JSVAL_ZERO'/>
<SEEALSO value='JSVAL_ONE'/>
<SEEALSO value='JSVAL_FALSE'/>
<SEEALSO value='JSVAL_TRUE'/>
<SEEALSO value='JS_NewContext'/>
</ENTRY>
<ENTRY id='JSVAL_NULL'>
<TYPE value='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>
<SEEALSO value='OBJECT_TO_JSVAL'/>
<SEEALSO value='JSVAL_VOID'/>
<SEEALSO value='JSVAL_ZERO'/>
<SEEALSO value='JSVAL_ONE'/>
<SEEALSO value='JSVAL_FALSE'/>
<SEEALSO value='JSVAL_TRUE'/>
<SEEALSO value='JS_NewContext'/>
</ENTRY>
<ENTRY id='JSVAL_ZERO'>
<TYPE value='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>
<SEEALSO value='INT_TO_JSVAL'/>
<SEEALSO value='JSVAL_VOID'/>
<SEEALSO value='JSVAL_NULL'/>
<SEEALSO value='JSVAL_ONE'/>
<SEEALSO value='JSVAL_FALSE'/>
<SEEALSO value='JSVAL_TRUE'/>
<SEEALSO value='JS_NewContext'/>
</ENTRY>
<ENTRY id='JSVAL_ONE'>
<TYPE value='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>
<SEEALSO value='INT_TO_JSVAL'/>
<SEEALSO value='JSVAL_VOID'/>
<SEEALSO value='JSVAL_NULL'/>
<SEEALSO value='JSVAL_ZERO'/>
<SEEALSO value='JSVAL_FALSE'/>
<SEEALSO value='JSVAL_TRUE'/>
<SEEALSO value='JS_NewContext'/>
</ENTRY>
<ENTRY id='JSVAL_FALSE'>
<TYPE value='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>
<SEEALSO value='BOOLEAN_TO_JSVAL'/>
<SEEALSO value='JSVAL_VOID'/>
<SEEALSO value='JSVAL_NULL'/>
<SEEALSO value='JSVAL_ZERO'/>
<SEEALSO value='JSVAL_ONE'/>
<SEEALSO value='JSVAL_TRUE'/>
<SEEALSO value='JS_NewContext'/>
</ENTRY>
<ENTRY id='JSVAL_TRUE'>
<TYPE value='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>
<SEEALSO value='BOOLEAN_TO_JSVAL'/>
<SEEALSO value='JSVAL_VOID'/>
<SEEALSO value='JSVAL_NULL'/>
<SEEALSO value='JSVAL_ZERO'/>
<SEEALSO value='JSVAL_ONE'/>
<SEEALSO value='JSVAL_FALSE'/>
<SEEALSO value='JS_NewContext'/>
</ENTRY>
<ENTRY id='JSCLASS_HAS_PRIVATE'>
<TYPE value='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>
<SEEALSO value='JSClass'/>
</ENTRY>
<ENTRY id='JSCLASS_NEW_ENUMERATE'>
<TYPE value='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>
<SEEALSO value='JSCLASS_HAS_PRIVATE'/>
<SEEALSO value='JSCLASS_NEW_RESOLVE'/>
<SEEALSO value='JSClass'/>
<SEEALSO value='JSObjectOps'/>
</ENTRY>
<ENTRY id='JSCLASS_NEW_RESOLVE'>
<TYPE value='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>
<SEEALSO value='JSCLASS_HAS_PRIVATE'/>
<SEEALSO value='JSCLASS_NEW_ENUMERATE'/>
<SEEALSO value='JSClass'/>
<SEEALSO value='JSObjectOps'/>
</ENTRY>
<ENTRY id='JSPRINCIPALS_HOLD'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSPRINCIPALS_DROP'/>
<SEEALSO value='JSPrincipals'/>
<SEEALSO value='JS_Init'/>
<SEEALSO value='JS_NewContext'/>
</ENTRY>
<ENTRY id='JSPRINCIPALS_DROP'>
<TYPE value='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>
<EXAMPLE desc='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>
<SEEALSO value='JSPRINCIPALS_HOLD'/>
<SEEALSO value='JSPrincipals'/>
<SEEALSO value='JS_Init'/>
<SEEALSO value='JS_NewContext'/>
</ENTRY>
<ENTRY id='JS_NewRuntime'>
<TYPE value='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>
<SEEALSO value='JS_DestroyRuntime'/>
</ENTRY>
<ENTRY id='JS_DestroyRuntime'>
<TYPE value='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>
<SEEALSO value='JS_NewRuntime'/>
</ENTRY>
<ENTRY id='JSRESOLVE_QUALIFIED'>
<TYPE value='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>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<SEEALSO value='JSRESOLVE_ASSIGNING'/>
</ENTRY>
<ENTRY id='JSRESOLVE_ASSIGNING'>
<TYPE value='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>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<SEEALSO value='JSRESOLVE_QUALIFIED'/>
</ENTRY>
<ENTRY id='JSClass'>
<TYPE value='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];
};
<PARAM name='*name' type='char'>
Class name<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='addProperty' type='JSPropertyOp'>
Method for adding a property to the class.<BR/>
</PARAM>
<PARAM name='delProperty' type='JSPropertyOp'>
Method for deleting a property from the class.<BR/>
</PARAM>
<PARAM name='getProperty' type='JSPropertyOp'>
Method for getting a property value.<BR/>
</PARAM>
<PARAM name='setProperty' type='JSPropertyOp'>
Method for setting a property value.<BR/>
</PARAM>
<PARAM name='enumerate' type='JSEnumerateOp'>
Method for enumerating over class properties.<BR/>
</PARAM>
<PARAM name='resolve' type='JSResolveOp'>
Method for resolving property ambiguities.<BR/>
</PARAM>
<PARAM name='convert' type='JSConvertOp'>
Method for converting property values.<BR/>
</PARAM>
<PARAM name='finalize' type='JSFinalizeOp'>
Method for finalizing the class.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='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>
<PARAM name='call' type='JSNative'>
Pointer to the method for calling into the object that represents this class.<BR/>
</PARAM>
<PARAM name='construct' type='JSNative'>
Pointer to the constructor for the object that represents this <C>class</C><BR/>
</PARAM>
<PARAM name='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>
<PARAM name='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>
<PARAM name='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>
<SEEALSO value='JSCLASS_HAS_PRIVATE'/>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_EnumerateStub'/>
<SEEALSO value='JS_ResolveStub'/>
<SEEALSO value='JS_ConvertStub'/>
<SEEALSO value='JS_FinalizeStub'/>
<SEEALSO value='JS_InitClass'/>
<SEEALSO value='JS_GetClass'/>
<SEEALSO value='JS_InstanceOf'/>
<SEEALSO value='JSObjectOps'/>
</ENTRY>
<ENTRY id='JSObjectOps'>
<TYPE value='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];
};
<PARAM name='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/>
</PARAM>
<PARAM name='destroyObjectMap' type='JSObjectMapOp'>
Pointer to the function that destroys the object map when it is no longer needed. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='lookupProperty' type='JSLookupPropOp'>
Pointer to a custom property lookup method for the object. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='defineProperty' type='JSDefinePropOp'>
Pointer to a custom property creation method for the object. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='getProperty' type='JSPropertyIdOp'>
Pointer to a custom property value retrieval method for the object. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='setProperty' type='JSPropertyIdOp'>
Pointer to a custom property value assignment method for the object. This pointer cannnot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='getAttributes' type='JSAttributesOp'>
Pointer to a custom property attributes retrieval method for the object. This pointer cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='setAttributes' type='JSAttributesOp'>
Pointer to a custom property attributes assignment method for this object. This property cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='defaultValue' type='JSConvertOp'>
Pointer to a method for converting a property value. This pointer cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='enumerate' type='JSNewEnumerateOp'>
Pointer to a custom method for enumerating over class properties. This pointer cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='checkAccess' type='JSCheckAccessIdOp'>
Pointer to an optional custom access control method for a this object. This pointer cannot be <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='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>
<PARAM name='call' type='JSNative'>
Pointer to the method for calling into the object that represents this class.<BR/>
</PARAM>
<PARAM name='construct' type='JSNative'>
Pointer to the constructor for the object that represents this <C>class</C><BR/>
</PARAM>
<PARAM name='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>
<PARAM name='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>
<PARAM name='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>
<SEEALSO value='JSClass'/>
</ENTRY>
<ENTRY id='JSPropertySpec'>
<TYPE value='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;
};
<PARAM name='*name' type='const char'>
Name to assign to the property.<BR/>
</PARAM>
<PARAM name='tinyid' type='int8'>
Unique ID number for the property to aid in resolving <C>getProperty</C> and <C>setProperty</C> method calls.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='getter' type='JSPropertyOp'>
<C>getProperty</C> method for the property.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JSPROP_ENUMERATE'/>
<SEEALSO value='JSPROP_READONLY'/>
<SEEALSO value='JSPROP_PERMANENT'/>
<SEEALSO value='JSPROP_EXPORTED'/>
<SEEALSO value='JSPROP_INDEX'/>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_EnumerateStub'/>
<SEEALSO value='JS_ResolveStub'/>
<SEEALSO value='JS_ConvertStub'/>
<SEEALSO value='JS_FinalizeStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
</ENTRY>
<ENTRY id='JSFunctionSpec'>
<TYPE value='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;
};
<PARAM name='*name' type='const char'>
Name to assign to the function.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='nargs' type='uint8'>
Number of arguments to pass to this function.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='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>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_GetFunctionName'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JSConstDoubleSpec'>
<TYPE value='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];
};
<PARAM name='dval' type='jsdouble'>
Value for the double.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name to assign the double.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='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>
<SEEALSO value='JSVAL_IS_DOUBLE'/>
<SEEALSO value='JSVAL_TO_DOUBLE'/>
<SEEALSO value='DOUBLE_TO_JSVAL'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewDoubleValue'/>
<SEEALSO value='JS_DefineConstDoubles'/>
</ENTRY>
<ENTRY id='JSPrincipals'>
<TYPE value='Data Structure'/>
<SUMMARY>
Defines security information for an object or script.
</SUMMARY>
<SYNTAX>
typedef struct JSPrincipals {
char *codebase;
void *(*getPrincipalArray)(JSContext *cx,
struct JSPrincipals *);
JSBool (*globalPrivilegesEnabled)(JSContext *cx,
struct JSPrincipals *);
uintN refcount;
void (*destroy)(JSContext *cx, struct JSPrincipals *);
} JSPrincipals;
<PARAM name='*codebase' type='char'>
Pointer to the codebase for the principal.<BR/>
</PARAM>
<PARAM name='*getPrincipalArray' type='void'>
Pointer to the function that returns an array of principal definitions.<BR/>
</PARAM>
<PARAM name='*globalPrivilegesEnabled' type='JSBool'>
Flag indicating whether principals are enabled globally.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='*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/>
</DESCRIPTION>
<SEEALSO value='JSPRINCIPALS_HOLD'/>
<SEEALSO value='JSPRINCIPALS_DROP'/>
<SEEALSO value='JS_CompileScriptForPrincipals'/>
<SEEALSO value='JS_CompileUCScriptForPrincipals'/>
<SEEALSO value='JS_CompileFunctionForPrincipals'/>
<SEEALSO value='JS_CompileUCFunctionForPrincipals'/>
<SEEALSO value='JS_EvaluateScriptForPrincipals'/>
</ENTRY>
<ENTRY id='JSErrorReport'>
<TYPE value='Data Structure'/>
<SUMMARY>
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;
};
<PARAM name='*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>
<PARAM name='lineno' type='uintN'>
Line number in the source that caused the error.<BR/>
</PARAM>
<PARAM name='*linebuf' type='const char'>
Text of the line that caused the error, minus the trailing newline character.<BR/>
</PARAM>
<PARAM name='*tokenptr' type='const char'>
Pointer to the error token in <C>*linebuf</C>.<BR/>
</PARAM>
<PARAM name='*uclinebuf' type='const jschar'>
Unicode line buffer. This is the buffer that contains the original data.<BR/>
</PARAM>
<PARAM name='*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>
<SEEALSO value='JS_ReportError'/>
<SEEALSO value='JS_ReportOutOfMemory'/>
<SEEALSO value='JS_SetErrorReporter'/>
</ENTRY>
<ENTRY id='JSIdArray'>
<TYPE value='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>
<SEEALSO value='JSProperty'/>
</ENTRY>
<ENTRY id='JSProperty'>
<TYPE value='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>
<SEEALSO value='JSIdArray'/>
</ENTRY>
<ENTRY id='JS_GetNaNValue'>
<TYPE value='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>
<SEEALSO value='JS_GetNegativeInfinityValue'/>
<SEEALSO value='JS_GetPositiveInfinityValue'/>
<SEEALSO value='JS_GetEmptyStringValue'/>
</ENTRY>
<ENTRY id='JS_GetNegativeInfinityValue'>
<TYPE value='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>
<SEEALSO value='JS_GetNaNValue'/>
<SEEALSO value='JS_GetPositiveInfinityValue'/>
<SEEALSO value='JS_GetEmptyStringValue'/>
</ENTRY>
<ENTRY id='JS_GetPositiveInfinityValue'>
<TYPE value='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>
<SEEALSO value='JS_GetNaNValue'/>
<SEEALSO value='JS_GetNegativeInfinityValue'/>
<SEEALSO value='JS_GetEmptyStringValue'/>
</ENTRY>
<ENTRY id='JS_GetEmptyStringValue'>
<TYPE value='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>
<SEEALSO value='JS_GetNaNValue'/>
<SEEALSO value='JS_GetNegativeInfinityValue'/>
<SEEALSO value='JS_GetPositiveInfinityValue'/>
</ENTRY>
<ENTRY id='JS_ConvertArguments'>
<TYPE value='Function'/>
<SUMMARY>
Converts a series of JS values, passed in an argument array, to their corresponding JS types.
</SUMMARY>
<SYNTAX>
JSBool JS_ConvertArguments(JSContext *cx, uintN argc,
jsval *argv, const char *format, ...);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='argc' type='uintN'>
The number of arguments to convert.<BR/>
</PARAM>
<PARAM name='argv' type='jsval *'>
Pointer to the vector of arguments to convert.<BR/>
</PARAM>
<PARAM name='format' type='char *'>
Character array containing the recognized format to which to convert<BR/>
</PARAM>
<PARAM name='...' 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[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Character
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Corresponding JS type to which to convert the value
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>b</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSBool</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>c</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>uint16 (16-bit, unsigned integer)</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>i</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>int32 (32-bit, ECMA-compliant signed integer)</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>u</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>uint32 (32-bit, ECMA-compliant, unsigned integer)</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>j</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>int32 (32-bit, signed integer)</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>d</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>jsdouble</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
I</TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>jsdouble (converted to an integer value)</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
s</TD><TD VALIGN='baseline' ALIGN='left'><P>
JSString (treated as an array of characters)</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
S</TD><TD VALIGN='baseline' ALIGN='left'><P>
JSString</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
o</TD><TD VALIGN='baseline' ALIGN='left'><P>
JSObject</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
f</TD><TD VALIGN='baseline' ALIGN='left'><P>
JSFunction</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
*</TD><TD VALIGN='baseline' ALIGN='left'><P>
None. If an asterisk (*) is present in <CODE>format</CODE>, it tells the conversion routine to skip converting the current argument.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
/</TD><TD VALIGN='baseline' ALIGN='left'><P>
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>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToECMAInt32'/>
<SEEALSO value='JS_ValueToECMAUint32'/>
<SEEALSO value='JS_ValueToUint16'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_ValueToId'/>
</ENTRY>
<ENTRY id='JS_ConvertValue'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to a value of a specific JS type.
</SUMMARY>
<SYNTAX>
JSBool JS_ConvertValue(JSContext *cx, jsval v, JSType type,
jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='v' type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='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>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_TypeOfValue'/>
<SEEALSO value='JS_GetTypeName'/>
</ENTRY>
<ENTRY id='JS_ValueToObject'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to a JS object.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToObject(JSContext *cx, jsval v,
JSObject **objp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='v' type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAM name='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
the <C>JS_AddRoot</C> function.
<P/>
</NOTE>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_TypeOfValue'/>
<SEEALSO value='JS_GetTypeName'/>
<SEEALSO value='JS_AddRoot'/>
</ENTRY>
<ENTRY id='JS_ValueToFunction'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to a JS function.
</SUMMARY>
<SYNTAX>
JSFunction * JS_ValueToFunction(JSContext *cx, jsval v);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_TypeOfValue'/>
<SEEALSO value='JS_GetTypeName'/>
</ENTRY>
<ENTRY id='JS_ValueToString'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to a JS string.
</SUMMARY>
<SYNTAX>
JSString * JS_ValueToString(JSContext *cx, jsval v);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_TypeOfValue'/>
<SEEALSO value='JS_GetTypeName'/>
<SEEALSO value='JS_AddRoot'/>
</ENTRY>
<ENTRY id='JS_ValueToNumber'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to a JS double.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToNumber(JSContext *cx, jsval v,
jsdouble *dp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='v' type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_TypeOfValue'/>
<SEEALSO value='JS_GetTypeName'/>
<SEEALSO value='JS_AddRoot'/>
</ENTRY>
<ENTRY id='JS_ValueToInt32'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to a JS 32-bit integer.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToInt32(JSContext *cx, jsval v, int32 *ip);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='v' type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAM name='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 32-bit integer (-2147483648 to 2147483647). If <C>v</C> is NaN, or a double and out of the 32-bit range, <C>JS_ValueToInt32</C> reports an error and conversion fails. A double is 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>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_TypeOfValue'/>
<SEEALSO value='JS_GetTypeName'/>
<SEEALSO value='JS_AddRoot'/>
</ENTRY>
<ENTRY id='JS_ValueToECMAInt32'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to an ECMA-compliant 32-bit integer.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToECMAInt32(JSContext *cx, jsval v, int32 *ip);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='v' type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToECMAUint32'/>
<SEEALSO value='JS_ValueToUint16'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_ValueToId'/>
</ENTRY>
<ENTRY id='JS_ValueToECMAUint32'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to an ECMA-compliant, unisgned 32-bit integer.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToECMAUint32(JSContext *cx, jsval v, uint32 *ip);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='v' type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToECMAInt32'/>
<SEEALSO value='JS_ValueToUint16'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_ValueToId'/>
</ENTRY>
<ENTRY id='JS_ValueToUint16'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to an unsigned, 16-bit integer.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToUint16(JSContext *cx, jsval v, uint16 *ip);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='v' type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToECMAInt32'/>
<SEEALSO value='JS_ValueToECMAUint32'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_ValueToId'/>
</ENTRY>
<ENTRY id='JS_ValueToBoolean'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to a JS Boolean.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToBoolean(JSContext *cx, jsval v,
JSBool *bp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='v' type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_TypeOfValue'/>
<SEEALSO value='JS_GetTypeName'/>
</ENTRY>
<ENTRY id='JS_ValueToId'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS value to a JS ID.
</SUMMARY>
<SYNTAX>
JSBool JS_ValueToId(JSContext *cx, jsval v, jsid *idp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='v' type='jsval'>
The JS value to convert.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ConvertArguments'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_TypeOfValue'/>
<SEEALSO value='JS_GetTypeName'/>
<SEEALSO value='JS_IdToValue'/>
</ENTRY>
<ENTRY id='JS_IdToValue'>
<TYPE value='Function'/>
<SUMMARY>
Converts a JS ID to a JS value.
</SUMMARY>
<SYNTAX>
JSBool JS_IdToValue(JSContext *cx, jsval v,
JSBool *bp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='id' type='jsid'>
The JS ID to convert.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToId'/>
<SEEALSO value='JS_TypeOfValue'/>
<SEEALSO value='JS_GetTypeName'/>
</ENTRY>
<ENTRY id='JS_TypeOfValue'>
<TYPE value='Function'/>
<SUMMARY>
Determines the JS data type of a JS value.
</SUMMARY>
<SYNTAX>
JSType JS_TypeOfValue(JSContext *cx, jsval v);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_GetTypeName'/>
</ENTRY>
<ENTRY id='JS_GetTypeName'>
<TYPE value='Macro'/>
<SUMMARY>
Function. Returns a pointer to the string literal description of a specified JS data type.
</SUMMARY>
<SYNTAX>
const char * JS_GetTypeName(JSContext *cx, JSType type);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Type
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Literal
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSTYPE_VOID</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>"undefined"</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSTYPE_OBJECT</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>"object"</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSTYPE_FUNCTION</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>"function"</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSTYPE_STRING</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>"string"</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSTYPE_NUMBER</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>"number"</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSTYPE_BOOLEAN</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>"boolean"</CODE></P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
Any other value</TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>NULL</CODE></P>
</TD></TR></TABLE >
]]>
<P/>
</DESCRIPTION>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ValueToNumber'/>
<SEEALSO value='JS_ValueToInt32'/>
<SEEALSO value='JS_ValueToBoolean'/>
<SEEALSO value='JS_TypeOfValue'/>
</ENTRY>
<ENTRY id='JS_Init'>
<TYPE value='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>
<SEEALSO value='JS_NewRuntime'/>
<SEEALSO value='JS_DestroyRuntime'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JS_Finish'>
<TYPE value='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>
<SEEALSO value='JS_DestroyRuntime'/>
<SEEALSO value='JS_NewRuntime'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JS_Lock'>
<TYPE value='Function'/>
<SUMMARY>
Locks the JS run-time environment.
</SUMMARY>
<SYNTAX>
void JS_Lock(JSRuntime *rt);
</SYNTAX>
<DESCRIPTION>
<C>JS_Lock</C> is a deprecated API; don't use it.<P/>
</DESCRIPTION>
<SEEALSO value='JS_Unlock'/>
<SEEALSO value='JS_GetRuntime'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JS_Unlock'>
<TYPE value='Function'/>
<SUMMARY>
Unlocks a previously locked JS run-time environment.
</SUMMARY>
<SYNTAX>
void JS_Unlock(JSRuntime *rt);
<PARAM name='*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 a deprecated API; don't use it.<P/>
</DESCRIPTION>
<SEEALSO value='JS_Lock'/>
<SEEALSO value='JS_GetRuntime'/>
<DEPRECATED/>
</ENTRY>
<!-- XXXXXXXXXXXXXXXXXXX -->
<ENTRY id='JS_SetContextThread'>
<TYPE value='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);
<PARAM name='*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>
<SEEALSO value='JS_GetContextThread'/>
</ENTRY>
<!-- XXXXXXXXXXXXXXXXXXX -->
<ENTRY id='JS_ClearContextThread'>
<TYPE value='Function'/>
<SUMMARY>
Removes the association between a context and the current thread.
</SUMMARY>
<SYNTAX>
intN JS_ClearContextThread(JSContext *cx);
<PARAM name='*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>
<SEEALSO value='JS_GetContextThread'/>
</ENTRY>
<!-- XXXXXXXXXXXXXXXXXXX -->
<ENTRY id='JS_GetContextThread'>
<TYPE value='Function'/>
<SUMMARY>
Returns the ID of the associated thread for a context.
</SUMMARY>
<SYNTAX>
intN JS_GetContextThread(JSContext *cx);
<PARAM name='*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
with <C>JS_THREADSAFE</C>.
</NOTE>
<SEEALSO value='JS_SetContextThread'/>
<SEEALSO value='JS_ClearContextThread'/>
</ENTRY>
<!-- XXXXXXXXXXXXXXXXXXX -->
<ENTRY id='JS_NewContext'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new JavaScript context.
</SUMMARY>
<SYNTAX>
JSContext * JS_NewContext(JSRuntime *rt, size_t stacksize);
<PARAM name='*rt' type='JSRuntime'>
Pointer to a previously established JS run-time environment with which to associate this context.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_DestroyContext'/>
<SEEALSO value='JS_ContextIterator'/>
</ENTRY>
<ENTRY id='JS_DestroyContext'>
<TYPE value='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>
<SEEALSO value='JS_NewContext'/>
<SEEALSO value='JS_ContextIterator'/>
</ENTRY>
<ENTRY id='JS_GetRuntime'>
<TYPE value='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>
<SEEALSO value='JS_Init'/>
<SEEALSO value='JS_Lock'/>
<SEEALSO value='JS_Unlock'/>
<SEEALSO value='JS_NewContext'/>
<SEEALSO value='JS_Finish'/>
</ENTRY>
<ENTRY id='JS_ContextIterator'>
<TYPE value='Function'/>
<SUMMARY>
Cycles through the JS contexts associated with a particular <C>JSRuntime</C>.
</SUMMARY>
<SYNTAX>
JSContext * JS_ContextIterator(JSRuntime *rt,
JSContext **iterp);
<PARAM name='rt' type='JSRuntime *'>
Pointer to a previously established JS run-time environment with which script contexts to iterate through are associated.<BR/>
</PARAM>
<PARAM name='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>
<EXAMPLE desc='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, &amp;iterp)) != NULL)
{
printf("%d ". ++1);
}
</EXAMPLE>
<SEEALSO value='JS_NewContext'/>
<SEEALSO value='JS_DestroyContext'/>
</ENTRY>
<ENTRY id='JS_GetVersion'>
<TYPE value='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:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Value
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Enumeration
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Meaning
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>100</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_1_0</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
JavaScript 1.0</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>110</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_1_1</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
JavaScript 1.1</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>120</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_1_2</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
JavaScript 1.2</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>130</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_1_3</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
JavaScript 1.3</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>0</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_DEFAULT</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Default JavaScript version</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>-1</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_UNKNOWN</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Unknown JavaScript version</P>
</TD></TR></TABLE >
]]>
<P/>
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>
<SEEALSO value='JS_SetVersion'/>
</ENTRY>
<ENTRY id='JS_SetVersion'>
<TYPE value='Function'/>
<SUMMARY>
Specifies the version of JavaScript used by a specified executable script context.
</SUMMARY>
<SYNTAX>
JSVersion JS_SetVersion(JSContext *cx, JSVersion version);
</SYNTAX>
<DESCRIPTION>
<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:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Enumeration
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Meaning
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_1_0</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
JavaScript 1.0</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_1_1</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
JavaScript 1.1</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_1_2</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
JavaScript 1.2</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSVERSION_1_3</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
JavaScript 1.3</P>
</TD></TR></TABLE >
]]>
<P/>
<C>JS_SetVersion</C> returns the JS version in effect for the context before you changed it.<P/>
</DESCRIPTION>
<SEEALSO value='JS_GetVersion'/>
</ENTRY>
<ENTRY id='JS_GetImplementationVersion'>
<TYPE value='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>
<SEEALSO value='JS_GetVersion'/>
<SEEALSO value='JS_SetVersion'/>
</ENTRY>
<ENTRY id='JS_GetGlobalObject'>
<TYPE value='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>
<SEEALSO value='JS_SetGlobalObject'/>
<SEEALSO value='OBJECT_TO_JSVAL'/>
<SEEALSO value='JSVAL_TO_OBJECT'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_GetFunctionObject'/>
</ENTRY>
<ENTRY id='JS_SetGlobalObject'>
<TYPE value='Function'/>
<SUMMARY>
Specifies the global object for an executable script context.
</SUMMARY>
<SYNTAX>
void JS_SetGlobalObject(JSContext *cx, JSObject *obj);
<PARAM name='cx' type='JSContext *'>
Pointer to the executable script context for which to set the global object.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_InitStandardClasses'/>
<SEEALSO value='JS_GetGlobalObject'/>
<SEEALSO value='OBJECT_TO_JSVAL'/>
<SEEALSO value='JSVAL_TO_OBJECT'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_GetFunctionObject'/>
</ENTRY>
<ENTRY id='JS_InitStandardClasses'>
<TYPE value='Function'/>
<SUMMARY>
Initializes general JS function and object classes, and the built-in object classes used in most scripts.
</SUMMARY>
<SYNTAX>
JSBool JS_InitStandardClasses(JSContext *cx, JSObject *obj);
<PARAM name='cx' type='JSContext *'>
Pointer to the executable script context for which to initialize JS function and object classes.<BR/>
</PARAM>
<PARAM name='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>&lt;object&gt;.&lt;prototype&gt;</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>
<SEEALSO value='JS_InitClass'/>
<SEEALSO value='JS_GetClass'/>
</ENTRY>
<ENTRY id='JS_GetScopeChain'>
<TYPE value='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>
<SEEALSO value='JS_InitStandardClasses'/>
</ENTRY>
<ENTRY id='JS_malloc'>
<TYPE value='Function'/>
<SUMMARY>
Allocates a region of memory for use.
</SUMMARY>
<SYNTAX>
void * JS_malloc(JSContext *cx, size_t nbytes);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
</NOTE>
<SEEALSO value='JS_realloc'/>
<SEEALSO value='JS_free'/>
<SEEALSO value='JS_ReportOutOfMemory'/>
</ENTRY>
<ENTRY id='JS_realloc'>
<TYPE value='Function'/>
<SUMMARY>
Reallocates a region of memory.
</SUMMARY>
<SYNTAX>
void * JS_realloc(JSContext *cx, void *p, size_t nbytes);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='p' type='void *'>
Pointer to the previously allocated memory<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_malloc'/>
<SEEALSO value='JS_free'/>
<SEEALSO value='JS_ReportOutOfMemory'/>
</ENTRY>
<ENTRY id='JS_free'>
<TYPE value='Function'/>
<SUMMARY>
Deallocates a region of memory.
</SUMMARY>
<SYNTAX>
void JS_free(JSContext *cx, void *p);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_malloc'/>
<SEEALSO value='JS_realloc'/>
</ENTRY>
<ENTRY id='JS_strdup'>
<TYPE value='Function'/>
<SUMMARY>
Duplicates a specified string within a specific JS executable script context.
</SUMMARY>
<SYNTAX>
char * JS_strdup(JSContext *cx, const char *s);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_NewDouble'/>
</ENTRY>
<ENTRY id='JS_NewDouble'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new double value.
</SUMMARY>
<SYNTAX>
jsdouble * JS_NewDouble(JSContext *cx, jsdouble d);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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.
<P/>
</NOTE>
<SEEALSO value='JS_strdup'/>
<SEEALSO value='JS_NewDoubleValue'/>
<SEEALSO value='JS_NewNumberValue'/>
<SEEALSO value='JS_AddRoot'/>
</ENTRY>
<ENTRY id='JS_NewDoubleValue'>
<TYPE value='Function'/>
<SUMMARY>
Creates a JS value based on a JS double.
</SUMMARY>
<SYNTAX>
JSBool JS_NewDoubleValue(JSContext *cx, jsdouble d,
jsval *rval);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='d' type='jsdouble'>
An existing double to assign as a value to the <C>jsval</C>.<BR/>
</PARAM>
<PARAM name='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.
<P/>
</NOTE>
<SEEALSO value='JS_NewNumberValue'/>
<SEEALSO value='JS_AddRoot'/>
</ENTRY>
<ENTRY id='JS_NewNumberValue'>
<TYPE value='Function'/>
<SUMMARY>
Internal use only. Summary fragment.
</SUMMARY>
<SYNTAX>
JSBool JS_NewNumberValue(JSContext *cx, jsdouble d,
jsval *rval);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='d' type='jsdouble'>
An existing double to assign as a value to the <C>jsval</C>.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewDoubleValue'/>
<SEEALSO value='JS_AddRoot'/>
</ENTRY>
<ENTRY id='JS_AddRoot'>
<TYPE value='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);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_AddNamedRoot'/>
<SEEALSO value='JS_DumpNamedRoots'/>
<SEEALSO value='JS_RemoveRoot'/>
</ENTRY>
<ENTRY id='JS_AddNamedRoot'>
<TYPE value='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);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='rp' type='void *'>
Pointer to the item to protect.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_AddRoot'/>
<SEEALSO value='JS_DumpNamedRoots'/>
<SEEALSO value='JS_RemoveRoot'/>
</ENTRY>
<ENTRY id='JS_DumpNamedRoots'>
<TYPE value='Function'/>
<SUMMARY>
Enumerates the named roots in the garbage collection hash table.
</SUMMARY>
<SYNTAX>
void JS_DumpNamedRoots(JSRuntime *rt,
void (*dump)(const char *name, void *rp, void *data),
void *data);
<PARAM name='rt' type='JSRuntime *'>
Pointer to a <C>JSRuntime</C> from which to dump named roots<BR/>
</PARAM>
<PARAM name='dump' type='void *'>
Pointer to function that actually dumps the named roots<BR/>
</PARAM>
<PARAM name='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:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Argument
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Type
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Description
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>name</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>const char *</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Name of the current hash entry.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>rp</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
<CODE>void *</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Pointer to the named roots</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
data</TD><TD VALIGN='baseline' ALIGN='left'><P>
void *</TD><TD VALIGN='baseline' ALIGN='left'><P>
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>
<SEEALSO value='JS_AddRoot'/>
<SEEALSO value='JS_AddNamedRoot'/>
<SEEALSO value='JS_RemoveRoot'/>
</ENTRY>
<ENTRY id='JS_RemoveRoot'>
<TYPE value='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);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
<C>JS_RemoveRoot</C> always returns <C>JS_TRUE</C>. <P/>
</DESCRIPTION>
<SEEALSO value='JS_AddRoot'/>
<SEEALSO value='JS_AddNamedRoot'/>
<SEEALSO value='JS_DumpNamedRoots'/>
</ENTRY>
<ENTRY id='JS_BeginRequest'>
<TYPE value='Function'/>
<SUMMARY>
Indicates to the JS engine that an application thread is entering a critical section that calls the JS API freely but does not block.
</SUMMARY>
<SYNTAX>
void JS_BeginRequest(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
When your multi-threaded application wants to execute JS API calls on a thread, it should use <C>JS_BeginRequest</C> and <C>JS_EndRequest</C> to bracket maximal non-blocking hunks of native code that call the JS API. This "request model" serves two purposes: to interlock with the global mark/sweep garbage collector, and to optimize object locking to be lock-free in most cases. In order to achieve these purposes, <C>JS_BeginRequest</C> 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 its request counter. After incrementing the counter, <C>JS_BeginRequest</C> unlocks the runtime if it previously locked it.<P/>
It is therefore imperative that native code executing within an active request on <C>cx</C> not block, or simply take too long. Any blocking native call, or lengthy computation that can race safely with the garbage collector, must be bracketed within the native method or function with <C>JS_SuspendRequest</C> and <C>JS_ResumeRequest</C>.<P/>
It is safe to nest calls to <C>JS_BeginRequest</C> so long as each call is balanced by a matching <C>JS_EndRequest</C>.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_BeginRequest</C> is available only 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>
<SEEALSO value='JS_EndRequest'/>
<SEEALSO value='JS_SuspendRequest'/>
<SEEALSO value='JS_ResumeRequest'/>
</ENTRY>
<ENTRY id='JS_EndRequest'>
<TYPE value='Function'/>
<SUMMARY>
Indicates to the JS engine that an application thread is leaving a critical section that calls the JS API freely but does not block.
</SUMMARY>
<SYNTAX>
void JS_EndRequest(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
When your multi-threaded application has called <C>JS_BeginRequest</C> and no longer needs to call the JS API in a non-blocking burst of activity, <C>JS_EndRequest</C> safely decrements the request 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.<P/>
The application may nest calls to <C>JS_BeginRequest</C> provided it balances each such call with a matching <C>JS_EndRequest</C>.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_EndRequest</C> is available only 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>
<SEEALSO value='JS_BeginRequest'/>
<SEEALSO value='JS_SuspendRequest'/>
<SEEALSO value='JS_ResumeRequest'/>
</ENTRY>
<ENTRY id='JS_SuspendRequest'>
<TYPE value='Function'/>
<SUMMARY>
Indicates to the JS engine that an application thread executing JS API calls in a request can suspend its API-calling critical section and block.
</SUMMARY>
<SYNTAX>
jsrefcount JS_SuspendRequest(JSContext *cx);
</SYNTAX>
<DESCRIPTION>
When your multi-threaded application is in a request but needs to block or perform lengthy computation that can race safely with the garbage collector, it should call <C>JS_SuspendRequest</C> before the blocking or lengthy call, and <C>JS_ResumeRequest</C> after. <C>JS_SuspendRequest</C> safely decrements the request counter for the JS engine runtime associated with a given context, <C>cx</C>. <C>JS_SuspendRequest</C> returns the saved value of the request-depth counter stored in <C>cx</C>, which must be passed to the matching <C>JS_SuspendRequest</C> after the blocking or lengthy code completes.<P/>
</DESCRIPTION>
<NOTE>
<C>JS_SuspendRequest</C> is available only 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>
<SEEALSO value='JS_BeginRequest'/>
<SEEALSO value='JS_EndRequest'/>
<SEEALSO value='JS_ResumeRequest'/>
</ENTRY>
<ENTRY id='JS_ResumeRequest'>
<TYPE value='Function'/>
<SUMMARY>
Indicates to the JS engine that an application thread in a suspended request wants to resume executing JS API calls from non-blocking code.
Restarts a previously suspended thread.
</SUMMARY>
<SYNTAX>
void JS_ResumeRequest(JSContext *cx, jsrefcount saveDepth);
</SYNTAX>
<DESCRIPTION>
When your multi-threaded application restarts a previously suspended request, <C>JS_ResumeRequest</C> safely restores the request depth counter from <C>saveDepth</C> for the given context, <C>cx</C>. It does this by calling <C>JS_BeginRequest</C> exactly <C>saveDepth</C> times, so <C>saveDepth</C> must come from the return value of a prior <C>JS_SuspendRequest</C> call.
<P/>
</DESCRIPTION>
<NOTE>
<C>JS_ResumeRequest</C> is available only 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>
<SEEALSO value='JS_BeginRequest'/>
<SEEALSO value='JS_EndRequest'/>
<SEEALSO value='JS_SuspendRequest'/>
</ENTRY>
<ENTRY id='JS_LockGCThing'>
<TYPE value='Function'/>
<SUMMARY>
Protects a specified JS item from garbage collection.
</SUMMARY>
<SYNTAX>
JSBool JS_LockGCThing(JSContext *cx, void *thing);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_UnlockGCThing'/>
<SEEALSO value='JS_AddRoot'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JS_UnlockGCThing'>
<TYPE value='Function'/>
<SUMMARY>
Reenables garbage collection of a specified JS item.
</SUMMARY>
<SYNTAX>
JSBool JS_UnockGCThing(JSContext *cx, void *thing);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_LockGCThing'/>
<SEEALSO value='JS_RemoveRoot'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JS_GC'>
<TYPE value='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>
<SEEALSO value='JS_malloc'/>
<SEEALSO value='JS_realloc'/>
<SEEALSO value='JS_MaybeGC'/>
</ENTRY>
<ENTRY id='JS_MaybeGC'>
<TYPE value='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>
<SEEALSO value='JS_malloc'/>
<SEEALSO value='JS_realloc'/>
<SEEALSO value='JS_GC'/>
</ENTRY>
<ENTRY id='JS_SetGCCallback'>
<TYPE value='Function'/>
<SUMMARY>
Specifies a new callback function for the garbage collector.
</SUMMARY>
<SYNTAX>
JSGCCallback JS_SetGCCallback(JSContext *cx, JSGCCallback cb);
</SYNTAX>
<DESCRIPTION>
<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/>
</DESCRIPTION>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_DestroyIdArray'>
<TYPE value='Function'/>
<SUMMARY>
Frees a JS ID array structure.
</SUMMARY>
<SYNTAX>
void JS_DestroyIdArray(JSContext *cx, JSIdArray *ida);
</SYNTAX>
<DESCRIPTION>
<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>
<SEEALSO value='JS_NewIdArray'/>
<SEEALSO value='JSIdArray'/>
</ENTRY>
<ENTRY id='JS_NewIdArray'>
<TYPE value='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>
<SEEALSO value='JS_DestroyIdArray'/>
<SEEALSO value='JSIdArray'/>
</ENTRY>
<ENTRY id='JS_PropertyStub'>
<TYPE value='Function'/>
<SUMMARY>
Provides a dummy property argument for API routines that requires property information.
</SUMMARY>
<SYNTAX>
JSBool JS_PropertyStub(JSContext *cx, JSObject *obj, jsval id,
jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Pointer to the object for this stub.<BR/>
</PARAM>
<PARAM name='id' type='jsval'>
The ID for the stub.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_EnumerateStub'/>
<SEEALSO value='JS_ResolveStub'/>
<SEEALSO value='JS_ConvertStub'/>
<SEEALSO value='JS_FinalizeStub'/>
</ENTRY>
<ENTRY id='JS_EnumerateStub'>
<TYPE value='Function'/>
<SUMMARY>
Provides a dummy enumeration object for API routines that requires it.
</SUMMARY>
<SYNTAX>
JSBool JS_EnumerateStub(JSContext *cx, JSObject *obj);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_ResolveStub'/>
<SEEALSO value='JS_ConvertStub'/>
<SEEALSO value='JS_FinalizeStub'/>
</ENTRY>
<ENTRY id='JS_ResolveStub'>
<TYPE value='Function'/>
<SUMMARY>
Provides a dummy resolution object for API routines that requires it.
</SUMMARY>
<SYNTAX>
JSBool JS_ResolveStub(JSContext *cx, JSObject *obj, jsval id);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Pointer to the object for this stub.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_EnumerateStub'/>
<SEEALSO value='JS_ConvertStub'/>
<SEEALSO value='JS_FinalizeStub'/>
</ENTRY>
<ENTRY id='JS_ConvertStub'>
<TYPE value='Function'/>
<SUMMARY>
Provides a dummy conversion object for API routines that requires it.
</SUMMARY>
<SYNTAX>
JSBool JS_ConvertStub(JSContext *cx, JSObject *obj, JSType type,
jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Pointer to the object for this stub.<BR/>
</PARAM>
<PARAM name='type' type='JSType'>
The type to which to convert this object.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_EnumerateStub'/>
<SEEALSO value='JS_ResolveStub'/>
<SEEALSO value='JS_FinalizeStub'/>
</ENTRY>
<ENTRY id='JS_FinalizeStub'>
<TYPE value='Function'/>
<SUMMARY>
Provides a dummy finalization object for API routines that requires it.
</SUMMARY>
<SYNTAX>
void JS_FinalizeStub(JSContext *cx, JSObject *obj);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_EnumerateStub'/>
<SEEALSO value='JS_ResolveStub'/>
<SEEALSO value='JS_ConvertStub'/>
</ENTRY>
<ENTRY id='JS_InitClass'>
<TYPE value='Function'/>
<SUMMARY>
Initializes a class structure, its prototype, properties, and functions.
</SUMMARY>
<SYNTAX>
JSObject * JS_InitClass(JSContext *cx, JSObject *obj,
JSObject *parent_proto, JSClass *clasp,
JSNative constructor, uintN nargs, JSPropertySpec *ps,
JSFunctionSpec *fs, JSPropertySpec *static_ps,
JSFunctionSpec *static_fs);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Pointer to the object to use for initializing the class.<BR/>
</PARAM>
<PARAM name='parent_proto' type='JSObject *'>
Pointer to a prototype object for the class.<BR/>
</PARAM>
<PARAM name='clasp' type='JSClass *'>
Pointer to the class structure to initialize. This structure defines the class for use by other API functions.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='nargs' type='uintN'>
Number of arguments for the constructor.<BR/>
</PARAM>
<PARAM name='ps' type='JSPropertySpec *'>
Pointer to the properties structure for the prototype object, <C>parent_proto</C>.<BR/>
</PARAM>
<PARAM name='fs' type='JSFunctionSpec *'>
Pointer to the functions structure for the prototype object, <C>parent_proto</C>.<BR/>
</PARAM>
<PARAM name='static_ps' type='JSPropertySpec *'>
Pointer to the properties structure for the constructor object, if it is not <C>NULL</C>.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_GetClass'/>
<SEEALSO value='JS_InstanceOf'/>
<SEEALSO value='JSClass'/>
<SEEALSO value='JSPropertySpec'/>
<SEEALSO value='JSFunctionSpec'/>
</ENTRY>
<ENTRY id='JS_GetClass'>
<TYPE value='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:
JSClass * JS_GetClass(JSContext *cx, JSObject *obj)
</SYNTAX>
<DESCRIPTION>
<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>
<SEEALSO value='JS_InitClass'/>
<SEEALSO value='JS_InstanceOf'/>
<SEEALSO value='JSClass'/>
</ENTRY>
<ENTRY id='JS_InstanceOf'>
<TYPE value='Function'/>
<SUMMARY>
Determines if an object is an instance of a specified JS class.
</SUMMARY>
<SYNTAX>
JSBool JS_InstanceOf(JSContext *cx, JSObject *obj,
JSClass *clasp, jsval *argv);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object to test.<BR/>
</PARAM>
<PARAM name='clasp' type='JSClass *'>
Class against which to test the object.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_InitClass'/>
<SEEALSO value='JS_GetClass'/>
<SEEALSO value='JSClass'/>
</ENTRY>
<ENTRY id='JS_GetPrivate'>
<TYPE value='Function'/>
<SUMMARY>
Retrieves the private data associated with an object.
</SUMMARY>
<SYNTAX>
void * JS_GetPrivate(JSContext *cx, JSObject *obj);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JSVAL_TO_PRIVATE'/>
<SEEALSO value='JSCLASS_HAS_PRIVATE'/>
<SEEALSO value='JS_InitClass'/>
<SEEALSO value='JS_SetPrivate'/>
<SEEALSO value='JS_GetInstancePrivate'/>
<SEEALSO value='JSClass'/>
</ENTRY>
<ENTRY id='JS_SetPrivate'>
<TYPE value='Function'/>
<SUMMARY>
Sets the private data for a JS object.
</SUMMARY>
<SYNTAX>
JSBool JS_SetPrivate(JSContext *cx, JSObject *obj, void *data);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to set private data.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='PRIVATE_TO_JSVAL'/>
<SEEALSO value='JSCLASS_HAS_PRIVATE'/>
<SEEALSO value='JS_InitClass'/>
<SEEALSO value='JS_GetPrivate'/>
<SEEALSO value='JS_GetInstancePrivate'/>
<SEEALSO value='JSClass'/>
</ENTRY>
<ENTRY id='JS_GetContextPrivate'>
<TYPE value='Function'/>
<SUMMARY>
Retrieves the private data associated with a context.
</SUMMARY>
<SYNTAX>
void * JS_GetContextPrivate(JSContext *cx);
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_SetContextPrivate'/>
</ENTRY>
<ENTRY id='JS_SetContextPrivate'>
<TYPE value='Function'/>
<SUMMARY>
Sets the private data for a context.
</SUMMARY>
<SYNTAX>
void JS_SetContextPrivate(JSContext *cx, void *data);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context for which to set private data.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_GetContextPrivate'/>
</ENTRY>
<ENTRY id='JS_GetInstancePrivate'>
<TYPE value='Function'/>
<SUMMARY>
Retrieves the private data associated with an object if that object is an instance of a class.
</SUMMARY>
<SYNTAX>
void * JS_GetInstancePrivate(JSContext *cx, JSObject *obj,
JSClass *clasp, jsval *argv);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to retrieve private data.<BR/>
</PARAM>
<PARAM name='clasp' type='JSClass *'>
Class against which to test the object.<BR/>
</PARAM>
<PARAM name='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>.
<P/>
</NOTE>
<SEEALSO value='JSVAL_TO_PRIVATE'/>
<SEEALSO value='JSCLASS_HAS_PRIVATE'/>
<SEEALSO value='JS_InitClass'/>
<SEEALSO value='JS_InstanceOf'/>
<SEEALSO value='JS_GetPrivate'/>
<SEEALSO value='JS_SetPrivate'/>
<SEEALSO value='JSClass'/>
</ENTRY>
<ENTRY id='JS_GetPrototype'>
<TYPE value='Function'/>
<SUMMARY>
Retrieves an object's prototype.
</SUMMARY>
<SYNTAX>
JSObject * JS_GetPrototype(JSContext *cx, JSObject *obj);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_SetPrototype'/>
</ENTRY>
<ENTRY id='JS_SetPrototype'>
<TYPE value='Function'/>
<SUMMARY>
Sets the prototype for an object.
</SUMMARY>
<SYNTAX>
JSBool JS_SetPrototype(JSContext *cx, JSObject *obj,
JSObject *proto);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Pointer to the object for which to set the prototype.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_GetPrototype'/>
<SEEALSO value='JS_NewObject'/>
</ENTRY>
<ENTRY id='JS_GetParent'>
<TYPE value='Function'/>
<SUMMARY>
Retrieves the parent object for a specified object.
</SUMMARY>
<SYNTAX>
JSObject * JS_GetParent(JSContext *cx, JSObject *obj);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_SetParent'/>
<SEEALSO value='JS_GetConstructor'/>
</ENTRY>
<ENTRY id='JS_SetParent'>
<TYPE value='Function'/>
<SUMMARY>
Sets the parent for an object.
</SUMMARY>
<SYNTAX>
JSBool JS_SetParent(JSContext *cx, JSObject *obj,
JSObject *parent);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Pointer to the object for which to set the parent.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_GetParent'/>
<SEEALSO value='JS_GetConstructor'/>
<SEEALSO value='JS_NewObject'/>
</ENTRY>
<ENTRY id='JS_GetConstructor'>
<TYPE value='Function'/>
<SUMMARY>
Retrieves the constructor for an object.
</SUMMARY>
<SYNTAX>
JSObject * JS_GetConstructor(JSContext *cx, JSObject *proto);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_GetParent'/>
<SEEALSO value='JS_GetPrototype'/>
</ENTRY>
<ENTRY id='JS_NewObject'>
<TYPE value='Function'/>
<SUMMARY>
Instantiates a new object.
</SUMMARY>
<SYNTAX>
JSObject * JS_NewObject(JSContext *cx, JSClass *clasp,
JSObject *proto, JSObject *parent);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='clasp' type='JSClass *'>
Pointer to the class to use for the new object.<BR/>
</PARAM>
<PARAM name='proto' type='JSObject *'>
Pointer to the prototype object to use for the new class.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ConstructObject'/>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_GetFunctionObject'/>
</ENTRY>
<ENTRY id='JS_ConstructObject'>
<TYPE value='Function'/>
<SUMMARY>
Instantiates a new object and invokes its constructor.
</SUMMARY>
<SYNTAX>
JSObject * JS_ConstructObject(JSContext *cx, JSClass *clasp,
JSObject *proto, JSObject *parent);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='clasp' type='JSClass *'>
Pointer to the class to use for the new object.<BR/>
</PARAM>
<PARAM name='proto' type='JSObject *'>
Pointer to the prototype object to use for the new class.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_GetFunctionObject'/>
</ENTRY>
<ENTRY id='JS_DefineObject'>
<TYPE value='Function'/>
<SUMMARY>
Instantiates an object that is a property of another object.
</SUMMARY>
<SYNTAX>
JSObject * JS_DefineObject(JSContext *cx, JSObject *obj,
const char *name, JSClass *clasp, JSObject *proto,
uintN flags);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information for error reporting.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object to which this new object belongs as a property.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name of the property that encapsulates the new object in <C>obj</C>.<BR/>
</PARAM>
<PARAM name='clasp' type='JSClass *'>
Class to use for the new object.<BR/>
</PARAM>
<PARAM name='proto' type='JSObject *'>
Prototype object to use for the new object.<BR/>
</PARAM>
<PARAM name='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:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Flag
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Purpose
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_ENUMERATE</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is visible to <B>for</B> and <B>in</B> loops.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_READONLY</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is read only.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_PERMANENT</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property cannot be deleted.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_EXPORTED</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property can be imported by other objects.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_INDEX</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
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>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_ValueToObject'/>
<SEEALSO value='JS_DefineConstDoubles'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_DefineElement'/>
</ENTRY>
<ENTRY id='JS_DefineConstDoubles'>
<TYPE value='Function'/>
<SUMMARY>
Creates one or more constant double-valued properties for an object.
</SUMMARY>
<SYNTAX>
JSBool JS_DefineConstDoubles(JSContext *cx, JSObject *obj,
JSConstDoubleSpec *cds);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to create new properties.<BR/>
</PARAM>
<PARAM name='*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/>
</DESCRIPTION>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JSConstDoubleSpec'/>
</ENTRY>
<ENTRY id='JS_DefineProperties'>
<TYPE value='Function'/>
<SUMMARY>
Creates one or more properties for an object.
</SUMMARY>
<SYNTAX>
JSBool JS_DefineProperties(JSContext *cx, JSObject *obj,
JSPropertySpec *ps);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to create new properties.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_DefineConstDoubles'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JSPropertySpec'/>
</ENTRY>
<ENTRY id='JS_DefineProperty'>
<TYPE value='Function'/>
<SUMMARY>
Creates a single property for a specified object.
</SUMMARY>
<SYNTAX>
JSBool) JS_DefineProperty(JSContext *cx, JSObject *obj,
const char *name, jsval value, JSPropertyOp getter,
JSPropertyOp setter, uintN flags);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to create the new property.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name for the property to create.<BR/>
</PARAM>
<PARAM name='value' type='jsval'>
Initial value to assign to the property.<BR/>
</PARAM>
<PARAM name='getter' type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current property value.<BR/>
</PARAM>
<PARAM name='setter' type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new property value.<BR/>
</PARAM>
<PARAM name='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:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Flag
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Purpose
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_ENUMERATE</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is visible in <B>for</B> and <B>in</B> loops.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_READONLY</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is read only.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_PERMANENT</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property cannot be deleted.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_EXPORTED</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property can be imported by other objects.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_INDEX</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
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>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_DefineConstDoubles'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_DefineElement'/>
</ENTRY>
<ENTRY id='JS_DefineUCProperty'>
<TYPE value='Function'/>
<SUMMARY>
Creates a single Unicode-encoded property for a specified object.
</SUMMARY>
<SYNTAX>
JSBool) JS_DefineUCProperty(JSContext *cx, JSObject *obj,
const jschar *name, size_t namelen, jsval value,
JSPropertyOp getter, JSPropertyOp setter, uintN attrs);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to create the new property.<BR/>
</PARAM>
<PARAM name='name' type='const jschar *'>
Name for the property to create.<BR/>
</PARAM>
<PARAM name='namelen' type='size_t'>
Length of <C>name</C>, in bytes.<BR/>
</PARAM>
<PARAM name='value' type='jsval'>
Initial value to assign to the property.<BR/>
</PARAM>
<PARAM name='getter' type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current property value.<BR/>
</PARAM>
<PARAM name='setter' type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new property value.<BR/>
</PARAM>
<PARAM name='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:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Flag
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Purpose
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_ENUMERATE</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is visible in <B>for</B> and <B>in</B> loops.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_READONLY</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is read only.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_PERMANENT</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property cannot be deleted.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_EXPORTED</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property can be imported by other objects.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_INDEX</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
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>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_DefineConstDoubles'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_DefineElement'/>
</ENTRY>
<ENTRY id='JS_DefinePropertyWithTinyId'>
<TYPE value='Function'/>
<SUMMARY>
Creates a single property for a specified object and assigns it an ID number.
</SUMMARY>
<SYNTAX>
JSBool JS_DefinePropertyWithTinyId( JSContext *cx,
JSObject *obj, const char *name, int8 tinyid, jsval value,
JSPropertyOp getter, JSPropertyOp setter, uintN flags);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to create the new property.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name for the property to create.<BR/>
</PARAM>
<PARAM name='tinyid' type='int8'>
8-bit ID to aid in sharing <C>getProperty</C>/<C>setProperty</C> methods among properties.<BR/>
</PARAM>
<PARAM name='value' type='jsval'>
Initial value to assign to the property.<BR/>
</PARAM>
<PARAM name='getter' type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current property value.<BR/>
</PARAM>
<PARAM name='setter' type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new property value.<BR/>
</PARAM>
<PARAM name='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:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Flag
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Purpose
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_ENUMERATE</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is visible in <B>for</B> and <B>in</B> loops.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_READONLY</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is read only.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_PERMANENT</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property cannot be deleted.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_EXPORTED</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property can be imported by other objects.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_INDEX</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
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>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_DefineConstDoubles'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
</ENTRY>
<ENTRY id='JS_DefineUCPropertyWithTinyID'>
<TYPE value='Function'/>
<SUMMARY>
Creates a single, Unicode-encoded property for a specified object and assigns it an ID number.
</SUMMARY>
<SYNTAX>
JSBool JS_DefinePropertyWithTinyId( JSContext *cx,
JSObject *obj, const jschar *name, size_t namelen,
int8 tinyid, jsval value, JSPropertyOp getter,
JSPropertyOp setter, uintN attrs);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to create the new property.<BR/>
</PARAM>
<PARAM name='name' type='const jschar *'>
Name for the property to create.<BR/>
</PARAM>
<PARAM name='namelen' type='size_t'>
Length, in bytes, of <C>name</C>.<BR/>
</PARAM>
<PARAM name='tinyid' type='int8'>
8-bit ID to aid in sharing <C>getProperty</C>/<C>setProperty</C> methods among properties.<BR/>
</PARAM>
<PARAM name='value' type='jsval'>
Initial value to assign to the property.<BR/>
</PARAM>
<PARAM name='getter' type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current property value.<BR/>
</PARAM>
<PARAM name='setter' type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new property value.<BR/>
</PARAM>
<PARAM name='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:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Flag
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Purpose
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_ENUMERATE</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is visible in <B>for</B> and <B>in</B> loops.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_READONLY</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property is read only.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_PERMANENT</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property cannot be deleted.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_EXPORTED</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Property can be imported by other objects.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_INDEX</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
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>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_DefineConstDoubles'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
</ENTRY>
<ENTRY id='JS_AliasProperty'>
<TYPE value='Function'/>
<SUMMARY>
Deprecated. Create an alias for a native property.
</SUMMARY>
<SYNTAX>
JSBool JS_AliasProperty(JSContext *cx, JSObject *obj,
const char *name, const char *alias);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to create the alias.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name of the property for which to create an alias.<BR/>
</PARAM>
<PARAM name='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/>
</NOTE>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_LookupProperty'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JS_LookupProperty'>
<TYPE value='Function'/>
<SUMMARY>
Determines if a specified property exists.
</SUMMARY>
<SYNTAX>
JSBool JS_LookupProperty(JSContext *cx, JSObject *obj,
const char *name, jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object to search on for the property.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name of the property to look up.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_AliasProperty'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
</ENTRY>
<ENTRY id='JS_LookupUCProperty'>
<TYPE value='Function'/>
<SUMMARY>
Determines if a specified, Unicode-encoded property exists.
</SUMMARY>
<SYNTAX>
JSBool JS_LookupUCProperty(JSContext *cx, JSObject *obj,
const jschar *name, size_t namelen, jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object to search on for the property.<BR/>
</PARAM>
<PARAM name='name' type='const jschar *'>
Name of the property to look up.<BR/>
</PARAM>
<PARAM name='namelen' type='size_t'>
Length, in bytes, of <C>name</C>.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_LookupProperty'/>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_AliasProperty'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
</ENTRY>
<ENTRY id='JS_GetProperty'>
<TYPE value='Function'/>
<SUMMARY>
Finds a specified property and retrieves its value.
</SUMMARY>
<SYNTAX>
JSBool JS_GetProperty(JSContext *cx, JSObject *obj,
const char *name, jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object to search on for the property.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name of the property to look up.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_AliasProperty'/>
<SEEALSO value='JS_LookupProperty'/>
<SEEALSO value='JS_GetUCProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_SetUCProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
<SEEALSO value='JS_DeleteProperty2'/>
<SEEALSO value='JS_DeleteUCProperty2'/>
</ENTRY>
<ENTRY id='JS_GetUCProperty'>
<TYPE value='Function'/>
<SUMMARY>
Finds a specified, Unicode-encoded property and retrieves its value.
</SUMMARY>
<SYNTAX>
JSBool JS_GetUCProperty(JSContext *cx, JSObject *obj,
const jschar *name, size_t namelen, jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object to search on for the property.<BR/>
</PARAM>
<PARAM name='name' type='const jschar *'>
Name of the property to look up.<BR/>
</PARAM>
<PARAM name='namelen' type='size_t'>
Length, in bytes of the the property name to look up.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_AliasProperty'/>
<SEEALSO value='JS_LookupProperty'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_SetUCProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
<SEEALSO value='JS_DeleteProperty2'/>
<SEEALSO value='JS_DeleteUCProperty2'/>
</ENTRY>
<ENTRY id='JS_SetProperty'>
<TYPE value='Function'/>
<SUMMARY>
Sets the current value of a property belonging to a specified object.
</SUMMARY>
<SYNTAX>
JSBool JS_SetProperty(JSContext *cx, JSObject *obj,
const char *name, jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object to which the property to set belongs.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name of the property to set.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_AliasProperty'/>
<SEEALSO value='JS_LookupProperty'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_GetUCProperty'/>
<SEEALSO value='JS_SetUCProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
<SEEALSO value='JS_DeleteProperty2'/>
<SEEALSO value='JS_DeleteUCProperty2'/>
</ENTRY>
<ENTRY id='JS_SetUCProperty'>
<TYPE value='Function'/>
<SUMMARY>
Sets the current value of a Unicode-encoded property belonging to a specified object.
</SUMMARY>
<SYNTAX>
JSBool JS_SetUCProperty(JSContext *cx, JSObject *obj,
const char *name, jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object to which the property to set belongs.<BR/>
</PARAM>
<PARAM name='name' type='const jschar *'>
Name of the property to set.<BR/>
</PARAM>
<PARAM name='namelen' type='size_t'>
Length, in bytes, of the name of the property to set.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_AliasProperty'/>
<SEEALSO value='JS_LookupProperty'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_GetUCProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
<SEEALSO value='JS_DeleteProperty2'/>
<SEEALSO value='JS_DeleteUCProperty2'/>
</ENTRY>
<ENTRY id='JS_DeleteProperty'>
<TYPE value='Function'/>
<SUMMARY>
Removes a specified property from an object.
</SUMMARY>
<SYNTAX>
JSBool JS_DeleteProperty(JSContext *cx, JSObject *obj,
const char *name);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object from which to delete a property.<BR/>
</PARAM>
<PARAM name='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>.
<P/>
</NOTE>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_AliasProperty'/>
<SEEALSO value='JS_LookupProperty'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_LookupUCProperty'/>
<SEEALSO value='JS_GetUCProperty'/>
<SEEALSO value='JS_SetUCProperty'/>
<SEEALSO value='JS_DeleteProperty2'/>
<SEEALSO value='JS_DeleteUCProperty2'/>
<SEEALSO value='JS_ClearScope'/>
</ENTRY>
<ENTRY id='JS_DeleteProperty2'>
<TYPE value='Function'/>
<SUMMARY>
Removes a specified property from an object.
</SUMMARY>
<SYNTAX>
JSBool JS_DeleteProperty2(JSContext *cx, JSObject *obj,
const char *name, jsval *rva);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object from which to delete a property.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name of the property to delete.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_AliasProperty'/>
<SEEALSO value='JS_LookupProperty'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_LookupUCProperty'/>
<SEEALSO value='JS_GetUCProperty'/>
<SEEALSO value='JS_SetUCProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
<SEEALSO value='JS_DeleteUCProperty2'/>
<SEEALSO value='JS_ClearScope'/>
</ENTRY>
<ENTRY id='JS_DeleteUCProperty2'>
<TYPE value='Function'/>
<SUMMARY>
Removes a specified Unicode-encoded property from an object.
</SUMMARY>
<SYNTAX>
JSBool JS_DeleteUCProperty2(JSContext *cx, JSObject *obj,
const jschar *name, size_t namelen, jsval *rva);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object from which to delete a property.<BR/>
</PARAM>
<PARAM name='name' type='const jschar *'>
Name of the property to delete.<BR/>
</PARAM>
<PARAM name='namelen' type='size_t'>
Length, in bytes, of the property name.<BR/>
</PARAM>
<PARAM name='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>.
<P/>
</NOTE>
<SEEALSO value='JS_PropertyStub'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefineUCProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineUCPropertyWithTinyID'/>
<SEEALSO value='JS_AliasProperty'/>
<SEEALSO value='JS_LookupProperty'/>
<SEEALSO value='JS_GetProperty'/>
<SEEALSO value='JS_SetProperty'/>
<SEEALSO value='JS_LookupUCProperty'/>
<SEEALSO value='JS_GetUCProperty'/>
<SEEALSO value='JS_SetUCProperty'/>
<SEEALSO value='JS_DeleteProperty'/>
<SEEALSO value='JS_DeleteProperty2'/>
<SEEALSO value='JS_ClearScope'/>
</ENTRY>
<ENTRY id='JS_GetPropertyAttributes'>
<TYPE value='Function'/>
<SUMMARY>
Retrieves the attributes of a specified property.
</SUMMARY>
<SYNTAX>
JSBool JS_GetPropertyAttributes(JSContext *cx, JSObject *obj,
const char *name, uintN *attrsp, JSBool *foundp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object from which to retrieve property attributes.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name of the property from which to retrieve attributes.<BR/>
</PARAM>
<PARAM name='uintN' type='attrsp *'>
Pointer to the storage area into which to place retrieves attributes.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_SetPropertyAttributes'/>
</ENTRY>
<ENTRY id='JS_SetPropertyAttributes'>
<TYPE value='Function'/>
<SUMMARY>
Sets the attributes for a specified property.
</SUMMARY>
<SYNTAX>
JSBool JS_SetPropertyAttributes(JSContext *cx, JSObject *obj,
const char *name, uintN attrs, JSBool *foundp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to set property attributes.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name of the property for which to set attributes.<BR/>
</PARAM>
<PARAM name='uintN' type='attrsp'>
Attribute values to set.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_GetPropertyAttributes'/>
</ENTRY>
<ENTRY id='JS_NewArrayObject'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new array object.
</SUMMARY>
<SYNTAX>
JSObject * JS_NewArrayObject(JSContext *cx, jsint length,
jsval *vector);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='length' type='jsint'>
Number of elements to include in the array.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_IsArrayObject'>
<TYPE value='Function'/>
<SUMMARY>
Determines if a specified object is of the Array class.
</SUMMARY>
<SYNTAX>
JSBool JS_IsArrayObject(JSContext *cx, JSObject *obj);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_GetArrayLength'>
<TYPE value='Function'/>
<SUMMARY>
Retrieves the number of elements in an array object.
</SUMMARY>
<SYNTAX>
JSBool JS_GetArrayLength(JSContext *cx, JSObject *obj,
jsint *lengthp);
<PARAM name='cx' type='JSContext *'>
Pointer to the JS context for the object.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Array object for which the number of array elements.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_SetArrayLength'>
<TYPE value='Function'/>
<SUMMARY>
Specifies the number of elements for an array object.
</SUMMARY>
<SYNTAX>
JSBool JS_SetArrayLength(JSContext *cx, JSObject *obj,
jsint length);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Array object for which to set the number of array elements.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_HasArrayLength'>
<TYPE value='Function'/>
<SUMMARY>
Determines if an object has an array length property.
</SUMMARY>
<SYNTAX>
JSBool JS_HasArrayLength(JSContext *cx, JSObject *obj,
jsuint *lengthp);
</SYNTAX>
<DESCRIPTION>
<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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_DefineElement'>
<TYPE value='Function'/>
<SUMMARY>
Creates a single element or numeric property for a specified object.
</SUMMARY>
<SYNTAX>
JSBool JS_DefineElement(JSContext *cx, JSObject *obj,
jsint index, jsval value, JSPropertyOp getter,
JSPropertyOp setter, uintN flags);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to create the new element.<BR/>
</PARAM>
<PARAM name='index' type='jsint'>
Array index number for the element to define.<BR/>
</PARAM>
<PARAM name='value' type='jsval'>
Initial value to assign to the element.<BR/>
</PARAM>
<PARAM name='getter' type='JSPropertyOp'>
<C>getProperty</C> method for retrieving the current element value.<BR/>
</PARAM>
<PARAM name='setter' type='JSPropertyOp'>
<C>setProperty</C> method for specifying a new element value.<BR/>
</PARAM>
<PARAM name='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:
<![CDATA[
<TABLE BORDER="0">
<TR><TD VALIGN='baseline' ALIGN='left'>
<B>Flag
</B></TD><TD VALIGN='baseline' ALIGN='left'>
<B>Purpose
</B>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_ENUMERATE</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Element is visible in <B>for</B> and <B>in</B> loops.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_READONLY</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Element is read only.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_PERMANENT</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Element cannot be deleted.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_EXPORTED</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
Element can be imported by other objects.</P>
</TD></TR><TR> <TD VALIGN='baseline' ALIGN='left'><P>
<CODE>JSPROP_INDEX</CODE></TD><TD VALIGN='baseline' ALIGN='left'><P>
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 element, <C>JS_DefineElement</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_DefineConstDoubles'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_AliasElement'>
<TYPE value='Function'/>
<SUMMARY>
Deprecated. Create an aliased index entry for an existing element or numeric property of a native object.
</SUMMARY>
<SYNTAX>
JSBool JS_AliasElement(JSContext *cx, JSObject *obj,
const char *name, jsint alias);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to create the alias.<BR/>
</PARAM>
<PARAM name='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>
<PARAM name='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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
<DEPRECATED/>
</ENTRY>
<ENTRY id='JS_LookupElement'>
<TYPE value='Function'/>
<SUMMARY>
Determines if a specified element or numeric property exists.
</SUMMARY>
<SYNTAX>
JSBool JS_LookupElement(JSContext *cx, JSObject *obj,
jsint index, jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object to search on for the element.<BR/>
</PARAM>
<PARAM name='index' type='jsint'>
Index number of the element to look up.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_GetElement'>
<TYPE value='Function'/>
<SUMMARY>
Finds specified element or numeric property associated with an object or the object's class and retrieves its current value.
</SUMMARY>
<SYNTAX>
JSBool JS_GetElement(JSContext *cx, JSObject *obj, jsint index,
jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Array object to search on for the element.<BR/>
</PARAM>
<PARAM name='index' type='jsint'>
Index number of the element to look up.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_SetElement'>
<TYPE value='Function'/>
<SUMMARY>
Sets the current value of an element or numeric property belonging to a specified object.
</SUMMARY>
<SYNTAX>
JSBool JS_SetElement(JSContext *cx, JSObject *obj, jsint index,
jsval *vp);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Array object to which the element to set belongs.<BR/>
</PARAM>
<PARAM name='index' type='jsint'>
Index number of the element to set.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_DeleteElement'>
<TYPE value='Function'/>
<SUMMARY>
Public. Removes a specified element or numeric property from an object.
</SUMMARY>
<SYNTAX>
JSBool JS_DeleteElement(JSContext *cx, JSObject *obj,
jsint index);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object from which to delete an element.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement2'/>
<SEEALSO value='JS_ClearScope'/>
</ENTRY>
<ENTRY id='JS_DeleteElement2'>
<TYPE value='Function'/>
<SUMMARY>
Removes a specified element or numeric property from an object.
</SUMMARY>
<SYNTAX>
JSBool JS_DeleteElement2(JSContext *cx, JSObject *obj,
const char *name, jsval *rva);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object from which to delete an element.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name of the element to delete.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_IsArrayObject'/>
<SEEALSO value='JS_GetArrayLength'/>
<SEEALSO value='JS_SetArrayLength'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_AliasElement'/>
<SEEALSO value='JS_LookupElement'/>
<SEEALSO value='JS_GetElement'/>
<SEEALSO value='JS_SetElement'/>
<SEEALSO value='JS_DeleteElement'/>
<SEEALSO value='JS_ClearScope'/>
</ENTRY>
<ENTRY id='JS_ClearScope'>
<TYPE value='Function'/>
<SUMMARY>
Removes all properties associated with an object.
</SUMMARY>
<SYNTAX>
void JS_ClearScope(JSContext *cx, JSObject *obj);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_GetScopeChain'/>
<SEEALSO value='JS_DeleteProperty'/>
<SEEALSO value='JS_DeleteElement'/>
</ENTRY>
<ENTRY id='JS_Enumerate'>
<TYPE value='Function'/>
<SUMMARY>
Enumerates the properties of a specified object.
</SUMMARY>
<SYNTAX>
JSIdArray * JS_Enumerate(JSContext *cx, JSObject *obj);
</SYNTAX>
<DESCRIPTION>
<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/>
</DESCRIPTION>
</ENTRY>
<ENTRY id='JS_CheckAccess'>
<TYPE value='Function'/>
<SUMMARY>
Determines the scope of access to an object.
</SUMMARY>
<SYNTAX>
JSBool JS_CheckAccess(JSContext *cx, JSObject *obj, jsid id,
JSAccessMode mode, jsval *vp, uintN *attrsp);
</SYNTAX>
<DESCRIPTION>
<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>
<ENTRY id='JS_NewFunction'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new JS function that wraps a native C function.
</SUMMARY>
<SYNTAX>
JSFunction * JS_NewFunction(JSContext *cx, JSNative call,
uintN nargs, uintN flags, JSObject *parent,
const char *name);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='call' type='JSNative'>
Native C function call wrapped by this function. <BR/>
</PARAM>
<PARAM name='nargs' type='uintN'>
Number of arguments that are passed to the underlying C function.<BR/>
</PARAM>
<PARAM name='flags' type='uintN'>
Function attributes. <BR/>
</PARAM>
<PARAM name='parent' type='JSObject *'>
Pointer to the parent object for this function.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_GetFunctionName'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_CompileUCFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_GetFunctionObject'>
<TYPE value='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>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionName'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_CompileUCFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_GetFunctionName'>
<TYPE value='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
function, <C>fun</C>, is in existence.
<P/>
</NOTE>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_CompileUCFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_DefineFunctions'>
<TYPE value='Function'/>
<SUMMARY>
Creates one or more functions for a JS object.
</SUMMARY>
<SYNTAX>
JSBool JS_DefineFunctions(JSContext *cx, JSObject *obj,
JSFunctionSpec *fs);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to define functions.<BR/>
</PARAM>
<PARAM name='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/>
If it successfully creates properties for all the functions specified in the array, <C>JS_DefineFunctions</C> returns <C>JS_TRUE</C>. Otherwise it returns <C>JS_FALSE</C>.<P/>
</DESCRIPTION>
<NOTE>
To define only a single function for an object, call <C>JS_DefineFunction</C>.
<P/>
</NOTE>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_DefineConstDoubles'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_GetFunctionName'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_CompileUCFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_DefineFunction'>
<TYPE value='Function'/>
<SUMMARY>
Creates a function and assigns it as a property to a specified JS object.
</SUMMARY>
<SYNTAX>
JSFunction * JS_DefineFunction(JSContext *cx, JSObject *obj,
const char *name, JSNative call, uintN nargs, uintN flags);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object for which to define a function as a property (method).<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name to assign to the function.<BR/>
</PARAM>
<PARAM name='call' type='JSNative'>
Indicates the built-in, native C call wrapped by this function.<BR/>
</PARAM>
<PARAM name='nargs' type='uintN'>
Number of arguments that are passed to the function when it is called.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_DefineObject'/>
<SEEALSO value='JS_DefineConstDoubles'/>
<SEEALSO value='JS_DefineProperties'/>
<SEEALSO value='JS_DefineProperty'/>
<SEEALSO value='JS_DefinePropertyWithTinyId'/>
<SEEALSO value='JS_DefineElement'/>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_CloneFunctionObject'>
<TYPE value='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/>
</DESCRIPTION>
<SEEALSO value='JS_GetFunctionObject'/>
</ENTRY>
<ENTRY id='JS_CompileScript'>
<TYPE value='Function'/>
<SUMMARY>
Compiles a script for execution.
</SUMMARY>
<SYNTAX>
JSScript * JS_CompileScript(JSContext *cx, JSObject *obj,
const char *bytes, size_t length, const char *filename,
uintN lineno);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='bytes' type='const char *'>
String containing the script to compile.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Size, in bytes, of the script to compile.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='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>.
<P/>
</NOTE>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_CompileUCScript'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
</ENTRY>
<ENTRY id='JS_CompileScriptForPrincipals'>
<TYPE value='Function'/>
<SUMMARY>
Compiles a security-enabled script for execution.
</SUMMARY>
<SYNTAX>
JSScript * JS_CompileScriptForPrincipals(JSContext *cx,
JSObject *obj, JSPrincipals *principals, const char *bytes,
size_t length, const char *filename, uintN lineno);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='principals' type='JSPrincipals *'>
Pointer to the structure holding the security information for this script.<BR/>
</PARAM>
<PARAM name='bytes' type='const char *'>
String containing the script to compile.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Size, in bytes, of the script to compile.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_CompileUCScript'/>
<SEEALSO value='JS_CompileUCScriptForPrincipals'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
<SEEALSO value='JS_EvaluateScriptForPrincipals'/>
</ENTRY>
<ENTRY id='JS_CompileUCScript'>
<TYPE value='Function'/>
<SUMMARY>
Compiles a Unicode-encoded script for execution.
</SUMMARY>
<SYNTAX>
JSScript * JS_CompileUCScript(JSContext *cx, JSObject *obj,
const jschar *chars, size_t length, const char *filename,
uintN lineno);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='chars' type='const jschar *'>
String containing the script to compile.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Number of Unicode characters in the script to compile.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
</ENTRY>
<ENTRY id='JS_CompileUCScriptForPrincipals'>
<TYPE value='Function'/>
<SUMMARY>
Compiles a security-enabled, Unicode-encoded script for execution.
</SUMMARY>
<SYNTAX>
JSScript * JS_CompileUCScriptForPrincipals(JSContext *cx,
JSObject *obj,JSPrincipals *principals, const jschar *chars,
size_t length, const char *filename, uintN lineno);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='principals' type='JSPrincipals *'>
Pointer to the structure holding the security information for this script.<BR/>
</PARAM>
<PARAM name='chars' type='const jschar *'>
String containing the script to compile.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Number of Unicode characters in the script to compile.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_CompileScriptForPrincipals'/>
<SEEALSO value='JS_CompileUCScript'/>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
<SEEALSO value='JS_EvaluateScriptForPrincipals'/>
</ENTRY>
<ENTRY id='JS_CompileFile'>
<TYPE value='Function'/>
<SUMMARY>
Compiles a script stored in an external file.
</SUMMARY>
<SYNTAX>
JSScript * JS_CompileFile(JSContext *cx, JSObject *obj,
const char *filename);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='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 available only 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>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
</ENTRY>
<ENTRY id='JS_NewScriptObject'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new object and associates a script with it.
</SUMMARY>
<SYNTAX>
JSObject * JS_NewScriptObject(JSContext *cx, JSScript *script);
</SYNTAX>
<DESCRIPTION>
<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/>
</DESCRIPTION>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
</ENTRY>
<ENTRY id='JS_DestroyScript'>
<TYPE value='Function'/>
<SUMMARY>
Frees a compiled script when no longer needed.
</SUMMARY>
<SYNTAX>
void) JS_DestroyScript(JSContext *cx, JSScript *script);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
</ENTRY>
<ENTRY id='JS_CompileFunction'>
<TYPE value='Function'/>
<SUMMARY>
Creates a JS function from a text string.
</SUMMARY>
<SYNTAX>
JSFunction * JS_CompileFunction(JSContext *cx, JSObject *obj,
const char *name, uintN nargs, const char **argnames,
const char *bytes, size_t length, const char *filename,
uintN lineno);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the function is associated.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name to assign the newly compiled function.<BR/>
</PARAM>
<PARAM name='nargs' type='uintN'>
Number of arguments to pass to the function.<BR/>
</PARAM>
<PARAM name='argnames' type='const char **'>
Names to assign to the arguments passed to the function.<BR/>
</PARAM>
<PARAM name='bytes' type='const char *'>
String containing the function to compile.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Size, in bytes, of the function to compile.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the function. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_CompileFunctionForPrincipals'>
<TYPE value='Function'/>
<SUMMARY>
Creates a security-enabled JS function from a text string.
</SUMMARY>
<SYNTAX>
JSFunction * JS_CompileFunctionForPrincipals(JSContext *cx,
JSObject *obj, JSPrincipals *principals, const char *name,
uintN nargs, const char **argnames, const char *bytes,
size_t length, const char *filename, uintN lineno);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the function is associated.<BR/>
</PARAM>
<PARAM name='principals' type='JSPrincipals *'>
Pointer to the structure holding the security information for this function.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name to assign the newly compiled function.<BR/>
</PARAM>
<PARAM name='nargs' type='uintN'>
Number of arguments to pass to the function.<BR/>
</PARAM>
<PARAM name='argnames' type='const char **'>
Names to assign to the arguments passed to the function.<BR/>
</PARAM>
<PARAM name='bytes' type='const char *'>
String containing the function to compile.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Size, in bytes, of the function to compile.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the function. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JSFUN_BOUND_METHOD'/>
<SEEALSO value='JSFUN_GLOBAL_PARENT'/>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_CompileUCFunction'/>
<SEEALSO value='JS_CompileUCFunctionForPrincipals'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
</ENTRY>
<ENTRY id='JS_CompileUCFunction'>
<TYPE value='Function'/>
<SUMMARY>
Creates a JS function from a Unicode-encoded character string.
</SUMMARY>
<SYNTAX>
JSFunction * JS_CompileUCFunction(JSContext *cx, JSObject *obj,
const char *name, uintN nargs, const char **argnames,
const jschar *chars, size_t length, const char *filename,
uintN lineno);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the function is associated.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name to assign the newly compiled function.<BR/>
</PARAM>
<PARAM name='nargs' type='uintN'>
Number of arguments to pass to the function.<BR/>
</PARAM>
<PARAM name='argnames' type='const char **'>
Names to assign to the arguments passed to the function.<BR/>
</PARAM>
<PARAM name='chars' type='const jschar *'>
Unicode string containing the function to compile.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Size, in Unicode characters, of the function to compile.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the function. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_CompileUCFunctionForPrincipals'>
<TYPE value='Function'/>
<SUMMARY>
Creates a JS function with security informtion from a Unicode-encoded character string.
</SUMMARY>
<SYNTAX>
JSFunction * JS_CompileUCFunctionForPrincipals(JSContext *cx,
JSObject *obj, JSPrincipals *principals, const char *name,
uintN nargs, const char **argnames, const jschar *chars,
size_t length, const char *filename, uintN lineno);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the function is associated.<BR/>
</PARAM>
<PARAM name='principals' type='JSPrincipals *'>
Pointer to the structure holding the security information for this function.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name to assign the newly compiled function.<BR/>
</PARAM>
<PARAM name='nargs' type='uintN'>
Number of arguments to pass to the function.<BR/>
</PARAM>
<PARAM name='argnames' type='const char **'>
Names to assign to the arguments passed to the function.<BR/>
</PARAM>
<PARAM name='chars' type='const jschar *'>
Unicode string containing the function to compile.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Size, in Unicode characters, of the function to compile.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the function. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileUCFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
</ENTRY>
<ENTRY id='JS_DecompileScript'>
<TYPE value='Function'/>
<SUMMARY>
Creates the source code of a script from a script's compiled form.
</SUMMARY>
<SYNTAX>
JSString * JS_DecompileScript(JSContext *cx, JSScript *script,
const char *name, uintN indent);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context.<BR/>
</PARAM>
<PARAM name='script' type='JSScript *'>
Script to decompile.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
Name to assign to the decompiled script.<BR/>
</PARAM>
<PARAM name='indent' type='uintN'>
Number of spaces to use for indented code.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<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>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
</ENTRY>
<ENTRY id='JS_DecompileFunction'>
<TYPE value='Function'/>
<SUMMARY>
Generates the complete source code of a function declaration from a compiled function.
</SUMMARY>
<SYNTAX>
JSString * JS_DecompileFunction(JSContext *cx, JSFunction *fun,
uintN indent);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='fun' type='JSFunction *'>
Function to decompile.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_DecompileFunctionBody'>
<TYPE value='Function'/>
<SUMMARY>
Generates the source code representing the body of a function, minus the <C>function</C> keyword, name, parameters, and braces.
</SUMMARY>
<SYNTAX>
JSString * JS_DecompileFunctionBody(JSContext *cx,
JSFunction *fun, uintN indent);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='fun' type='JSFunction *'>
Function to decompile.<BR/>
</PARAM>
<PARAM name='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>.
<P/>
</NOTE>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_ExecuteScript'>
<TYPE value='Function'/>
<SUMMARY>
Executes a compiled script.
</SUMMARY>
<SYNTAX>
JSBool JS_ExecuteScript(JSContext *cx, JSObject *obj,
JSScript *script, jsval *rval);
<PARAM name='cx' type='JSContext *'>
JS context in which the script executes.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='script' type='JSScript *'>
Previously compiled script to execute.<BR/>
</PARAM>
<PARAM name='rval' type='jsval *'>
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
execute the script.
<P/>
</NOTE>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_EvaluateScript'/>
</ENTRY>
<ENTRY id='JS_EvaluateScript'>
<TYPE value='Function'/>
<SUMMARY>
Compiles and executes a script.
</SUMMARY>
<SYNTAX>
JSBool JS_EvaluateScript(JSContext *cx, JSObject *obj,
const char *bytes, uintN length, const char *filename,
uintN lineno, jsval *rval);
<PARAM name='cx' type='JSContext *'>
JS context in which the script compiles and executes.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='bytes' type='const char *'>
String containing the script to compile and execute.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Size, in bytes, of the script to compile and execute.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='lineno' type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScriptForPrincipals'/>
</ENTRY>
<ENTRY id='JS_EvaluateUCScript'>
<TYPE value='Function'/>
<SUMMARY>
Compiles and executes a Unicode-encoded script.
</SUMMARY>
<SYNTAX>
JSBool JS_EvaluateUCScript(JSContext *cx, JSObject *obj,
const jschar *chars, uintN length, const char *filename,
uintN lineno, jsval *rval);
<PARAM name='cx' type='JSContext *'>
JS context in which the script compiles and executes.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='chars' type='const jschar *'>
Unicode character array ontaining the script to compile and execute.<BR/>
</PARAM>
<PARAM name='length' type='uintN'>
Size, in Unicode characters, of the script to compile and execute.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='lineno' type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
<SEEALSO value='JS_EvaluateScriptForPrincipals'/>
<SEEALSO value='JS_EvaluateUCScriptForPrincipals'/>
</ENTRY>
<ENTRY id='JS_EvaluateScriptForPrincipals'>
<TYPE value='Function'/>
<SUMMARY>
Compiles and executes a security-enabled script.
</SUMMARY>
<SYNTAX>
JSBool JS_EvaluateScriptForPrincipals(JSContext *cx,
JSObject *obj, JSPrincipals *principals, const char *bytes,
uintN length, const char *filename, uintN lineno,
jsval *rval);
<PARAM name='cx' type='JSContext *'>
JS context in which the script compiles and executes.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='principals' type='JSPrincipals *'>
Pointer to the structure holding the security information for this script.<BR/>
</PARAM>
<PARAM name='bytes' type='const char *'>
String containing the script to compile and execute.<BR/>
</PARAM>
<PARAM name='length' type='size_t'>
Size, in bytes, of the script to compile and execute.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='lineno' type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
<SEEALSO value='JS_EvaluateUCScript'/>
<SEEALSO value='JS_EvaluateUCScriptForPrincipals'/>
</ENTRY>
<ENTRY id='JS_EvaluateUCScriptForPrincipals'>
<TYPE value='Function'/>
<SUMMARY>
Compiles and executes a security-enabled,Unicode-encoded character script.
</SUMMARY>
<SYNTAX>
JSBool JS_EvaluateScriptUCForPrincipals(JSContext *cx,
JSObject *obj, JSPrincipals *principals, const jschar *chars,
uintN length, const char *filename, uintN lineno,
jsval *rval);
<PARAM name='cx' type='JSContext *'>
JS context in which the script compiles and executes.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
Object with which the script is associated.<BR/>
</PARAM>
<PARAM name='principals' type='JSPrincipals *'>
Pointer to the structure holding the security information for this script.<BR/>
</PARAM>
<PARAM name='chars' type='const jschar *'>
Unicode-encoded character array containing the script to compile and execute.<BR/>
</PARAM>
<PARAM name='length' type='uintN'>
Size, in Unicode characters, of the script to compile and execute.<BR/>
</PARAM>
<PARAM name='filename' type='const char *'>
Name of file or URL containing the script. Used to report filename or URL in error messages.<BR/>
</PARAM>
<PARAM name='lineno' type='uintN'>
Line number. Used to report the offending line in the file or URL if an error occurs.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_CompileScript'/>
<SEEALSO value='JS_CompileFile'/>
<SEEALSO value='JS_DestroyScript'/>
<SEEALSO value='JS_DecompileScript'/>
<SEEALSO value='JS_ExecuteScript'/>
<SEEALSO value='JS_EvaluateScript'/>
<SEEALSO value='JS_EvaluateUCScript'/>
<SEEALSO value='JS_EvaluateScriptForPrincipals'/>
</ENTRY>
<ENTRY id='JS_CallFunction'>
<TYPE value='Function'/>
<SUMMARY>
Calls a specified function.
</SUMMARY>
<SYNTAX>
JSBool JS_CallFunction(JSContext *cx, JSObject *obj,
JSFunction *fun, uintN argc, jsval *argv, jsval *rval);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
The "current" object on which the function operates; the object specified here is "this" when the function executes.<BR/>
</PARAM>
<PARAM name='*fun' type='JSFunction *'>
Pointer to the function to call.<BR/>
</PARAM>
<PARAM name='argc' type='uintN'>
Number of arguments you are passing to the function.<BR/>
</PARAM>
<PARAM name='argv' type='jsval *'>
Pointer to the array of argument values to pass to the function.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_CallFunctionName'>
<TYPE value='Function'/>
<SUMMARY>
Calls a function-valued property belonging to an object.
</SUMMARY>
<SYNTAX>
JSBool JS_CallFunctionName(JSContext *cx, JSObject *obj,
const char *name, uintN argc, jsval *argv, jsval *rval);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
The object containing the method to execute.<BR/>
</PARAM>
<PARAM name='name' type='const char *'>
The name of the function to execute.<BR/>
</PARAM>
<PARAM name='argc' type='uintN'>
Number of arguments you are passing to the function.<BR/>
</PARAM>
<PARAM name='argv' type='jsval *'>
Pointer to the array of argument values to pass to the function.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionValue'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_CallFunctionValue'>
<TYPE value='Function'/>
<SUMMARY>
Calls a function referenced by a <C>jsval</C>.
</SUMMARY>
<SYNTAX>
JSBool JS_CallFunctionValue(JSContext *cx, JSObject *obj,
jsval fval, uintN argc, jsval *argv, jsval *rval);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='obj' type='JSObject *'>
The "current" object on which the function operates; the object specified here is "this" when the function executes.<BR/>
</PARAM>
<PARAM name='fval' type='jsval'>
The jsval containing the function to execute.<BR/>
</PARAM>
<PARAM name='argc' type='uintN'>
Number of arguments you are passing to the function.<BR/>
</PARAM>
<PARAM name='argv' type='jsval *'>
Pointer to the array of argument values to pass to the function.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_ValueToFunction'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_GetFunctionObject'/>
<SEEALSO value='JS_DefineFunctions'/>
<SEEALSO value='JS_DefineFunction'/>
<SEEALSO value='JS_CompileFunction'/>
<SEEALSO value='JS_DecompileFunction'/>
<SEEALSO value='JS_DecompileFunctionBody'/>
<SEEALSO value='JS_CallFunction'/>
<SEEALSO value='JS_CallFunctionName'/>
<SEEALSO value='JS_SetBranchCallback'/>
</ENTRY>
<ENTRY id='JS_SetBranchCallback'>
<TYPE value='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.
</SUMMARY>
<SYNTAX>
JSBranchCallback JS_SetBranchCallback(JSContext *cx,
JSBranchCallback cb);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<ENTRY id='JS_IsRunning'>
<TYPE value='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>
<SEEALSO value='JS_Init'/>
<SEEALSO value='JS_Finish'/>
<SEEALSO value='JS_NewContext'/>
<SEEALSO value='JS_DestroyContext'/>
<SEEALSO value='JS_GetRuntime'/>
<SEEALSO value='JS_ContextIterator'/>
</ENTRY>
<ENTRY id='JS_IsConstructing'>
<TYPE value='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/>
</DESCRIPTION>
</ENTRY>
<ENTRY id='JS_NewString'>
<TYPE value='Function'/>
<SUMMARY>
Allocates a new JS string.
</SUMMARY>
<SYNTAX>
JSString * JS_NewString(JSContext *cx, char *bytes,
size_t length);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='bytes' type='char *'>
Pointer to the byte array containing the text for the JS string to create.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewUCString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewUCStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_NewUCStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_InternUCString'/>
<SEEALSO value='JS_InternUCStringN'/>
<SEEALSO value='JS_GetStringChars'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
<SEEALSO value='JS_malloc'/>
</ENTRY>
<ENTRY id='JS_NewUCString'>
<TYPE value='Function'/>
<SUMMARY>
Allocates a new JS Unicode-encoded string.
</SUMMARY>
<SYNTAX>
JSString * JS_NewUCString(JSContext *cx, jschar *chars,
size_t length);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='chars' type='jschar *'>
Pointer to the Unicode-encoded character array containing the text for the JS string to create.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewUCStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_NewUCStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_InternUCString'/>
<SEEALSO value='JS_InternUCStringN'/>
<SEEALSO value='JS_GetStringChars'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
<SEEALSO value='JS_malloc'/>
</ENTRY>
<ENTRY id='JS_NewStringCopyN'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new JS string of a specified size.
</SUMMARY>
<SYNTAX>
JSString * JS_NewStringCopyN(JSContext *cx, const char *s,
size_t n);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='s' type='const char *'>
Pointer to the character array containing the text for the JS string to create.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewUCString'/>
<SEEALSO value='JS_NewUCStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_NewUCStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_InternUCString'/>
<SEEALSO value='JS_InternUCStringN'/>
<SEEALSO value='JS_GetStringChars'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
<SEEALSO value='JS_malloc'/>
</ENTRY>
<ENTRY id='JS_NewUCStringCopyN'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new Unicode-encoded JS string of a specified size.
</SUMMARY>
<SYNTAX>
JSString * JS_NewUCStringCopyN(JSContext *cx, const jschar *s,
size_t n);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='s' type='const jschar *'>
Pointer to the Unicode character array containing the text for the JS string to create.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewUCString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_NewUCStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_InternUCString'/>
<SEEALSO value='JS_InternUCStringN'/>
<SEEALSO value='JS_GetStringChars'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
<SEEALSO value='JS_malloc'/>
</ENTRY>
<ENTRY id='JS_NewStringCopyZ'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new JS string and ensures that the resulting string is null-terminated.
</SUMMARY>
<SYNTAX>
JSString * JS_NewStringCopyZ(JSContext *cx, const char *s);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewUCString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewUCStringCopyN'/>
<SEEALSO value='JS_NewUCStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_InternUCString'/>
<SEEALSO value='JS_InternUCStringN'/>
<SEEALSO value='JS_GetStringChars'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
<SEEALSO value='JS_malloc'/>
</ENTRY>
<ENTRY id='JS_NewUCStringCopyZ'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new Unicode-encoded JS string and ensures that the resulting string is null-terminated.
</SUMMARY>
<SYNTAX>
JSString * JS_NewUCStringCopyZ(JSContext *cx, const jschar *s);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewUCString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewUCStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_InternUCString'/>
<SEEALSO value='JS_InternUCStringN'/>
<SEEALSO value='JS_GetStringChars'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
<SEEALSO value='JS_malloc'/>
</ENTRY>
<ENTRY id='JS_InternString'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new, static JS string whose value is automatically shared by all string literals that are identical.
</SUMMARY>
<SYNTAX>
JSString * JS_InternString(JSContext *cx, const char *s);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewUCString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewUCStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_NewUCStringCopyZ'/>
<SEEALSO value='JS_InternUCString'/>
<SEEALSO value='JS_InternUCStringN'/>
<SEEALSO value='JS_GetStringChars'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
</ENTRY>
<ENTRY id='JS_InternUCString'>
<TYPE value='Function'/>
<SUMMARY>
Creates a new, static, Unicode-encoded JS string whose value is automatically shared by all string literals that are identical.
</SUMMARY>
<SYNTAX>
JSString * JS_InternUCString(JSContext *cx, const jschar *s);
</SYNTAX>
<DESCRIPTION>
<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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewUCString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewUCStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_NewUCStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_InternUCStringN'/>
<SEEALSO value='JS_GetStringChars'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
</ENTRY>
<ENTRY id='JS_InternUCStringN'>
<TYPE value='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.
</SUMMARY>
<SYNTAX>
JSString * JS_InternUCStringN(JSContext *cx, const jschar *s, size_t length);
</SYNTAX>
<DESCRIPTION>
<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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewUCString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewUCStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_NewUCStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_InternUCString'/>
<SEEALSO value='JS_GetStringChars'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
</ENTRY>
<ENTRY id='JS_GetStringChars'>
<TYPE value='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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewUCString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewUCStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_NewUCStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_InternUCString'/>
<SEEALSO value='JS_InternUCStringN'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
</ENTRY>
<ENTRY id='JS_GetStringBytes'>
<TYPE value='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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_GetStringLength'/>
<SEEALSO value='JS_CompareStrings'/>
</ENTRY>
<ENTRY id='JS_GetStringLength'>
<TYPE value='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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_CompareStrings'/>
</ENTRY>
<ENTRY id='JS_CompareStrings'>
<TYPE value='Function'/>
<SUMMARY>
Compares two JS strings, and reports the results of the comparison.
</SUMMARY>
<SYNTAX>
intN JS_CompareStrings(JSString *str1, JSString *str2);
<PARAM name='str1' type='JSString *'>
First string to compare.<BR/>
</PARAM>
<PARAM name='str2' type='JSString *'>
Second string to compare.<BR/>
</PARAM>
</SYNTAX>
<DESCRIPTION>
<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>
<SEEALSO value='JS_GetEmptyStringValue'/>
<SEEALSO value='JS_ValueToString'/>
<SEEALSO value='JS_ConvertValue'/>
<SEEALSO value='JS_NewDouble'/>
<SEEALSO value='JS_NewObject'/>
<SEEALSO value='JS_NewArrayObject'/>
<SEEALSO value='JS_NewFunction'/>
<SEEALSO value='JS_NewString'/>
<SEEALSO value='JS_NewStringCopyN'/>
<SEEALSO value='JS_NewStringCopyZ'/>
<SEEALSO value='JS_InternString'/>
<SEEALSO value='JS_GetStringBytes'/>
<SEEALSO value='JS_GetStringLength'/>
</ENTRY>
<ENTRY id='JS_ReportError'>
<TYPE value='Function'/>
<SUMMARY>
Creates a formatted error message to pass to a user-defined error reporting function.
</SUMMARY>
<SYNTAX>
void JS_ReportError(JSContext *cx, const char *format, ...);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='format' type='const char *'>
Format string to convert into an error message using a standard C sprintf conversion routine.<BR/>
</PARAM>
<PARAM name='...' 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>
<SEEALSO value='JS_ReportOutOfMemory'/>
<SEEALSO value='JS_SetErrorReporter'/>
</ENTRY>
<ENTRY id='JS_ReportOutOfMemory'>
<TYPE value='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>
<SEEALSO value='JS_ReportError'/>
<SEEALSO value='JS_SetErrorReporter'/>
</ENTRY>
<ENTRY id='JS_SetErrorReporter'>
<TYPE value='Function'/>
<SUMMARY>
Specifies the error reporting mechanism for an application.
</SUMMARY>
<SYNTAX>
JSErrorReporter JS_SetErrorReporter(JSContext *cx,
JSErrorReporter er);
<PARAM name='cx' type='JSContext *'>
Pointer to a JS context from which to derive runtime information.<BR/>
</PARAM>
<PARAM name='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/>
</DESCRIPTION>
<SEEALSO value='JS_ReportError'/>
<SEEALSO value='JS_ReportOutOfMemory'/>
<SEEALSO value='JSErrorReport'/>
</ENTRY>
</API>