Determines if a specified value is a JS object.

JSVAL_IS_OBJECT(v) Use JSVAL_IS_OBJECT to determine if a given JS value, v, is a JS object or NULL. If the type tag for v is JSVAL_OBJECT, JSVAL_IS_OBJECT evaluates to true. Otherwise, it evaluates to false. These return types are C values, not JS Boolean values.

if (JSVAL_IS_OBJECT(MyItem)) { . . . }

Determines if a specified value is a JS integer or double.

JSVAL_IS_NUMBER(v) Use JSVAL_IS_NUMBER to determine if a given JS value, v, is an integer or double value. If the type tag for v is JSVAL_INT or JSVAL_DOUBLE, JSVAL_IS_NUMBER evaluates to true. Otherwise, it evaluates to false. These return types are C values, not JS Boolean values.

if (JSVAL_IS_NUMBER(MyItem)) { . . . }

Determines if a specified value is a JS integer data type.

JSVAL_IS_INT(v) Use JSVAL_IS_INT to determine if a given JS value, v, is a JS integer value. If the type tag for v is JSVAL_INT and is not JSVAL_VOID, JSVAL_IS_INT evaluates to true. Otherwise, it evaluates to false. These return types are C values, not JS Boolean values.

if (JSVAL_IS_INT(MyItem)) { . . . }

Determines if a specified JS value is a JS double data type.

JSVAL_IS_DOUBLE(v) Use JSVAL_IS_DOUBLE to determine if a given value, v, is a JS double value. If the type tag for v is JSVAL_DOUBLE, JSVAL_IS_DOUBLE evaluates to true. Otherwise, it evaluates to false. These return types are C values, not JS Boolean values.

if (JSVAL_IS_DOUBLE(MyItem)) { . . . }

Determines if a specified JS value is a JS string data type.

JSVAL_IS_STRING(v) Use JSVAL_IS_STRING to determine if a given JS value, v, is a JS string. If the type tag for v is JSVAL_STRING, JSVAL_IS_STRING evaluates to true. Otherwise, it evaluates to false. These return types are C values, not JS Boolean values.

if (JSVAL_IS_STRING(MyItem)) { . . . }

Determines if a specified value is a JS Boolean data type.

JSVAL_IS_BOOLEAN(v) Use JSVAL_IS_BOOLEAN to determine if a given value, v, is a JS Boolean value. If the type tag for v is JSVAL_BOOLEAN, JSVAL_IS_BOOLEAN evaluates to true. Otherwise, it evaluates to false. These return types are C values, not JS Boolean values.

if (JSVAL_IS_BOOLEAN(MyItem)) { . . . }

Determines if a specified JS value is null.

JSVAL_IS_NULL(v) Use JSVAL_IS_NULL to determine if a given JS value, v, contains a null value. If v is JSVAL_NULL, JSVAL_IS_NULL evaluates to true. Otherwise, it evaluates to false. These return types are C values, not JS Boolean values.

Even though v may contain a null value, its type tag is always JSVAL_OBJECT.

if (JSVAL_IS_NULL(MyItem)) { . . . }

Determines if a given JS value is a primitive type.

JSVAL_IS_PRIMITIVE(v) Use JSVAL_IS_PRIMITVE to determine if a specified jsval, v, is an instrinsic JS primitive. Primitves are values that are undefined, null, boolean, numeric, or string types. If v is one of these, JSVAL_IS_PRIMITVE returns true. If v is an object, JSVAL_IS_PRIMITIVE returns false.

Determines if a specified JS value is void.

JSVAL_IS_VOID(v) Use JSVAL_IS_VOID to determine if a given value, v, is void. If v is JSVAL_VOID, JSVAL_IS_VOID evaluates to true. Otherwise, it evaluates to false. These return types are C values, not JS Boolean values.

In JavaScript and in the ECMA language standard, the C type, void, indicates an "undefined" value.

if (JSVAL_IS_VOID(MyItem)) { . . . }

Indicates whether a JS value has a type that is subject to garbage collection.

JSVAL_IS_GCTHING(v) JSVAL_IS_GCTHING determines whether or not a specified JS value, v, 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 v is not JSVAL_INT and it is not JSVAL_BOOLEAN, JSVAL_IS_GCTHING evaluates to true. Otherwise it evaluates to false.

JSVAL_IS_GCTHING evaluates to true for JSVAL_NULL.

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.

JSVAL_TO_GCTHING(v) JSVAL_TO_GCTHING clears the type tag for a specified JS value, v, 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 v. The resulting value is cast to a void pointer.

Casts the type tag for a specified JS value and returns a pointer to the value cast as a JS object.

JSVAL_TO_OBJECT(v) JSVAL_TO_OBJECT clears a specified JS value, v, to a JS object. It does so by casting the value's type tag and casting the result to an object pointer.

Casting v to an object pointer manipulates its underlying type tag. v must be an object jsval. Casting does not convert the value stored in v to a different data type. To perform actual data type conversion, use the JS_ValueToObject function.

This macro assumes that the JS type tag for v is already JSVAL_OBJECT. Because JS values are represented as bit-shifted C integers, comparisons of JSVAL_TO_OBJECT(v) to v itself are not equal unless you ignore the C pointer type mismatch and v is an object reference.

Casts the type flag for a specified JS value and returns a pointer to the value cast as a JS double.

JSVAL_TO_DOUBLE(v) JSVAL_TO_DOUBLE casts a specified JS value, v, to a JS double. It does so by casting the value's type tag and casting the result to a double pointer.

Clearing v to a double pointer manipulates its underlying type tag. It does not convert the value stored in v to a different data type. To perform actual data conversion, use the JS_ValueToNumber function.

This macro assumes that the JS type tag for v is already JSVAL_DOUBLE. Because JS values are represented as bit-shifted C integers, comparisons of JSVAL_TO_DOUBLE(v) to v itself are not equal unless you ignore the C pointer type mismatch and v is an object reference.

Casts the type tag for a specified JS value and returns a pointer to the value cast as a JS string.

JSVAL_TO_STRING(v) JSVAL_TO_STRING casts a specified JS value, v, to a JS string. It does so by casting the value's type tag and casting the result to a string pointer.

Casting v to a string pointer manipulate its underlying type tag. It does not convert the value stored in v to a different data type. To perform actual data type conversion, use the JS_ValueToString function.

This macro assumes that the JS type tag for v is already JSVAL_STRING. Because JS values are represented as bit-shifted C integers, comparisons of JSVAL_TO_STRING(v) to v itself are not equal unless you ignore the C pointer type mismatch and v is an object reference.

Casts a specified JS object to a JS value.

OBJECT_TO_JSVAL(obj) OBJECT_TO_JSVAL casts a specified JS object, obj, to a JS value.

Casts a specified JS double to a JS value.

DOUBLE_TO_JSVAL(dp) DOUBLE_TO_JSVAL casts a specified JS double type, dp, to a JS value, jsval. First it sets the double's data type flag to JSVAL_DOUBLE and then performs the cast.

Casts a specified JS string to a JS value.

STRING_TO_JSVAL(str) STRING_TO_JSVAL casts a specified JS string type, str, to a JS value, jsval. First it sets the string's data type flag to JSVAL_STRING and then performs the cast.

Locks a JS value to prevent garbage collection on it.

JSVAL_LOCK(cx,v) JSVAL_LOCK is a deprecated feature that is supported only for backward compatibility with existing applications. To lock a value, use local roots with JS_AddRoot.

JSVAL_LOCK locks a JS value, v, to prevent the value from being garbage collected. v is a JS object, string, or double value.

JSVAL_LOCK determines if v is an object, string, or double value, and if it is, it locks the value. If locking is successful, or v already cannot be garbage collected because it is not an object, string, or double value, JSVAL_LOCK evaluates to true. Otherwise JSVAL_LOCK evaluates to false.

Unlocks a JS value, enabling garbage collection on it.

JSVAL_UNLOCK(cx,v) JSVAL_UNLOCK is a deprecated feature that is supported only for backward compatibility with existing applications. To unlock a value, use local roots with JS_RemoveRoot.

JSVAL_UNLOCK unlocks a previously locked JS value, v, so it can be garbage collected. v is a JS object, string, or double value.

JSVAL_UNLOCK determine if v is an object, string, or double value, and if it is, it unlocks the value. If unlocking is successful, or v is not affected by garbage collection because it is not an object, string, or double value, JSVAL_UNLOCK evaluates to true. Otherwise JSVAL_UNLOCK evaluates to false.

Determines if a specified value is a valid JS integer.

INT_FITS_IN_JSVAL(i) Determines if a specified C integer value, i, lies within the minimum and maximum ranges allowed for a jsval integer. If the value is within range, it can become a valid JS integer, and INT_FITS_IN_JSVAL is true. Otherwise INT_FITS_IN_JSVAL is false.

if (INT_FITS_IN_JSVAL(MyItem)) { . . . } else JS_ReportError(MyContext, "Integer out of range: %s", MyItem);

Converts a JS integer value to an integer.

JSVAL_TO_INT(v) JSVAL_TO_INT converts a specified JS integer value, v, to a C integer value by performing a bitwise right shift operation. JSVAL_TO_INT assumes that it was passed a JS value of type JSVAL_INT, and returns that JS value's corresponding C integer value. Note that because of the bit-shifting operation, that a C comparison of JSVAL_TO_INT(v) to v always results in nonequality.

Converts a specified integer value to a JS integer value.

INT_TO_JSVAL(i) INT_TO_JSVAL converts a C integer, i, to a JS integer value type using a bitwise left shift operation and OR'ing the result with the JSVAL_INT macro.

Converts a JS value to a C true or false value.

JSVAL_TO_BOOLEAN(v) JSVAL_TO_BOOLEAN converts a specified JS value, v, to a C true or false value by performing a bitwise right shift operation. JSVAL_TO_BOOLEAN assumes that it was passed a JS value of type JSVAL_BOOLEAN, and returns that JS value's corresponding C integer value.

Converts a specified C true or false value to a JS value.

BOOLEAN_TO_JSVAL(b) BOOLEAN_TO_JSVAL converts a C true or false value, b, to a JS Boolean value type using a bitwise left shift operation and setting the data type flag to JSVAL_BOOLEAN.

Casts a JS value to a private data pointer.

JSVAL_TO_PRIVATE(v) JSVAL_TO_PRIVATE casts a JS value, v, to a void pointer to private data. Private data is associated with an JS class on which the JSCLASS_HAS_PRIVATE attribute is set. Private data is user-allocated, defined, and maintained. Private pointers must be word aligned.

JSVAL_TO_PRIVATE returns an integer pointer cast as a void pointer.

Casts a private data pointer to a JS integer value.

PRIVATE_TO_JSVAL(p) PRIVATE_TO_JSVAL enables you to store a private data pointer, p, as a JS value. The private pointer must be word-aligned. Before passing a pointer to PRIVATE_TO_JSVAL, test it with INT_FITS_IN_JSVAL to be verify that the pointer can be cast to a legal JS integer value.

PRIVATE_TO_JSVAL casts a pointer to a JS integer value and sets the JSVAL_INT type tag on it.

Public.Flag that indicates a property is visible to for and in loops.

JSPROP_ENUMERATE JSPROP_ENUMERATE is a flag value that indicates a property belonging to a JS object is visible to for and in loops. JSPROP_ENUMERATE is used to set or clear the flags field in a JSPropertySpec structure so that a property can be made visible or invisible to loops.

Property flags cannot be changed at run time. Instead, you either pass a set of flags as an argument to JS_DefineProperty to create a single property with fixed flag values, or you set property flags in a JSPropertySpec struct which is then passed to the JS_DefineProperties function to create multiple properties on a single object.

JSPropertySpec MyProperty; . . . MyProperty.flags = MyProperty.flags | JSPROP_ENUMERATE;

Flag that indicates a property is read only.

JSPROP_READONLY 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 JSPROP_READONLY 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 flags fields to determine if a property is read only.

Flag that indicates a property is permanent and cannot be deleted.

JSPROP_PERMANENT 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 flags fields to determine if a property is permanent.

Flag that indicates a property is exported from a JS object.

JSPROP_EXPORTED JSPROP_EXPORTED is a flag value that indicates that a property can be imported by other scripts or objects, typically to borrow security privileges.

Flag that indicates a property's name is actually an index number into an array.

JSPROP_INDEX 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).

Flag that indicates a function nominally associated with an object is bound, instead, to that object's parent.

JSFUN_BOUND_METHOD This macro is deprecated. JSFUN_BOUND_METHOD is a flag that indicates a method associated with an object is bound to the object's parent. This macro is no longer needed because the JS engine now supports closures.

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.

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.

JSFUN_GLOBAL_PARENT This macro is deprecated. Instead of using it, use JS_CloneFunctionObject. JSFUN_GLOBAL_PARENT 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.

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.

Defines a void JS value.

JSVAL_VOID JSVAL_VOID defines a void JS value. Currently this value is defined as 0-JSVAL_INT_POW2(30).

Defines a null JS value.

JSVAL_NULL JSVAL_NULL defines a null JS value. Currently this value is defined as OBJECT_TO_JSVAL(0).

Defines a JS value of 0.

JSVAL_ZERO JSVAL_ZERO defines a JS value of 0. Currently this value is defined as INT_TO_JSVAL(0).

Defines a JS value of 1.

JSVAL_ONE JSVAL_ZERO defines a JS value of 1. Currently this value is defined as INT_TO_JSVAL(1).

Defines a false JS Boolean value.

JSVAL_FALSE JSVAL_FALSE defines a false JS Boolean value. Currently this value is defined as BOOLEAN_TO_JSVAL(JS_FALSE).

Do not compare JSVAL_FALSE with JS_FALSE in logical operations. These values are not equal.

Defines a true JS Boolean value.

JSVAL_TRUE JSVAL_TRUE defines a true JS Boolean value. Currently this value is defined as BOOLEAN_TO_JSVAL(JS_TRUE).

Do not compare JSVAL_TRUE with JS_TRUE in logical operations. These values are not equal.

Flag that indicates a class instance has a private data slot.

JSCLASS_HAS_PRIVATE JSCLASS_HAS_PRIVATE can be specified in the flags field of a JSClass struct to indicate that a class instance has a private data slot. Set this flag if class instances should be allowed to use the JS_GetPrivate and JS_SetPrivate functions to store and retrieve private data.

Flag that indicates that the JSNewEnumerateOp method is defined for a class.

JSCLASS_NEW_EUMERATE JSCLASS_NEW_ENUMERATE can be specified in the flags field of a JSClass struct to indicate that a class instance defines the JSNewEnumerateOp method. This method is used for property enumerations when a class defines the getObjectOps field.

Flag that indicates that the JSNewResolveOp method is defined for a class.

JSCLASS_NEW_RESOLVE JSCLASS_NEW_RESOLVE can be specified inthe flags field of a JSClass struct to indicate that a class instance defines the JSNewResolveOp method. This method is used for property resolutions when a class defines the getObjectOps field.

Increments the reference count for a specified JSPrincipals struct.

JSPRINCIPALS_HOLD(cx, principals) JSPRINCIPALS_HOLD maintains the specified principals in a JSPrincipals struct, principals, for a specified JSContext, cx. Principals are used by the JS security mechanism. The hold is maintained by incrementing the reference count field in the struct by 1.

JSPrincipals MyPrincipals; JSContext * MyContext; JSRuntime *rt; . . . rt = Js_Init(32768); MyContext = JS_NewContext(rt, 16384); . . . JSPRINCIPALS_HOLD(MyContext, MyPrincipals);

Decrements the reference count for a specified JSPrincipals struct, and destroys the principals if the reference count is 0.

JSPRINCIPALS_DROP(cx, principals) JSPRINCIPALS_DROP decrements the specified principals in a JSPrincipals struct, principals, for a specified JSContext, cx. The principals are dropped by deccrementing the reference count field in the struct by 1. If the reference count drops to zero, then JSPRINCIPALS_DROP also destroys the principals.

JSPrincipals MyPrincipals; JSContext * MyContext; JSRuntime *rt; . . . rt = Js_Init(32768); MyContext = JS_NewContext(rt, 16384); . . . JSPRINCIPALS_HOLD(MyContext, MyPrincipals); . . . JSPRINCIPALS_DROP(MyContext, MyPrincipals);

Initializes the JavaScript runtime.

JS_NewRuntime(maxbytes); JS_NewRuntime initializes the JavaScript runtime environment. Call JS_NewRuntime before making any other API calls. JS_NewRuntime allocates memory for the JSRuntime, and initializes certain internal runtime structures. maxbytes specifies the number of allocated bytes after which garbage collection is run.

Generally speaking, most applications need only one JSRuntime. 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.

If JS_NewRuntime is successful, it returns a pointer to the runtime. Otherwise it returns NULL.

Frees the JavaScript runtime.

JS_DestroyRuntime(rt); JS_DestroyRuntime frees the specified the JavaScript runtime environment, rt. Call JS_DestroyRuntime after completing all other JS API calls. JS_DestroyRuntime garbage collects and frees the memory previously allocated by JS_NewRuntime.

Flag that specifies that a function's identify can be uniquely resolved without examining the function prototype chain.

JSRESOLVE_QUALIFIED JSRESOLVE_QUALIFIED is flag that, if included in a function's flags field, indicates that its identify can be uniquely resolved without reference to its full prototype chain.

Flag that specifies that a function's identify can be uniquely resolved by examining the left side of an assignment statement.

JSRESOLVE_ASSIGNING JSRESOLVE_ASSIGNING 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.

Defines a base class for use in building and maintaining JS objects.

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]; }; Class name
Class attributes. 0 indicates no attributes are set. Attributes can be one or both of the following values OR'd together:
JSCLASS_HAS_PRIVATE: class can use private data.
JSCLASS_NEW_ENUMERATE: class defines getObjectOps to point to a new method for enumerating properties.
JSCLASS_NEW_RESOLVE: class defines getObjectOps to point to a new method for property resolution.
Method for adding a property to the class.
Method for deleting a property from the class.
Method for getting a property value.
Method for setting a property value.
Method for enumerating over class properties.
Method for resolving property ambiguities.
Method for converting property values.
Method for finalizing the class.
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 getObjectOps to NULL.
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 NULL.
Pointer to the method for calling into the object that represents this class.
Pointer to the constructor for the object that represents this class
Pointer to an optional XDR object and its methods. If you do not use XDR, set this value to NULL.
Pointer to an optional hasInstance method for this object. If you do not provide a method for hasInstance, set this pointer to NULL.
Reserved for future use.
Use JSClass to define a base class used in object creation and manipulation. In your applications, you may use JSClass to declare a constructor function, base properties, methods, and attributes common to a series of objects you create.

By default, JSClass 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 getObjectOps to point to an optional JSObjectOps struct that contains pointers to an array of methods that override the default access methods. For more information about creating method overrides, see JSObjectOps.

Defines pointers to custom override methods for a class.

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]; }; 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 NULL.
Pointer to the function that destroys the object map when it is no longer needed. This pointer cannnot be NULL.
Pointer to a custom property lookup method for the object. This pointer cannnot be NULL.
Pointer to a custom property creation method for the object. This pointer cannnot be NULL.
Pointer to a custom property value retrieval method for the object. This pointer cannnot be NULL.
Pointer to a custom property value assignment method for the object. This pointer cannnot be NULL.
Pointer to a custom property attributes retrieval method for the object. This pointer cannot be NULL.
Pointer to a custom property attributes assignment method for this object. This property cannot be NULL.
Pointer to a custom method for deleting a property belonging to this object. This pointer cannot be NULL.
Pointer to a method for converting a property value. This pointer cannot be NULL.
Pointer to a custom method for enumerating over class properties. This pointer cannot be NULL.
Pointer to an optional custom access control method for a this object. This pointer cannot be NULL.
Pointer to an optional custom method that retrieves this object. If you do not use this method, set thisObject to NULL.
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 dropProperty to NULL.
Pointer to the method for calling into the object that represents this class.
Pointer to the constructor for the object that represents this class
Pointer to an optional XDR object and its methods. If you do not use XDR, set this value to NULL.
Pointer to an optional hasInstance method for this object. If you do not provide an override method for hasInstance, set this pointer to NULL.
Reserved for future use.
Use JSObjectOps to define an optional structure of pointers to custom property methods for a class. If you define JSObjectOps, you can create methods to override the default methods used by JSClass.

If you create a JSObjectOps 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 NULL.

Defines a single property for an object.

struct JSPropertySpec { const char *name; int8 tinyid; uint8 flags; JSPropertyOp getter; JSPropertyOp setter; }; Name to assign to the property.
Unique ID number for the property to aid in resolving getProperty and setProperty method calls.
Property attributes. If 0, no flags are set. Otherwise, the following attributes can be used singly or OR'd together:
JSPROP_ENUMERATE: property is visible in for loops.
JSPROP_READONLY: property is read-only.
JSPROP_PERMANENT: property cannot be deleted.
JSPROP_EXPORTED: property can be exported outside its object.
JSPROP_INDEX: property is actual an array element.
getProperty method for the property.
setProperty method for the property. Read-only properties should not have a setProperty method.
JSPropertySpec defines the attributes for a single JS property to associate with an object. Generally, you populate an array of JSPropertySpec to define all the properties for an object, and then call JS_DefineProperties to create the properties and assign them to an object.

Defines a single function for an object.

struct JSFunctionSpec { const char *name; JSNative call; uint8 nargs; uint8 flags; uint16 extra; }; Name to assign to the function.
The built-in JS call wrapped by this function. If the function does not wrap a native JS call, set this value to NULL.
Number of arguments to pass to this function.
Function attributes. If set to 0 the function has no attributes. Otherwise, existing applications can set flags to either or both of the following attributes OR'd:
JSFUN_BOUND_METHOD
JSFUN_GLOBAL_PARENT
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.
Reserved for future use.
JSFuctionSpec defines the attributes for a single JS function to associate with an object. Generally, you populate an array of JSFunctionSpec to define all the functions for an object, and then call JS_DefineFunctions to create the functions and assign them to an object.

JSFunctionSpec 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 const char*, initialize the name field with it, and specify the JSPROP_INDEX attribute in flags.

Describes a double value and assigns it a name.

struct JSConstDoubleSpec { jsdouble dval; const char *name; uint8 flags; uint8 spare[3]; }; Value for the double.
Name to assign the double.
Attributes for the double. Currently these can be 0 or more of the following values OR'd:
JSPROP_ENUMERATE: property is visible in for loops.
JSPROP_READONLY: property is read-only.
JSPROP_PERMANENT: property cannot be deleted.
JSPROP_EXPORTED: property can be exported outside its object.
JSPROP_INDEX: property is actually an array element.
Reserved for future use.
JSConstDoubleSpecs is typically used to define a set of double values that are assigned as properties to an object using JS_DefineConstDoubles. JS_DefineConstDoubles creates one or more double properties for a specified object.

JS_DefineConstDoubles takes an argument that is a pointer to an array of JSConstDoubleSpecs. Each array element defines a single property name and property value to create. The last element of the array must contain zero-valued values. JS_DefineConstDoubles creates one property for each non-zero element in the array.

Defines security information for an object or script.

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; Pointer to the codebase for the principal.
Pointer to the function that returns an array of principal definitions.
Flag indicating whether principals are enabled globally.
Reference count for the principals. Each reference to a principal increments refcount by one. As principals references are dropped, call the destroy method to decrement the reference count and free the principals if they are no longer needed.
Pointer to the function that decrements the reference count and possibly frees the principals if they are no longer in use.
JSPrincipals 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 JSPrincipals 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 JS_CompileScriptForPrincipals, JS_CompileFunctionForPrincipals, and JS_EvaluateScriptForPrincipals.

codebase points to the common codebase for this object or script. Only objects and scripts that share a common codebase can interact.

getPrincipalArray is a pointer to the function that retrieves the principals for this object or script.

globalPrivilegesEnabled is a flag that indicates whether principals are enabled globally.

refcount is used to maintain active principals. Each time an object is referenced, refcount must be increased by one. Each time an object is dereferenced, refcount must be decremented by one. When refcount is zero, the principals are no longer in use and are destroyed. Use the JSPRINCIPALS_HOLD macro to increment refcount, and use JS_PRINCIPALS_DROP to decrement refcount.

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.

struct JSErrorReport { const char *filename; uintN lineno; const char *linebuf; const char *tokenptr; const jschar *uclinebuf; const jschar *uctokenptr; }; Indicates the source file or URL that produced the error condition. If NULL, the error is local to the script in the current HTML page.
Line number in the source that caused the error.
Text of the line that caused the error, minus the trailing newline character.
Pointer to the error token in *linebuf.
Unicode line buffer. This is the buffer that contains the original data.
Pointer to the error token in *uclinebuf.
JSErrorReport describes a single error that occurs in the execution of script.

In the event of an error, filename will either contain the name of the external source file or URL containing the script (SCRIPT SRC=) or NULL, indicating that a script embedded in the current HTML page caused the error.

lineno indicates the line number of the script containing the error. In the case of an error in a script embedded in the HTML page, lineno indicates the HTML lineno where the script error is located.

linebuf is a pointer to a user-defined buffer into which JS copies the offending line of the script.

tokenptr is a pointer into linebuf that identifies the precise location line of the problem within the offending line.

uclinebuf is a pointer to a user-defined buffer into which JS copies the Unicode (original) version of the offending line of script.

uctokenptr is a pointer into uclinebuf that identifies the precise location line of the problem within the offending Unicode (original) version of the offending line.

To use JSErrorReport, your application must define a variable of type JSErrorReport and allocate a buffer to hold the text that generated the error condition. Set linebuf 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 uclinebuf and uctokenptr to NULL.

Internal use only. Describes an array of property IDs to associated with an object.

struct JSIdArray { jsint length; jsid vector[1]; }; JSIdArray is used internally by the JS engine to hold IDs for enumerated properties associated with an object.

Internal use only. Describes a single ID value for a JS property.

struct JSProperty { jsid id; }; JSProperty is used by the JS engine to hold a unique ID to a property belonging to an object.

Retrieves the numeric representation for not-a-number (NaN).

jsval JS_GetNaNValue(JSContext *cx); JS_GetNanValue retrieves a numeric representation of NaN given a specific JS context, cx. JS_GetNaNValue returns a JS value that corresponds to the IEEE floating point quiet NaN value.

NaN is typically used in JavaScript to represent numbers that fall outside the valid range for integer or double values. NaN 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.

Comparing NaN to any other numeric value or to itself always results in an unequal comparison.

Retrieves the negative infinity representation.

jsval JS_GetNegativeInfinityValue(JSContext *cx); JS_GetNegativeInfinityValue retrieves a numeric representation of negative-infinity, given a specific JS context, cx. JS_GetNegativeInfinityValue returns a JS value.

Negative infinity is typically used in JavaScript to represent numbers that are smaller than the minimum valid integer or double value.

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.

Retrieves the numeric representation of infinity.

jsval JS_GetPositiveInfinityValue(JSContext *cx); JS_GetPositiveInfinityValue retrieves the numeric representation of infinity. JS_GetPositiveInfinityValue returns a JS value.

The infinity representation is typically used in JavaScript to represent numbers that are larger than the maximum valid integer or double value.

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.

Retrieves the representation of an empty string.

jsval JS_GetEmptyStringValue(JSContext *cx); JS_GetEmptyStringValue retrieves the empty string value.

Converts a series of JS values, passed in an argument array, to their corresponding JS types.

JSBool JS_ConvertArguments(JSContext *cx, uintN argc, jsval *argv, const char *format, ...); Pointer to a JS context from which to derive runtime information.
The number of arguments to convert.
Pointer to the vector of arguments to convert.
Character array containing the recognized format to which to convert
A variable number of pointers into which to store the converted types. There should be one pointer for each converted value.
JS_ConvertArguments 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 if...else statements in your function code to retrieve and translate multiple JS values for use with your own functions.

cx is the context for the call. argc indicates the number of JS values you are passing in for conversion. argv is a pointer to the array of JS values to convert.

format is a sequential character array, where each element of the array indicates the JS type into which to convert the next available JS value. format can contain one or more instances of the following characters, as appropriate: Character Corresponding JS type to which to convert the value

b

JSBool

c

uint16 (16-bit, unsigned integer)

i

int32 (32-bit, ECMA-compliant signed integer)

u

uint32 (32-bit, ECMA-compliant, unsigned integer)

j

int32 (32-bit, signed integer)

d

jsdouble

jsdouble (converted to an integer value)

JSString (treated as an array of characters)

JSString

JSObject

JSFunction

None. If an asterisk (*) is present in format, it tells the conversion routine to skip converting the current argument.

None. If a slash (/) is present in format, it tells the conversion routine to turn off checking that the argument vector was passed to JS_ConvertArguments from a valid native JS function.

]]>

For example, if format is "bIfb", then JS_ConvertArguments converts the first JS value in argv into a JSBool, the second value into a jsdouble, the third value into a JSObject, and the last value into a JSBool.

To skip a given argument, pass an asterisk in the corresponding position in format.

JS_ConvertArguments 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 JS_ConvertArguments, 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, JS_ConvertArguments 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.

When you call JS_ConvertArguments, the arguments you pass in after format must be a series of pointers to storage. You must allocate one storage pointer for each converted value you expect.

If JS_ConvertArgument successfully converts all arguments, it returns JS_TRUE. Otherwise it returns JS_FALSE.

Converts a JS value to a value of a specific JS type.

JSBool JS_ConvertValue(JSContext *cx, jsval v, JSType type, jsval *vp); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
The type to which to convert the value. type must be one of JSTYPE_VOID, JSTYPE_OBJECT, JSTYPE_FUNCTION, JSTYPE_STRING, JSTYPE_NUMBER, or JSTYPE_BOOLEAN. Otherwise JS_ConvertValue reports an error.
Pointer to the JS value that contains the converted value when the function returns.
JS_ConvertValue converts a specified JS value, v, to a specified JS type, type. The converted value is stored in the jsval pointed to by vp. Typically users of this function set vp to point to v, so that if conversion is successful, v now contains the converted value.

JS_ConvertValue calls other, type-specific conversion routines based on what you specify in type. These include JS_ValueToFunction, JS_ValueToString, JS_ValueToNumber, and JS_ValueToBoolean.

Converting any JS value to JSTYPE_VOID always succeeds.

Converting to JSTYPE_OBJECT is successful if the JS value to convert is one of JSVAL_INT, JSVAL_DOUBLE, JSVAL_STRING, JSVAL_BOOLEAN, or JSVAL_OBJECT.

Converting to JSTYPE_FUNCTION 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.

Converting any JS value to JSTYPE_STRING always succeeds.

Converting a JS value to JSTYPE_NUMBER succeeds if the JS value to convert is a JSVAL_INT, JSVAL_DOUBLE, or JSVAL_BOOLEAN. If the JS value is a JSVAL_STRING that contains numeric values and signs only, conversion also succeeds. If the JS value is a JSVAL_OBJECT, conversion is successful if the object supports its own conversion function.

Converting any JS value to JSTYPE_BOOLEAN always succeeds, except when the JS value is a JSVAL_OBJECT that does not support its own conversion routine.

If the conversion is successful, JS_ConvertValue returns JS_TRUE, and vp points to the converted value. Otherwise, it returns JS_FALSE, and vp is either undefined, or points to the current value of v, depending on how you implement your code.

Converting a JS value from one type to another does not change the actual data value stored in the item.

Converts a JS value to a JS object.

JSBool JS_ValueToObject(JSContext *cx, jsval v, JSObject **objp); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
Pointer to the JS object into which to store the converted value.
JS_ValueToObject converts a specified JS value, v, to a JS object. The converted object is stored in the object pointed to by objp. If the conversion is successful, JS_ValueToObject returns JS_TRUE. Otherwise it returns JS_FALSE.

You can successfully convert a JS value to an object if the JS value to convert is one of JSVAL_INT, JSVAL_DOUBLE, JSVAL_STRING, JSVAL_BOOLEAN, or JSVAL_OBJECT. Note that if v is already an object, the object returned in objp represents a converted version of v, rather than original version of v.

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 JS_AddRoot function.

Converts a JS value to a JS function.

JSFunction * JS_ValueToFunction(JSContext *cx, jsval v); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
JS_ValueToFunction converts a specified JS value, v, to a JS function. The actual conversion is performed by the object's convert operation. JS_ValueToFunction returns a pointer to the converted function.

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, JS_ValueToFunction returns NULL.

Converts a JS value to a JS string.

JSString * JS_ValueToString(JSContext *cx, jsval v); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
JS_ValueToString converts a specified JS value, v, to a JS string. The actual conversion is performed by the object's convert operation. JS_ValueToString always returns a pointer to a string. The original value is untouched.

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 JS_AddRoot function.

Converts a JS value to a JS double.

JSBool JS_ValueToNumber(JSContext *cx, jsval v, jsdouble *dp); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
Pointer to the JS value that contains the converted double when the function returns.
JS_ValueToNumber converts a specified JS value, v, to a JS double. The converted value is stored in the jsdouble pointed to by dp.

You can convert a JS value to a number if the JS value to convert is a JSVAL_INT, JSVAL_DOUBLE, or JSVAL_BOOLEAN. If the JS value is a JSVAL_STRING that contains numeric values and signs only, conversion also succeeds. If the JS value is a JSVAL_OBJECT, conversion is successful if the object's convert operation returns a primitive value that can be converted.

When conversion is successful, JS_ValueToNumber returns JS_TRUE. Otherwise, it reports an error and returns JS_FALSE.

Converts a JS value to a JS 32-bit integer.

JSBool JS_ValueToInt32(JSContext *cx, jsval v, int32 *ip); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
Pointer to the JS value that contains the converted integer when the function returns.
JS_ValueToInt32 converts a specified JS value, v, to a JS double, and then to a 32-bit integer, if it fits. If the double is out of range, JS_ValueToInt32 reports an error and conversion fails. The double rounded to the nearest integer value.

The actual conversion is performed by the object's convert operation. The converted value is stored in the int32 pointed to by ip.

You can convert a JS value to an integer if the JS value to convert is a JSVAL_INT, JSVAL_DOUBLE, or JSVAL_BOOLEAN. If the JS value is a JSVAL_STRING that contains numeric values and signs only, conversion also succeeds. If the JS value is a JSVAL_OBJECT, conversion is successful if the object's convert operation returns a primitive value that can be converted.

If the conversion is successful, JS_ValueToInt32 returns JS_TRUE. Otherwise, it reports an error and returns JS_FALSE.

Converts a JS value to an ECMA-compliant 32-bit integer.

JSBool JS_ValueToECMAInt32(JSContext *cx, jsval v, int32 *ip); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
Pointer to the JS value that contains the converted integer when the function returns.
JS_ValueToECMAInt32 converts a JS value, v, 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.

You can convert a JS value to an integer if the JS value to convert is a JSVAL_INT, JSVAL_DOUBLE, or JSVAL_BOOLEAN. If the JS value is a JSVAL_STRING that contains a well formed numeric literal (ignoring leading and trailing whitespace) conversion also succeeds. If the JS value is a JSVAL_OBJECT, conversion is successful if the object's convert operation returns a primitive value that can be converted.

If the conversion is successful, JS_ValueToECMAInt32 returns JS_TRUE. Otherwise, it reports an error and returns JS_FALSE.

Converts a JS value to an ECMA-compliant, unisgned 32-bit integer.

JSBool JS_ValueToECMAUint32(JSContext *cx, jsval v, uint32 *ip); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
Pointer to the JS value that contains the converted integer when the function returns.
JS_ValueToECMAUint32 converts a JS value, v, 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 conversion is successful, JS_ValueToECMAInt32 returns JS_TRUE, and ip contains a pointer to the converted value. Otherwise, it reports an error and returns JS_FALSE.

Converts a JS value to an unsigned, 16-bit integer.

JSBool JS_ValueToUint16(JSContext *cx, jsval v, uint16 *ip); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
Pointer to the JS value that contains the converted integer when the function returns.
JS_ValueToUint16 converts a specified JS value, v, 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, JS_ValueToUint16 reports an error and conversion fails. The converted value is stored in the uint16 pointed to by ip.

If the conversion is successful, JS_ValueToInt32 returns JS_TRUE. Otherwise, it reports an error and returns JS_FALSE.

Converts a JS value to a JS Boolean.

JSBool JS_ValueToBoolean(JSContext *cx, jsval v, JSBool *bp); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
Pointer to the JS value that contains the converted Boolean when the function returns.
JS_ValueToBoolean converts a specified JS value, v, 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 JSVAL_OBJECT that does not support its own conversion routine.

The converted value is stored in the JSBool pointed to by bp. If the conversion is successful, JS_ValueToBoolean returns JS_TRUE. If the value to convert is an empty string, or conversion is unsuccesful, JS_ValueToBoolean returns JS_FALSE.

Converts a JS value to a JS ID.

JSBool JS_ValueToId(JSContext *cx, jsval v, jsid *idp); Pointer to a JS context from which to derive runtime information.
The JS value to convert.
Pointer to the JS ID that contains the converted value when the function returns.
JS_ValueToId converts a specified JS value, v, to a JS ID. If v already contains a JS_INT value, idp is set to point at v. Otherwise, JS_ValueToId attempts to generate an ID value based on the current value of v.

The converted value is stored in the jsid pointed to by idp. If the conversion is successful, JS_ValueToId returns JS_TRUE. Otherwise, it returns JS_FALSE.

Converts a JS ID to a JS value.

JSBool JS_IdToValue(JSContext *cx, jsval v, JSBool *bp); Pointer to a JS context from which to derive runtime information.
The JS ID to convert.
Pointer to the JS value that contains the converted ID when the function returns.
JS_IdToValue converts a specified JS ID, id, to a JS value. The converted value is stored in the jsval pointed to by vp. If the conversion is successful, JS_IdToValue returns JS_TRUE. Otherwise, it returns JS_FALSE.

Determines the JS data type of a JS value.

JSType JS_TypeOfValue(JSContext *cx, jsval v); Pointer to a JS context from which to derive runtime information.
The JS value to examine.
JS_TypeOfValue examines a specified JS value, v, and returns its JS data type. The return value is always one of JSTYPE_VOID, JSTYPE_OBJECT, JSTYPE_FUNCTION, JSTYPE_STRING, JSTYPE_NUMBER, or JSTYPE_BOOLEAN.

Function. Returns a pointer to the string literal description of a specified JS data type.

const char * JS_GetTypeName(JSContext *cx, JSType type); Pointer to a JS context from which to derive runtime information.
The JS value to examine. type is one of JSTYPE_VOID, JSTYPE_OBJECT, JSTYPE_FUNCTION, JSTYPE_STRING, JSTYPE_NUMBER, or JSTYPE_BOOLEAN.
JS_GetTypeName returns a pointer to a string literal description of a specified JS data type, type. The following table lists JSTypes and the string literals reported by JS_GetTypeName: Type Literal

JSTYPE_VOID

"undefined"

JSTYPE_OBJECT

"object"

JSTYPE_FUNCTION

"function"

JSTYPE_STRING

"string"

JSTYPE_NUMBER

"number"

JSTYPE_BOOLEAN

"boolean"

Any other value

NULL

]]>

Deprecated. Initializes the JavaScript runtime.

JSRuntime * JS_Init(uint32 maxbytes); JS_Init is a deprecated function that initializes the JavaScript runtime environment. Use JS_NewRuntime instead of this function.

Deprecated. Frees the JavaScript runtime.

void JS_Finish(JSRuntime *rt); JS_Finish is a deprecated function that frees the specified the JavaScript runtime environment, rt. Use JS_DestroyRuntime instead of this function.

Locks the JS run-time environment.

void JS_Lock(JSRuntime *rt); JS_Lock is an empty, API hook function for developers so that they provide an exclusive locking mechanism for the JSRuntime on a specific platform or for a specific application. Developers must create their own locking function that takes a single argument, rt, the JS run-time environment to lock. Locking the runtime protects critical sections in a threaded environment. After performing one or more exclusive lock operations, the runtime should be unlocked with a call to JS_Unlock.

Unlocks a previously locked JS run-time environment.

void JS_Unlock(JSRuntime *rt); Pointer to a previously established JS run-time environment with which to associate this context.
JS_Unlock is an empty, API hook function for developers so that they can provide a mechanism for unlocking the JS run-time environment after having previously locked it with a call to JS_Lock. Developers must create their own unlocking function that takes a single argument, rt, the JS run-time environment to unlock. JS_Unlock must undo the actions taken by the developer's implementation of JS_Lock.

Associate a context with the current thread. No other thread should use the context while the association lasts.

intN JS_SetContextThread(JSContext *cx); Pointer to a previously established JS context. JS_SetContextThread ties cx to the current thread for exclusive use. No other thread should attempt to use cx until this association is removed. Use JS_ClearContextThread to break the tie.

JS_SetContextThread returns the thread ID of the last thread to be associated with this context. JS_NewContext performs a JS_SetContextThread implicitly. JS_SetContextThread is available only if the engine is built with JS_THREADSAFE.

Removes the association between a context and the current thread.

intN JS_ClearContextThread(JSContext *cx); Pointer to a previously established JS context. JS_ClearContextThread clears any tie cx had with a thread. The context should not be used until it as associated with another thread via JS_SetContextThread.

JS_ClearContextThread returns the thread ID of the last thread to be associated with this context. JS_ClearContextThread is available only if the engine is built with JS_THREADSAFE.

Returns the ID of the associated thread for a context.

intN JS_GetContextThread(JSContext *cx); Pointer to a previously established JS context.
JS_GetContextThread returns the ID of the thread currently associated with this context. JS_GetContextThread is available only if the engine is built with JS_THREADSAFE.

Creates a new JavaScript context.

JSContext * JS_NewContext(JSRuntime *rt, size_t stacksize); Pointer to a previously established JS run-time environment with which to associate this context.
The size, in bytes, of the execution stack space to allocate for the context.
JS_NewContext 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 JSRuntime, rt. 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.

Generally you use JS_NewContext to generate a context for each separate script in a HTML page or frame.

Once established, a context can be used any number of times for different scripts or threads so long as it's associated via JS_SetContextThread with only one thread at a time.

If a call to JS_NewContext is successful, it returns a pointer to the new context. Otherwise it returns NULL.

Frees a specified JSContext.

void JS_DestroyContext(JSContext *cx); JS_DestroyContext frees the stack space allocated to a previously created JS context, cx.

Retrieves a pointer to the JSRuntime.

JSRuntime *) JS_GetRuntime(JSContext *cx); JS_GetRuntime retrieves a pointer to the JSRuntime with which a specified JSContext, cx, is associated. All contexts are associated with a particular JSRuntime when they are first created; JS_GetRuntime provides a convenient, programmatic way to look up the association.

Cycles through the JS contexts associated with a particular JSRuntime.

JSContext * JS_ContextIterator(JSRuntime *rt, JSContext **iterp); Pointer to a previously established JS run-time environment with which script contexts to iterate through are associated.
Pointer to a JS context pointer that holds current context when JS_ContextIterator is called, and that on return holds the next context to call with a subsequent call to the iterator.
JS_ContextIterator enables you to cycle through all the executable script contexts associated with a specified JS run-time environment, rt. Each call to JS_ContextIterator cycles from the current context to the previous context.

The first time you call JS_ContextIterator, iterp 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 iterp 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 iterp 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 JS_ContextIterator returns NULL. Otherwise JS_ContextIterator points iterp to the previous context pointer in the context chain, and returns that pointer.

In effect, by making repeated calls to JS_ContextIterator you can cycle through all executable script contexts for a given runtime, and perform common operations on each them.

JSContext **cxArray, *acx; JSContext *iterp = NULL; int i;i = 0; while ((acx = JSContextIterator(rt, &iterp)) != NULL) { printf("%d ". ++1); }

Retrieves the JavaScript version number used within a specified executable script context.

JSVersion JS_GetVersion(JSContext *cx); JS_GetVersion reports an encapsulated JavaScript version number used within a specified JSContext, cx. The version number is an enumerated value that corresponds to the JavaScript version string with which JS users are familiar.

The following table lists possible values reported by JS_GetVersion, the enumerated value you can use for the JS version in your code, and provides a translation to the actual JavaScript version string: Value Enumeration Meaning

100

JSVERSION_1_0

JavaScript 1.0

110

JSVERSION_1_1

JavaScript 1.1

120

JSVERSION_1_2

JavaScript 1.2

130

JSVERSION_1_3

JavaScript 1.3

0

JSVERSION_DEFAULT

Default JavaScript version

-1

JSVERSION_UNKNOWN

Unknown JavaScript version

]]>

If JSVERSION_DEFAULT is returned by JS_GetVersion, 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, JS_GetVersion still returns JSVERSION_DEFAULT.

Specifies the version of JavaScript used by a specified executable script context.

JSVersion JS_SetVersion(JSContext *cx, JSVersion version); JS_SetVersion attempts to set the version of JavaScript to version for a specified executable script context, cx. version must be one of the following values: Enumeration Meaning

JSVERSION_1_0

JavaScript 1.0

JSVERSION_1_1

JavaScript 1.1

JSVERSION_1_2

JavaScript 1.2

JSVERSION_1_3

JavaScript 1.3

]]>

JS_SetVersion returns the JS version in effect for the context before you changed it.

Indicates the version number of the JS engine.

const char * JS_GetImplementationVersion; JS_GetImplementationVersion returns a hard-coded, English language string that specifies the version number of the JS engine currently in use, and its release date.

Retrieves a pointer to the global JS object for an executable script context.

JSObject * JS_GetGlobalObject(JSContext *cx); JS_GetGlobalObject enables you to retrieve a pointer to the global JS object for a specified JSContext, cx.

Specifies the global object for an executable script context.

void JS_SetGlobalObject(JSContext *cx, JSObject *obj); Pointer to the executable script context for which to set the global object.
Pointer to the JS object to set as the global object.
JS_SetGlobalObject sets the global object to obj for a specified executable script context, cx. Ordinarily you set a context's global object when you call JS_InitStandardClasses to set up the general JS function and object classes for use by scripts.

Initializes general JS function and object classes, and the built-in object classes used in most scripts.

JSBool JS_InitStandardClasses(JSContext *cx, JSObject *obj); Pointer to the executable script context for which to initialize JS function and object classes.
Pointer to a JS object to set as the global object.
JS_InitStandardClasses 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 JS_InitStandardClasses before executing scripts that make use of JS objects, functions, and built-in objects.

As a side effect, JS_InitStandardClasses uses obj to establish a global object for the specified executable context, cx, if one is not already established.

JS_InitStandardClasses also initializes the general JS function and object classes. Initializing the function class enables building of constructors. Initializing the object classes enables the <object>.<prototype> syntax to work in JavaScript.

Finally, JS_InitStandardClasses initializes the built-in JS objects (Array, Boolean, Date, Math, Number, and String) used by most scripts.

Retrieves the scope chain for a given executable script context.

JSObject * JS_GetScopeChain(JSContext *cx); JS_GetScopeChain retrieves the scope chain for the currently executing (or "active") script or function in a given context, cx. 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.

Allocates a region of memory for use.

void * JS_malloc(JSContext *cx, size_t nbytes); Pointer to a JS context from which to derive runtime information.
Amount of space, in bytes, to allocate.
JS_malloc allocates a region of memory nbytes in size. If the allocation is successful, JS_malloc returns a pointer to the beginning of the region.

If the memory cannot be allocated, JS_malloc passes cx to JS_ReportOutOfMemory to report the error, and returns a null pointer.

As with a standard C call to malloc, the region of memory allocated by this call is uninitialized and should be assumed to contain meaningless information.

Currently JS_malloc is a wrapper on the standard C malloc call. Do not make assumptions based on this underlying reliance. Future versions of JS_malloc may be implemented in a different manner.

Reallocates a region of memory.

void * JS_realloc(JSContext *cx, void *p, size_t nbytes); Pointer to a JS context from which to derive runtime information.
Pointer to the previously allocated memory
Amount of space, in bytes, to reallocate.
JS_realloc reallocates a region of memory, while preserving its contents. Typically you call JS_realloc because you need to allocate more memory than orginally allocated with a call to JS_malloc, but it can also be called to decrease the amount of allocated memory, and even to deallocate the memory region entirely. p is a pointer to the previously allocated memory region, and nbytes is the size, in bytes, of the region to allocate.

Currently JS_realloc is a wrapper on the standard C realloc call. Do not make assumptions based on this underlying reliance. Future versions of JS_realloc may be implemented in a different manner.

If p is null, then JS_realloc behaves like JS_malloc. If p is not null, and nbytes is 0, JS_realloc returns null and the region is deallocated. As with JS_malloc, new space is not initialized and should be regarded to contain meaningless information.

If a reallocation request fails, JS_realloc passes cx to JS_ReportOutOfMemory to report the error.

Whenever the pointer returned by JS_realloc differs from p, the old region of memory is deallocated and should not be used.

Deallocates a region of memory.

void JS_free(JSContext *cx, void *p); Pointer to a JS context from which to derive runtime information.
Pointer to the previously allocated memory
JS_free deallocates a region of memory allocated by previous calls to JS_malloc and JS_realloc. If p is null, JS_free does nothing. Once memory is freed, it should not be used by your application.

Currently JS_free is a wrapper on the standard C free call. Do not make assumptions based on this underlying reliance. Future versions of JS_free may be implemented in a different manner.

Duplicates a specified string within a specific JS executable script context.

char * JS_strdup(JSContext *cx, const char *s); Pointer to a JS context from which to derive runtime information.
Pointer to an existing string to duplicate.
JS_strdup duplicates a specified string, s, within a specified JSContext, cx. To duplicate the string, JS_strdup allocates space from the malloc heap for the a copy of the string, and then copies s to the newly allocated location. If the allocation fails, JS_strdup returns a null pointer. Otherwise, it returns a pointer to the duplicate string.

Creates a new double value.

jsdouble * JS_NewDouble(JSContext *cx, jsdouble d); Pointer to a JS context from which to derive runtime information.
An existing double value to duplicate.
JS_NewDouble creates a copy of a JS double, d, for a given executable script context, cx. Space for the new value is allocated from the JS garbage collection heap.

If the duplication is successful, JS_NewDouble returns a pointer to the copy of the double. Otherwise it returns NULL.

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 JS_AddRoot function.

Creates a JS value based on a JS double.

JSBool JS_NewDoubleValue(JSContext *cx, jsdouble d, jsval *rval); Pointer to a JS context from which to derive runtime information.
An existing double to assign as a value to the jsval.
Pointer to a previously declared jsval into which to store the double value.
JS_NewDoubleValue creates a jsval containing a double value that corresponds to the double passed in as an argument. cx is the executable script context in which this call is made. d is the double value to assign to the jsval, and rval is the jsval into which the new JS double value is stored. Space for the new value is allocated from the JS garbage collection heap.

JS_NewDoubleValue attempts to creates a temporary copy of the double value. If the copy is successful, then the jsval is created, and the function returns JS_TRUE.Otherwise it returns JS_FALSE.

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 JS_AddRoot function.

Internal use only. Summary fragment.

JSBool JS_NewNumberValue(JSContext *cx, jsdouble d, jsval *rval); Pointer to a JS context from which to derive runtime information.
An existing double to assign as a value to the jsval.
Pointer to a previously declared jsval into which to store the double value.
JS_NewNumberValue creates a jsval containing a numeric value that corresponds to the double passed in as an argument. cx is the executable script context in which this call is made. d is the numeric value to assign to the jsval, and rval is the jsval into which the new JS numeric value is stored. Space for the new value is allocated from the JS garbage collection heap.

JS_NewNumberValue 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 JS_NewNumber converts the integer to a JS value. If they do not match, JS_NewNumber calls JS_NewDouble to create a JS value containing the value of the original double. If the creation of the JS value is successful, the function returns JS_TRUE. Otherwise it returns JS_FALSE.

If JS_NewNumberValue 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 JS_AddRoot function.

Adds a garbage collection hash table entry for a specified JS item to protect it from garbage collection.

JSBool JS_AddRoot(JSContext *cx, void *rp); Pointer to a JS context from which to derive runtime information.
Pointer to the item to protect.
JS_AddRoot protects the GC thing pointed at by a specified pointer, *rp, from garbage collection. rp is a pointer to a pointer to a JS double, string, or object. An entry for rp is added to the garbage collector's table for the JSRuntime of the specified JSContext, cx.

If the GC thing pointed to by *rp is an object, then any GC things reachable from it's properties are automatically protected from garbage collection, too.

You should use JS_AddRoot to root only JS objects, JS strings, or JS doubles, and then only if they are derived from calls to their respective JS_NewXXX creation functions.

If the entry in the root table is successfully created, JS_AddRoot returns JS_TRUE. Otherwise it reports an out of memory error and returns JS_FALSE.

*rp may also be a jsval. If JSVAL_IS_GCTHING evaluates to true for that value, then the GC thing will be protected.

Adds a garbage collection hash table entry for a named JS item to protect it from garbage collection.

JSBool JS_AddNamedRoot(JSContext *cx, void *rp, const char *name); Pointer to a JS context from which to derive runtime information.
Pointer to the item to protect.
Name of the item to protect
JS_AddNamedRoot protects the GC thing pointed at by a specified pointer, *rp, from garbage collection. rp is a pointer to a pointer to a JS double, string, or object. An entry for rp is added to the garbage collector's table for the JSRuntime of the specified JSContext, cx.

If the GC thing pointed to by *rp is an object, then any GC things reachable from it's properties are automatically protected from garbage collection, too.

The name parameter is stored in the JSRuntime's root table entry along with rp. The name string's lifetime must be at least as long as the JSRuntime's. Typically name is a static string constant, identifying the source location of the call to JS_AddNamedRoot, for debugging purposes. JS_DumpNamedRoots can be used to access this information from a debugger. You should use JS_AddNamedRoot to root only JS objects, JS strings, or JS doubles, and then only if they are derived from calls to their respective JS_NewXXX creation functions.

If the entry in the root table is successfully created, JS_AddNamedRoot returns JS_TRUE. Otherwise it reports an out of memory error and returns JS_FALSE.

*rp may also be a jsval. If JSVAL_IS_GCTHING evaluates to true for that value, then the GC thing will be protected.

Enumerates the named roots in the garbage collection hash table.

void JS_DumpNamedRoots(JSRuntime *rt, void (*dump)(const char *name, void *rp, void *data), void *data); Pointer to a JSRuntime from which to dump named roots
Pointer to function that actually dumps the named roots
Pointer to a storage area into which to put a root's data.
JS_DumpNamedRoots retrieves information from the garbage collection hash table about the named roots associated with a specific JSRuntime, rt.

dump 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 dump function to replace the internal engine function, note that the function you write must accept the following arguments, in order: Argument Type Description

name

const char *

Name of the current hash entry.

rp

void *

Pointer to the named roots

data

void *

Pointer to a storage area into which to put a root's data.

]]>

data 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 dump function, data must be the same as the last argument passed to the dump function.

Removes a garbage collection hash table entry for a specified JS item to enable it to be garbage collected.

JSBool JS_RemoveRoot(JSContext *cx, void *rp); Pointer to a JS context from which to derive runtime information.
Pointer to the item to remove from the hash table.
JS_RemoveRoot removes an entry for a a specified item, rp, from the garbage collection hash table. When an item is removed from the hash table, it can be garbage collected. rp 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, cx.

JS_RemoveRoot always returns JS_TRUE.

Indicates to the JS engine that the application is starting a thread.

void JS_BeginRequest(JSContext *cx); When your application start a new thread, JS_BeginRequest safely increments the thread counter for the JS engine runtime associated with a given context, cx. In order to increment the counter, this function first checks that garbage collection is not in process. If it is, JS_BeginRequest waits until garbage collection is complete before locking the JS engine runtime and incrementing the thread counter. After incrementing the counter, JS_BeginRequest unlocks the runtime if it previously locked it.

JS_BeginRequest is only available if you compile the JS engine with JS_THREADSAFE defined. In a default engine compilation, JS_THREADSAFE is undefined.

Indicates to the JS engine that the application no longer requires a thread.

void JS_EndRequest(JSContext *cx); When your application no longer requires a thread, JS_EndRequest safely decrements the thread counter for the JS engine runtime associated with a given context, cx. If decrementing the counter reduces it to zero, JS_EndRequest locks the runtime and notifies the garbage collector so that values no longer in use can be cleaned up. To avoid garbage collection notification, call JS_SuspendRequest instead of JS_EndRequest.

JS_EndRequest is only available if you compile the JS engine with JS_THREADSAFE defined. In a default engine compilation, JS_THREADSAFE is undefined.

Indicates to the JS engine that the application is temporarily suspending a thread.

void JS_SuspendRequest(JSContext *cx); When your application suspends use of a thread, JS_SuspendRequest safely decrements the thread counter for the JS engine runtime associated with a given context, cx.

JS_SuspendRequest is only available if you compile the JS engine with JS_THREADSAFE defined. In a default engine compilation, JS_THREADSAFE is undefined.

Restarts a previously suspended thread.

void JS_ResumeRequest(JSContext *cx); When your application restart a previously suspended thread, JS_BeginRequest safely increments the thread counter for the JS engine runtime associated with a given context, cx. In order to increment the counter, this function first checks that garbage collection is not in process. If it is, JS_ResumeRequest waits until garbage collection is complete before locking the JS engine runtime and incrementing the thread counter. After incrementing the counter, JS_ResumeRequest unlocks the runtime if it previously locked it.

JS_ResumeRequest is only available if you compile the JS engine with JS_THREADSAFE defined. In a default engine compilation, JS_THREADSAFE is undefined.

Protects a specified JS item from garbage collection.

JSBool JS_LockGCThing(JSContext *cx, void *thing); Pointer to a JS context from which to derive runtime information.
Pointer to the item to protect.
JS_LockGCThing is a deprecated function that protects a specified item, thing, associated with an executable script context, cx, from garbage collection. thing is a JS double, string, or object. This function is available only for backward compatibility with existing applications. Use JS_AddRoot instead of this function.

Reenables garbage collection of a specified JS item.

JSBool JS_UnockGCThing(JSContext *cx, void *thing); Pointer to a JS context from which to derive runtime information.
Pointer to the item to unlock.
JS_LockGCThing removes a lock from a specified item, thing, enabling it to be garbage collected. Unlocking occurs within a specified executable script context, cx. thing is a JS double, string, or object.This function is available only for backward compatibility with existing applications. Use JS_RemoveRoot instead.

Performs garbage collection in the JS memory pool.

void JS_GC(JSContext *cx); JS_GC performs garbage collection, if necessary, of JS objects, doubles, and strings that are no longer needed by a script executing in a specified JSContext, cx. Garbage collection frees space in the memory pool so that it can be reused by the JS engine.

When you use JS_malloc and JS_realloc to allocate memory for executable script contexts, these routines automatically invoke the garbage collection routine.

When your scripts create many objects, you may want to call JS_GC 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 JS_MaybeGC instead of JS_GC.

Invokes conditional garbage collection on the JS memory pool.

void JS_MaybeGC(JSContext *cx); JS_MaybeGC performs a conditional garbage collection of JS objects, doubles, and strings that are no longer needed by a script executing in a specified JSContext, cx. 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 JS_GC instead of JS_MaybeGC.

Specifies a new callback function for the garbage collector.

JSGCCallback JS_SetGCCallback(JSContext *cx, JSGCCallback cb); JS_SetGCCallback enables you to specify the function is called by the garbage collector to return control to the calling program when garbage collection is complete. cx is the context in which you specify the callback. cb is a pointer to the new callback function to use.

JS_SetGCCallback 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.

To restore the original callback, simply call JS_SetGCCallback a second time, and pass the old callback in as the cb argument.

Frees a JS ID array structure.

void JS_DestroyIdArray(JSContext *cx, JSIdArray *ida); JS_DestroyIdArray frees the JS ID array structure pointed to by ida. cx is the context in which the freeing of the array takes place.

Creates a new JS ID array structure.

JSIdArray JS_NewIdArray(JSContext *cx); JS_NewIdArray allocates memory for a new JS ID array structure. On success, it returns a pointer to the newly allocated structure. Otherwise it returns NULL.

Provides a dummy property argument for API routines that requires property information.

JSBool JS_PropertyStub(JSContext *cx, JSObject *obj, jsval id, jsval *vp); Pointer to a JS context from which to derive runtime information.
Pointer to the object for this stub.
The ID for the stub.
Pointer to a jsval for the stub.
JS_PropertyStub 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.

As designed, JS_PropertyStub does not use the arguments you pass to it, and simply returns JS_TRUE.

Provides a dummy enumeration object for API routines that requires it.

JSBool JS_EnumerateStub(JSContext *cx, JSObject *obj); Pointer to a JS context from which to derive runtime information.
Pointer to the object for this stub.
JS_EnumerateStub 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.

As designed, JS_EnumerationStub does not use the arguments you pass to it, and simply returns JS_TRUE.

Provides a dummy resolution object for API routines that requires it.

JSBool JS_ResolveStub(JSContext *cx, JSObject *obj, jsval id); Pointer to a JS context from which to derive runtime information.
Pointer to the object for this stub.
The ID for the stub.
JS_ResolveStub 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.

As designed, JS_ResolveStub does not use the arguments you pass to it, and simply returns JS_TRUE.

Provides a dummy conversion object for API routines that requires it.

JSBool JS_ConvertStub(JSContext *cx, JSObject *obj, JSType type, jsval *vp); Pointer to a JS context from which to derive runtime information.
Pointer to the object for this stub.
The type to which to convert this object.
Pointer to the JS value in which to store the conversion.
JS_ConvertStub 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.

As designed, JS_ConvertStub does not use the arguments you pass to it, and simply returns JS_TRUE.

Provides a dummy finalization object for API routines that requires it.

void JS_FinalizeStub(JSContext *cx, JSObject *obj); Pointer to a JS context from which to derive runtime information.
Pointer to the object for this stub.
JS_FinalizeStub 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.

As designed, JS_FinalizeStub does not use the arguments you pass to it, and simply returns JS_TRUE.

Initializes a class structure, its prototype, properties, and functions.

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); Pointer to a JS context from which to derive runtime information.
Pointer to the object to use for initializing the class.
Pointer to a prototype object for the class.
Pointer to the class structure to initialize. This structure defines the class for use by other API functions.
The constructor for the class. Its scope matches that of the obj argument. If constructor is NULL, then static_ps and static_fs are also NULL.
Number of arguments for the constructor.
Pointer to the properties structure for the prototype object, parent_proto.
Pointer to the functions structure for the prototype object, parent_proto.
Pointer to the properties structure for the constructor object, if it is not NULL.
Pointer to the functions structure for the constructor object, if it is not NULL.
JS_InitClass 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.

JS_InitClass returns a pointer to a JS object that is the prototype for the newly initialized class. If JS_InitClass fails, then the pointer returned is NULL.

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.

The constructor for the class is built in the same context as cx, and in the same scope as obj. If you pass NULL to JS_InitClass, then a constructor is not built, and you cannot specify static properties and functions for the class.

If you provide a constructor for the class, then you should also pass an object to parent_proto. JS_InitClass uses parent_proto 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, JS_InitClass returns a pointer to the JS object. Otherwise it returns NULL, indicating failure to create the accessor object, and therefore failure to create the class itself.

After building the constructor and prototype, JS_InitClass 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.

Retrieves the class associated with an object.

JSClass * JS_GetClass(JSObject *obj); Alternative syntax when JS_THREADSAFE is defined in a multithreaded environment: JSClass * JS_GetClass(JSContext *cx, JSObject *obj) JS_GetClass returns a pointer to the class associated with a specified JS object, obj. 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.

If your application runs in a multithreaded environment, define JS_THREADSAFE, and pass a thread context as the first argument to JS_GetClass.

If an object has a class, JS_GetClass returns a pointer to the class structure. Otherwise, it returns NULL.

Determines if an object is an instance of a specified JS class.

JSBool JS_InstanceOf(JSContext *cx, JSObject *obj, JSClass *clasp, jsval *argv); Pointer to a JS context from which to derive runtime information.
Object to test.
Class against which to test the object.
Optional argument vector. If you do not want to pass an argument vector, pass NULL for this argument.
JS_InstanceOf determines if a specified JS object, obj, has a JS class struct, clasp. If the object's internal class pointer corresponds to clasp, this function returns JS_TRUE, indicating that the object is an instance of the class. Otherwise, JS_InstanceOf returns JS_FALSE.

If you pass a non-null argument vector, argv, to JS_InstanceOf, and obj is not an instance of clasp, this function may report a class mismatch before returning. To do so, JS_InstanceOf 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 JS_ReportError function.

Retrieves the private data associated with an object.

void * JS_GetPrivate(JSContext *cx, JSObject *obj); Pointer to a JS context from which to derive runtime information.
Object for which to retrieve private data.
JS_GetPrivate retrieves the private data associated with a specified object, obj. To retrieve private data, an object must be an instance of a class, and that class must include the JSCLASS_HAS_PRIVATE flag.

If successful, JS_GetPrivate returns a pointer to the private data. Otherwise it returns NULL which can mean either that there is no private data currently associated with the object, or that the object cannot have private data.

Sets the private data for a JS object.

JSBool JS_SetPrivate(JSContext *cx, JSObject *obj, void *data); Pointer to a JS context from which to derive runtime information.
Object for which to set private data.
Private data for the object.
JS_SetPrivate sets the private data pointer for a specified object, obj. To set private data for an object, the object must be an instance of a class, and the class must include JSCLASS_HAS_PRIVATE in its flag set.

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.

If successful, JS_SetPrivate returns JS_TRUE. Otherwise it returns JS_FALSE.

Retrieves the private data associated with a context.

void * JS_GetContextPrivate(JSContext *cx); Pointer to a JS context for which to retrieve data.
JS_GetContextPrivate retrieves the private data associated with a specified JSContext, cx. If successful, JS_GetContextPrivate returns a pointer to the private data. Otherwise it returns NULL which means that there is no private data currently associated with the context.

Sets the private data for a context.

void JS_SetContextPrivate(JSContext *cx, void *data); Pointer to a JS context for which to set private data.
Pointer to the private data for the context.
JS_SetContextPrivate sets the private data pointer for a specified JSContext, cx.

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.

Retrieves the private data associated with an object if that object is an instance of a class.

void * JS_GetInstancePrivate(JSContext *cx, JSObject *obj, JSClass *clasp, jsval *argv); Pointer to a JS context from which to derive runtime information.
Object for which to retrieve private data.
Class against which to test the object.
Optional argument vector. If you do not want to pass an argument vector, pass NULL for this argument.
JS_GetInstancePrivate determines if a specified JS object, obj, is an instance of a JS class, clasp, and if it is, returns a pointer to the object's private data. If the object's internal class pointer corresponds to clasp, and you do not also pass an optional argument vector, argv, this function attempts to retrieve a pointer to the private data. Otherwise, it returns NULL.

If you pass a non-null argument vector, argv, to JS_GetInstancePrivate, and obj is not an instance of clasp, this function reports a class mismatch before returning NULL. In this case, JS_GetInstancePrivate 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 JS_ReportError function.

If obj is an instance of clasp, but there is no private data currently associated with the object, or the object cannot have private data, JS_GetInstancePrivate also returns NULL.

Retrieves an object's prototype.

JSObject * JS_GetPrototype(JSContext *cx, JSObject *obj); Pointer to a JS context from which to derive runtime information.
Object for which to retrieve the prototype.
JS_GetPrototype retrieves the prototype object for a specified object, obj. A prototype object provides properties shared by similar JS objects.

If an object has a prototype, JS_GetPrototype returns a pointer to the prototype. If the object does not have a prototype, or the object finalize function is active, JS_GetPrototype returns NULL.

Sets the prototype for an object.

JSBool JS_SetPrototype(JSContext *cx, JSObject *obj, JSObject *proto); Pointer to a JS context from which to derive runtime information.
Pointer to the object for which to set the prototype.
Pointer to the prototype to use.
JS_SetPrototype 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 JS_NewObject, but if you do not set a prototype at that time, you can later call JS_SetPrototype to do so.

obj is a pointer to an existing JS object, and proto is a pointer to second existing object upon which the first object is based.

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.

If JS_SetPrototype is successful, it returns JS_TRUE. Otherwise, if it cannot create and fill a prototype slot for the object, it returns JS_FALSE.

Retrieves the parent object for a specified object.

JSObject * JS_GetParent(JSContext *cx, JSObject *obj); Pointer to a JS context from which to derive runtime information.
Object for which to retrieve the parent.
JS_GetParent retrieves the parent object for a specified object, obj. If an object has a parent, JS_GetParent returns a pointer to the parent object. If the object does not have a parent, or the object finalize function is active, JS_GetParent returns NULL.

Sets the parent for an object.

JSBool JS_SetParent(JSContext *cx, JSObject *obj, JSObject *parent); Pointer to a JS context from which to derive runtime information.
Pointer to the object for which to set the parent.
Pointer to the parent object to use.
JS_SetParent 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 JS_NewObject, but if you do not set a parent at that time, you can later call JS_SetParent to do so.

obj is a pointer to an existing JS object, and parent is a pointer to a second existing object of which the first object is a child. If JS_SetParent is successful, it returns JS_TRUE. Otherwise, if it cannot create and fill a parent slot for the object, it returns JS_FALSE.

Retrieves the constructor for an object.

JSObject * JS_GetConstructor(JSContext *cx, JSObject *proto); Pointer to a JS context from which to derive runtime information.
Pointer to the object for which to retrieve a constructor.
JS_GetConstructor retrieves the constructor for a specified object, proto. The constructor is a function that builds the object. If successful, JS_GetConstructor returns a pointer to the constructor object.

If proto does not have any properties, JS_GetConstructor returns NULL. If proto has properties, but it does not have an associated constructor function, JS_GetConstructor reports the lack of a constructor function and then returns NULL.

Instantiates a new object.

JSObject * JS_NewObject(JSContext *cx, JSClass *clasp, JSObject *proto, JSObject *parent); Pointer to a JS context from which to derive runtime information.
Pointer to the class to use for the new object.
Pointer to the prototype object to use for the new class.
Pointer to which to set the new object's __parent__ property.
JS_NewObject instantiates a new object based on a specified class, prototype, and parent object. cx is a pointer to a context associated with the runtime in which to establish the new object. clasp is a pointer to an existing class to use for internal methods, such as finalize. proto is an optional pointer to the prototype object with which to associate the new object.

Set proto to NULL to force JS to assign a prototype object for you. In this case, JS_NewObject 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.

parent is an optional pointer to an existing object to which to set the new object's parent object property. You can set parent to NULL if you do not want to set the parent property.

On success, JS_NewObject returns a pointer to the newly instantiated object. Otherwise it returns NULL.

To create a new object that is a property of an existing object, use JS_DefineObject.

Instantiates a new object and invokes its constructor.

JSObject * JS_ConstructObject(JSContext *cx, JSClass *clasp, JSObject *proto, JSObject *parent); Pointer to a JS context from which to derive runtime information.
Pointer to the class to use for the new object.
Pointer to the prototype object to use for the new class.
Pointer to which to set the new object's __parent__ property.
JS_ConstructObject instantiates a new object based on a specified class, prototype, and parent object, and then invokes its constructor function. cx is a pointer to a context associated with the runtime in which to establish the new object. clasp is a pointer to an existing class to use for internal methods, such as finalize. proto is an optional pointer to the prototype object with which to associate the new object.

parent is an optional pointer to an existing object to which to set the new object's parent object property. You can set parent to NULL if you do not want to set the parent property.

On success, JS_ConstructObject returns a pointer to the newly instantiated object. Otherwise it returns NULL.

Instantiates an object that is a property of another object.

JSObject * JS_DefineObject(JSContext *cx, JSObject *obj, const char *name, JSClass *clasp, JSObject *proto, uintN flags); Pointer to a JS context from which to derive runtime information for error reporting.
Object to which this new object belongs as a property.
Name of the property that encapsulates the new object in obj.
Class to use for the new object.
Prototype object to use for the new object.
Property flags for the new object.
JS_DefineObject instantiates and names a new object for an existing object, obj. name is the property name to assign to obj to hold the new object, and flags contains the property flags to set for the newly created property. The following table lists possible values you can pass in flags, either singly, or OR'd together: Flag Purpose

JSPROP_ENUMERATE

Property is visible to for and in loops.

JSPROP_READONLY

Property is read only.

JSPROP_PERMANENT

Property cannot be deleted.

JSPROP_EXPORTED

Property can be imported by other objects.

JSPROP_INDEX

Property is actually an index into an array of properties, and is cast to a const char *.

]]>

clasp is a pointer to the base class to use when creating the new object, and proto is an pointer to the prototype upon which to base the new object. If you set proto to NULL, JS sets the prototype object for you. The parent object for the new object is set to obj.

JS_DefineObject returns a pointer to the newly created property object if successful. If the property already exists, or cannot be created, JS_DefineObject returns NULL.

Creates one or more constant double-valued properties for an object.

JSBool JS_DefineConstDoubles(JSContext *cx, JSObject *obj, JSConstDoubleSpec *cds); Pointer to a JS context from which to derive runtime information.
Object for which to create new properties.
Pointer to an array of structs containing double property values and property names to create. The last array element must contain zero-valued members.
JS_DefineConstDoubles creates one or more properties for a specified object, obj, where each property consists of a double value. Each property is automatically assigned attributes as specified in the flags field of the JSConstDoubleSpec struct pointed to by cds. If flags is set to zero, the attributes for the property are automatically set to JSPROP_PERMANENT | JSPROP_READONLY.

cds is a pointer to the first element of an array of JSConstDoubleSpecs. Each array element defines a single property name and property value to create. The name field of last element of the array must contain a zero value. JS_DefineConstDoubles creates one property for each element in the array what contains a non-zero name field.

If successful, JS_DefineConstDoubles returns JS_TRUE, indicating it has created all properties listed in the array. Otherwise it returns JS_FALSE.

Creates one or more properties for an object.

JSBool JS_DefineProperties(JSContext *cx, JSObject *obj, JSPropertySpec *ps); Pointer to a JS context from which to derive runtime information.
Object for which to create new properties.
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.
JS_DefineProperties creates one or more properties in a specified object, obj.

ps is a pointer to the first element of an array of JSPropertySpec structures. Each array element defines a single property: its name, id, flags, and getProperty and setProperty methods. The name field of the last array element must contain zero-valued members. JS_DefineProperties creates one property for each element in the array with a non-zero name field.

If successful, JS_DefineProperties returns JS_TRUE, indicating it has created all properties listed in the array. Otherwise it returns JS_FALSE.

Creates a single property for a specified object.

JSBool) JS_DefineProperty(JSContext *cx, JSObject *obj, const char *name, jsval value, JSPropertyOp getter, JSPropertyOp setter, uintN flags); Pointer to a JS context from which to derive runtime information.
Object for which to create the new property.
Name for the property to create.
Initial value to assign to the property.
getProperty method for retrieving the current property value.
setProperty method for specifying a new property value.
Property flags.
JS_DefineProperty defines a single property in a specified object, obj.

name is the name to assign to the property in the object. value is a jsval that defines the property's data type and initial value. getter and setter identify the getProperty and setProperty methods for the property, respectively. If you pass null values for these entries, JS_DefineProperties assigns the default getProperty and setProperty methods to this property. flags contains the property flags to set for the newly created property. The following table lists possible values you can pass in flags, either singly, or OR'd together: Flag Purpose

JSPROP_ENUMERATE

Property is visible in for and in loops.

JSPROP_READONLY

Property is read only.

JSPROP_PERMANENT

Property cannot be deleted.

JSPROP_EXPORTED

Property can be imported by other objects.

JSPROP_INDEX

Property is actually an index into an array of properties, and is cast to a const char *.

]]>

While you can assign a setProperty method to a property and set flags to JSPROP_READONLY, the setter method will not be called on this property.

If it successfully creates the property, JS_DefineProperty returns JS_TRUE. If the property already exists, or cannot be created, JS_DefineProperty returns JS_FALSE.

Creates a single Unicode-encoded property for a specified object.

JSBool) JS_DefineUCProperty(JSContext *cx, JSObject *obj, const jschar *name, size_t namelen, jsval value, JSPropertyOp getter, JSPropertyOp setter, uintN attrs); Pointer to a JS context from which to derive runtime information.
Object for which to create the new property.
Name for the property to create.
Length of name, in bytes.
Initial value to assign to the property.
getProperty method for retrieving the current property value.
setProperty method for specifying a new property value.
Property flags.
JS_DefineUCProperty defines a single Unicode-encoded property in a specified object, obj.

name is the Unicode-encoded name to assign to the property in the object. namelen is the length, in bytes, of name. value is a jsval that defines the property's data type and initial value. getter and setter identify the getProperty and setProperty methods for the property, respectively. If you pass null values for these entries, JS_DefineUCProperties assigns the default getProperty and setProperty methods to this property. attrs contains the property flags to set for the newly created property. The following table lists possible values you can pass in attrs, either singly, or OR'd together: Flag Purpose

JSPROP_ENUMERATE

Property is visible in for and in loops.

JSPROP_READONLY

Property is read only.

JSPROP_PERMANENT

Property cannot be deleted.

JSPROP_EXPORTED

Property can be imported by other objects.

JSPROP_INDEX

Property is actually an index into an array of properties, and is cast to a const char *.

]]>

While you can assign a setProperty method to a property and set attrs to JSPROP_READONLY, the setter method will not be called on this property.

If it successfully creates the property, JS_DefineUCProperty returns JS_TRUE. If the property already exists, or cannot be created, JS_DefineUCProperty returns JS_FALSE.

Creates a single property for a specified object and assigns it an ID number.

JSBool JS_DefinePropertyWithTinyId( JSContext *cx, JSObject *obj, const char *name, int8 tinyid, jsval value, JSPropertyOp getter, JSPropertyOp setter, uintN flags); Pointer to a JS context from which to derive runtime information.
Object for which to create the new property.
Name for the property to create.
8-bit ID to aid in sharing getProperty/setProperty methods among properties.
Initial value to assign to the property.
getProperty method for retrieving the current property value.
setProperty method for specifying a new property value.
Property flags.
JS_DefinePropertyWithTinyId defines a single property for a specified object, obj.

name is the name to assign to the property in the object. value is a jsval that defines the property's data type and initial value.

tinyid is an 8-bit value that simplifies determining which property to access, and is especially useful in getProperty and setProperty methods that are shared by a number of different properties.

getter and setter identify the getProperty and setProperty methods for the property, respectively. If you pass null values for these entries, JS_DefinePropertyWithTinyId assigns the default getProperty and setProperty methods to this property. flags contains the property flags to set for the newly created property. The following table lists possible values you can pass in flags, either singly, or OR'd together: Flag Purpose

JSPROP_ENUMERATE

Property is visible in for and in loops.

JSPROP_READONLY

Property is read only.

JSPROP_PERMANENT

Property cannot be deleted.

JSPROP_EXPORTED

Property can be imported by other objects.

JSPROP_INDEX

Property is actually an index into an array of properties, and is cast to a const char *.

]]>

While you can assign a setProperty method to a property and set flags to JSPROP_READONLY, the setter method will not be called on this property.

If it successfully creates the property, JS_DefinePropertyWithTinyId returns JS_TRUE. If the property already exists, or cannot be created, it returns JS_FALSE.

Creates a single, Unicode-encoded property for a specified object and assigns it an ID number.

JSBool JS_DefinePropertyWithTinyId( JSContext *cx, JSObject *obj, const jschar *name, size_t namelen, int8 tinyid, jsval value, JSPropertyOp getter, JSPropertyOp setter, uintN attrs); Pointer to a JS context from which to derive runtime information.
Object for which to create the new property.
Name for the property to create.
Length, in bytes, of name.
8-bit ID to aid in sharing getProperty/setProperty methods among properties.
Initial value to assign to the property.
getProperty method for retrieving the current property value.
setProperty method for specifying a new property value.
Property flags.
JS_DefineUCPropertyWithTinyId defines a single, Unicode-encoded property for a specified object, obj.

name is the Unicode-encoded name to assign to the property in the object. namelen is the length, in bytes, of name. value is a jsval that defines the property's data type and initial value.

tinyid is an 8-bit value that simplifies determining which property to access, and is especially useful in getProperty and setProperty methods that are shared by a number of different properties.

getter and setter identify the getProperty and setProperty methods for the property, respectively. If you pass null values for these entries, JS_DefineUCPropertyWithTinyId assigns the default getProperty and setProperty methods to this property. attrs contains the property flags to set for the newly created property. The following table lists possible values you can pass in sttrs, either singly, or OR'd together: Flag Purpose

JSPROP_ENUMERATE

Property is visible in for and in loops.

JSPROP_READONLY

Property is read only.

JSPROP_PERMANENT

Property cannot be deleted.

JSPROP_EXPORTED

Property can be imported by other objects.

JSPROP_INDEX

Property is actually an index into an array of properties, and is cast to a const char *.

]]>

While you can assign a setProperty method to a property and set attrs to JSPROP_READONLY, the setter method will not be called on this property.

If it successfully creates the property, JS_DefineUCPropertyWithTinyId returns JS_TRUE. If the property already exists, or cannot be created, it returns JS_FALSE.

Deprecated. Create an alias for a native property.

JSBool JS_AliasProperty(JSContext *cx, JSObject *obj, const char *name, const char *alias); Pointer to a JS context from which to derive runtime information.
Object for which to create the alias.
Name of the property for which to create an alias.
Alias name to assign to the property.
JS_AliasProperty assigns an alternate name for a property associated with a native object. obj is the object to which the property belongs. name is the property's current name in the object, and alias is the alternate name to assign to the property.

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.

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, JS_AliasProperty returns JS_TRUE. Creating an alias does not change the length of the property array.

If the property name you specify does not exist, JS_AliasProperty reports an error, and returns JS_FALSE. If the property is currently out of scope, already exists, or the alias itself cannot be assigned to the property, JS_AliasProperty does not report an error, but returns JS_FALSE.

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.

Determines if a specified property exists.

JSBool JS_LookupProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp); Pointer to a JS context from which to derive runtime information.
Object to search on for the property.
Name of the property to look up.
Pointer to a variable into which to store the last retrieved value of the property if it exists. If not, vp is set to JSVAL_VOID.
JS_LookupProperty examines a specified JS object, obj, for a property named name. If the property exists, vp is set either to the last retrieved value of the property if it exists, or to JSVAL_VOID if it does not, and JS_LookupProperty returns JS_TRUE. On error, such as running out of memory during the search, JS_LookupProperty returns JS_FALSE, and vp is undefined.

JS_LookupProperty does not distunguish between a property with a value of undefined and a property that does not exist. Use JS_GetPropertyAttributes to distinguish these cases.

Determines if a specified, Unicode-encoded property exists.

JSBool JS_LookupUCProperty(JSContext *cx, JSObject *obj, const jschar *name, size_t namelen, jsval *vp); Pointer to a JS context from which to derive runtime information.
Object to search on for the property.
Name of the property to look up.
Length, in bytes, of name.
Pointer to a variable into which to store the last retrieved value of the property if it exists. If not, vp is set to JSVAL_VOID.
JS_LookupUCProperty examines a specified JS object, obj, for a Unicode-encoded property named name. namelen indicates the size, in bytes, of name. If the property exists, vp is set either to the last retrieved value of the property if it exists, or to JSVAL_VOID if it does not, and JS_LookupProperty returns JS_TRUE. On error, such as running out of memory during the search, JS_LookupProperty returns JS_FALSE, and vp is undefined.

JS_LookupUCProperty does not distunguish between a property with a value of undefined and a property that does not exist.

Finds a specified property and retrieves its value.

JSBool JS_GetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp); Pointer to a JS context from which to derive runtime information.
Object to search on for the property.
Name of the property to look up.
Pointer to a variable into which to store the current value of the property if it exists. If not, vp is set to JSVAL_VOID.
JS_GetProperty examines a specified JS object, obj, its scope and prototype links, for a property named name. If the property is not defined on the object in its scope, or in its prototype links, vp is set to JSVAL_VOID.

If the property exists, JS_GetProperty sets vp to the current value of the property, and returns JS_TRUE. If an error occurs during the search, JS_GetProperty returns JS_FALSE, and vp is undefined.

Finds a specified, Unicode-encoded property and retrieves its value.

JSBool JS_GetUCProperty(JSContext *cx, JSObject *obj, const jschar *name, size_t namelen, jsval *vp); Pointer to a JS context from which to derive runtime information.
Object to search on for the property.
Name of the property to look up.
Length, in bytes of the the property name to look up.
Pointer to a variable into which to store the current value of the property if it exists. If not, vp is set to JSVAL_VOID.
JS_GetUCProperty examines a specified JS object, obj, its scope and prototype links, for a property named name. namelen indicates the size, in bytes, of name. If the property is not defined on the object in its scope, or in its prototype links, vp is set to JSVAL_VOID.

If the property exists, JS_GetUCProperty sets vp to the current value of the property, and returns JS_TRUE. If an error occurs during the search, JS_GetUCProperty returns JS_FALSE, and vp is undefined.

Sets the current value of a property belonging to a specified object.

JSBool JS_SetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp); Pointer to a JS context from which to derive runtime information.
Object to which the property to set belongs.
Name of the property to set.
Pointer to the value to set for the property.
JS_SetProperty 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, JS_SetProperty sets the JSPROP_ENUMERATE attribute in the property's flags field; all other values for the property are undefined.

name is the property to set, and vp is a pointer to the new value to set for the property. On successfully setting a property to a new value, JS_SetProperty returns JS_TRUE. Otherwise it returns JS_FALSE.

If you attempt to set the value for a read-only property using JavaScript 1.2 or earlier, JS_SetProperty reports an error and returns JS_FALSE. For JavaScript 1.3 and greater, such an attempt is silently ignored.

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, JS_SetProperty creates a new read-only property on the object, sets its value to JSVAL_VOID, and reports a read-only violation error.

Sets the current value of a Unicode-encoded property belonging to a specified object.

JSBool JS_SetUCProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp); Pointer to a JS context from which to derive runtime information.
Object to which the property to set belongs.
Name of the property to set.
Length, in bytes, of the name of the property to set.
Pointer to the value to set for the property.
JS_SetUCProperty 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, JS_SetUCProperty sets the JSPROP_ENUMERATE attribute in the property's flags field; all other values for the property are undefined.

name is the property to set, namelen indicates the size, in bytes, of name, and vp is a pointer to the new value to set for the property. On successfully setting a property to a new value, JS_SetUCProperty returns JS_TRUE. Otherwise it returns JS_FALSE.

If you attempt to set the value for a read-only property using JavaScript 1.2 or earlier, JS_SetUCProperty reports an error and returns JS_FALSE. For JavaScript 1.3 and greater, such an attempt is silently ignored.

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, JS_SetUCProperty creates a new read-only property on the object, sets its value to JSVAL_VOID, and reports a read-only violation error.

Removes a specified property from an object.

JSBool JS_DeleteProperty(JSContext *cx, JSObject *obj, const char *name); Pointer to a JS context from which to derive runtime information.
Object from which to delete a property.
Name of the property to delete.
JS_DeleteProperty removes a specified property, name, from an object, obj. 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, JS_DeleteProperty returns JS_TRUE. Otherwise it returns JS_FALSE.

Per the ECMA standard, JS_DeleteProperty removes read-only properties from objects as long as those properties are not also permanent.

For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent property, JS_DeleteProperty reports the error before returning JS_FALSE. For JavaScript 1.3, the attempt is silently ignored.

To remove all properties from an object, call JS_ClearScope.

Removes a specified property from an object.

JSBool JS_DeleteProperty2(JSContext *cx, JSObject *obj, const char *name, jsval *rva); Pointer to a JS context from which to derive runtime information.
Object from which to delete a property.
Name of the property to delete.
Pointer to the deleted value.
JS_DeleteProperty2 removes a specified property, name, from an object, obj, and stores a pointer to the deleted property in rval. If rval is NULL, 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, JS_DeleteProperty2 returns JS_TRUE. Otherwise it returns JS_FALSE.

Per the ECMA standard, JS_DeleteProperty2 removes read-only properties from objects as long as those properties are not also permanent.

For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent property, JS_DeleteProperty2 reports the error before returning JS_FALSE. For JavaScript 1.3, the attempt is silently ignored. In both these cases, rval will contain a non-NULL pointer to the undeleted property.

To remove all properties from an object, call JS_ClearScope.

Removes a specified Unicode-encoded property from an object.

JSBool JS_DeleteUCProperty2(JSContext *cx, JSObject *obj, const jschar *name, size_t namelen, jsval *rva); Pointer to a JS context from which to derive runtime information.
Object from which to delete a property.
Name of the property to delete.
Length, in bytes, of the property name.
Pointer to the deleted value.
JS_DeleteUCProperty2 removes a specified property, name, from an object, obj, and stores a pointer to the deleted property in rval. If rval is NULL, the property is deleted. namelen 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, JS_DeleteUCProperty2 returns JS_TRUE. Otherwise it returns JS_FALSE.

Per the ECMA standard, JS_DeleteUCProperty2 removes read-only properties from objects as long as those properties are not also permanent.

For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent property, JS_DeleteUCProperty2 reports the error before returning JS_FALSE. For JavaScript 1.3, the attempt is silently ignored. In both these cases, rval will contain a non-NULL pointer to the undeleted property.

To remove all properties from an object, call JS_ClearScope.

Retrieves the attributes of a specified property.

JSBool JS_GetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name, uintN *attrsp, JSBool *foundp); Pointer to a JS context from which to derive runtime information.
Object from which to retrieve property attributes.
Name of the property from which to retrieve attributes.
Pointer to the storage area into which to place retrieves attributes.
Flag indicating whether or not the specified property was located.
JS_GetPropertyAttributes retrieves the attributes for a specified property, name. cx is the context, and obj is a pointer to the object that owns the property. attrsp is a pointer to the unsigned integer storage area into which to retrieve the attributes.

If JS_GetPropertyAttributes cannot locate an object with the specified property, it returns JS_FALSE, and both attrsp and foundp are undefined.

If the specified property or the specified object does not exist, foundp is set to JS_FALSE. If the property exists, but belongs to another object, JS_GetPropertyAttributes then returns JS_FALSE, and attrsp is undefined. If the property exists and it belongs to the object you specify, then foundp is set to JS_TRUE. If JS_GetPropertyAttributes can actually read the current property values, it returns JS_TRUE. Otherwise, it returns JS_FALSE.

Sets the attributes for a specified property.

JSBool JS_SetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name, uintN attrs, JSBool *foundp); Pointer to a JS context from which to derive runtime information.
Object for which to set property attributes.
Name of the property for which to set attributes.
Attribute values to set.
Flag indicating whether or not the specified property was located.
JS_SetPropertyAttributes sets the attributes for a specified property, name. cx is the context, and obj is a pointer to the object that owns the property. attrsp is an unsigned integer containing the attribute value to set, and can contain 0 or more of the following values OR'd:

JSPROP_ENUMERATE: property is visible in for loops.

JSPROP_READONLY: property is read-only.

JSPROP_PERMANENT: property cannot be deleted.

JSPROP_EXPORTED: property can be exported outside its object.

JSPROP_INDEX: property is actually an array element.

]]> If JS_SetPropertyAttributes cannot locate an object with the specified property, it returns JS_FALSE, and foundp is undefined.

If the specified property or the specified object does not exist, foundp is set to JS_FALSE. Then, iff the property exists, but is associated with a different object, JS_SetPropertyAttributes returns JS_TRUE. Otherwise, it sets foundp to JS_TRUE, and attempts to set the attributes as specified. If the attributes can be set, JS_SetPropertyAttributes returns JS_TRUE. If not, it returns JS_FALSE.

Creates a new array object.

JSObject * JS_NewArrayObject(JSContext *cx, jsint length, jsval *vector); Pointer to a JS context from which to derive runtime information.
Number of elements to include in the array.
Pointer to the initial values for the array's elements.
JS_NewArrayObject creates a new array object in the JSRuntime of the specified JSContext, cx. If array creation is successful, JS_NewArrayObject initializes each element identified by index i from 0 to length - 1 to have the value vector[i], and then returns a pointer to the new object. Otherwise JS_NewArrayObject returns NULL.

length specifies the number of elements in the array. If length is 0, JS_NewArrayObject creates an array object of length 0 and ignores vector. It is often better to call JS_NewArrayObject(cx, 0, NULL), store the returned object in a GC root, and then populate its elements with JS_SetElement or JS_DefineElement. This avoids unrooted jsvals in vector from being subject to garbage collection until the new object has been populated.

Determines if a specified object is of the Array class.

JSBool JS_IsArrayObject(JSContext *cx, JSObject *obj); Pointer to a JS context from which to derive runtime information.
Object to examine.
JS_IsArrayObject determines if a specified object, obj, is of the Array class. If the object is of the Array class, JS_IsArrayObject returns JS_TRUE. Otherwise it returns JS_FALSE.

Retrieves the number of elements in an array object.

JSBool JS_GetArrayLength(JSContext *cx, JSObject *obj, jsint *lengthp); Pointer to the JS context for the object.
Array object for which the number of array elements.
Variable in which to report the number of array elements.
JS_GetArrayLength reports the number of elements in an array object, obj. If the number of elements can be determined, JS_GetArrayLength reports the number of elements in lengthp and returns JS_TRUE. Otherwise, it sets lengthp to NULL and returns JS_FALSE.

Specifies the number of elements for an array object.

JSBool JS_SetArrayLength(JSContext *cx, JSObject *obj, jsint length); Pointer to a JS context from which to derive runtime information.
Array object for which to set the number of array elements.
Number of array elements to set.
JS_SetArrayLength specifies the number of elements for an array object, obj. length indicates the number of elements. If JS_SetArrayLength successfully sets the number of elements, it returns JS_TRUE. Otherwise it returns JS_FALSE.

You can call JS_SetArrayLength 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.

Setting the number of array elements does not initialize those elements. To initialize an element call JS_DefineElement. If you call JS_SetArrayLength on an existing array, and length is less than the highest index number for previously defined elements, all elements greater than or equal to length are automatically deleted.

Determines if an object has an array length property.

JSBool JS_HasArrayLength(JSContext *cx, JSObject *obj, jsuint *lengthp); JS_HasArrayLength determines if an object, obj, has a length property. If the property exists, JS_HasArrayLength returns the current value of the property in lengthp.

On success, JS_HasArrayLength returns JS_TRUE, and lengthp indicates the current value of the array property. On failure, JS_HasArrayLength returns JS_FALSE, and lengthp is undefined.

Creates a single element or numeric property for a specified object.

JSBool JS_DefineElement(JSContext *cx, JSObject *obj, jsint index, jsval value, JSPropertyOp getter, JSPropertyOp setter, uintN flags); Pointer to a JS context from which to derive runtime information.
Object for which to create the new element.
Array index number for the element to define.
Initial value to assign to the element.
getProperty method for retrieving the current element value.
setProperty method for specifying a new element value.
Property flags.
JS_DefineElement defines a single element or numeric property for a specified object, obj.

index is the slot number in the array for which to define an element. It may be an valid jsval integer. value is a jsval that defines the element's data type and initial value. getter and setter identify the getProperty and setProperty methods for the element, respectively. If you pass null values for these entries, JS_DefineElement assigns the default getProperty and setProperty methods to this element. flags contains the property flags to set for the newly created element. The following table lists possible values you can pass in flags, either singly, or OR'd together: Flag Purpose

JSPROP_ENUMERATE

Element is visible in for and in loops.

JSPROP_READONLY

Element is read only.

JSPROP_PERMANENT

Element cannot be deleted.

JSPROP_EXPORTED

Element can be imported by other objects.

JSPROP_INDEX

Property is actually an index into an array of properties, and is cast to a const char *.

]]>

While you can assign a setProperty method to a property and set flags to JSPROP_READONLY, the setter method will not be called on this property.

If it successfully creates the element, JS_DefineElement returns JS_TRUE. Otherwise it returns JS_FALSE.

Deprecated. Create an aliased index entry for an existing element or numeric property of a native object.

JSBool JS_AliasElement(JSContext *cx, JSObject *obj, const char *name, jsint alias); Pointer to a JS context from which to derive runtime information.
Object for which to create the alias.
Name of the element for which to create an alias. This name corresponds to a string representation of the element's current index number.
Alias number to assign to the element.
JS_AliasElement assigns an alternate index number for an element or numeric property associated with a native object. obj is the object to which the element belongs. name is the element's current index in the object, and alias is the alternate index to assign to the element.

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.

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, JS_AliasElement returns JS_TRUE. Adding an alias element does not change the element array length.

If the property name you specify does not exist, JS_AliasElement reports an error, and returns JS_FALSE. If the element is currently out of scope, already exists, or the alias itself cannot be assigned to the element, JS_AliasElement does not report an error, but returns JS_FALSE.

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.

Determines if a specified element or numeric property exists.

JSBool JS_LookupElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp); Pointer to a JS context from which to derive runtime information.
Object to search on for the element.
Index number of the element to look up.
Pointer to a variable into which to store the current value of the element if it has a value. If not, vp is set to JSVAL_VOID.
JS_LookupElement examines a specified JS object, obj, for an element or numeric property numbered index. If the element exists, vp is set either to the current value of the property if it has a value, or to JSVAL_VOID if it does not, and JS_LookupElement returns JS_TRUE. On error, such as running out of memory during the search, JS_LookupElement returns JS_FALSE, and vp is undefined.

JS_LookupElement does not distunguish between a property with a value of undefined and a property that does not exist.

Finds specified element or numeric property associated with an object or the object's class and retrieves its current value.

JSBool JS_GetElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp); Pointer to a JS context from which to derive runtime information.
Array object to search on for the element.
Index number of the element to look up.
Pointer to a variable into which to store the current value of the element if it has a value. If not, vp is set to JSVAL_VOID.
JS_GetElement examines a specified JS object, obj, its scope and prototype links, for an element or numeric property numbered index.

If the element exists, JS_GetElement sets vp to the current value of the element if it has a value, or to JSVAL_VOID if it does not, and returns JS_TRUE. If an error occurs during the search, JS_GetElement returns JS_FALSE, and vp is undefined.

Sets the current value of an element or numeric property belonging to a specified object.

JSBool JS_SetElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp); Pointer to a JS context from which to derive runtime information.
Array object to which the element to set belongs.
Index number of the element to set.
Pointer to the value to set for the element.
JS_SetElement 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, JS_SetElement sets the JSPROP_ENUMERATE attribute in the element's flags field; all other values for the property are undefined.

index is element number to set, and vp is a pointer to the new value to set for the element. On successfully setting an element to a new value, JS_SetElement returns JS_TRUE. Otherwise it returns JS_FALSE.

If you attempt to set the value for a read-only element using JavaScript 1.2 or earlier, JS_SetElement reports an error and returns JS_FALSE. For JavaScript 1.3 and greater, such an attempt is silently ignored.

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, JS_SetElement creates a new read-only element on the object, sets its value to JSVAL_VOID, and reports a read-only violation error.

Public. Removes a specified element or numeric property from an object.

JSBool JS_DeleteElement(JSContext *cx, JSObject *obj, jsint index); Pointer to a JS context from which to derive runtime information.
Object from which to delete an element.
Index number of the element to delete.
JS_DeleteElement removes a specified element or numeric property, index, from an object, obj. 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, JS_DeleteElement returns JS_TRUE. Otherwise it returns JS_FALSE.

For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent or read-only element, JS_DeleteProperty reports the error before returning JS_FALSE. For JavaScript 1.3, the attempt is silently ignored.

To remove all elements and properties from an object, call JS_ClearScope.

Removes a specified element or numeric property from an object.

JSBool JS_DeleteElement2(JSContext *cx, JSObject *obj, const char *name, jsval *rva); Pointer to a JS context from which to derive runtime information.
Object from which to delete an element.
Name of the element to delete.
Pointer to the deleted value.
JS_DeleteElement2 removes a specified element, name, from an object, obj, and stores a pointer to the deleted element in rval. If rval is NULL, 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, JS_DeleteElement2 returns JS_TRUE. Otherwise it returns JS_FALSE.

Per the ECMA standard, JS_DeleteElement2 removes read-only elements from objects as long as those elements are not also permanent.

For JavaScript 1.2 and earlier, if failure occurs because you attempt to delete a permanent element, JS_DeleteElement2 reports the error before returning JS_FALSE. For JavaScript 1.3, the attempt is silently ignored. In both these cases, rval will contain a non-NULL pointer to the undeleted element.

To remove all elements and properties from an object, call JS_ClearScope.

Removes all properties associated with an object.

void JS_ClearScope(JSContext *cx, JSObject *obj); Pointer to a JS context from which to derive runtime information.
Object from which to delete all properties.
JS_ClearScope removes all properties and elements from obj in a single operation. To remove a single property from an object, call JS_DeleteProperty, and to remove a single array object element, call JS_DeleteElement.

Enumerates the properties of a specified object.

JSIdArray * JS_Enumerate(JSContext *cx, JSObject *obj); JS_Enumerate enumerates all properties of a specified object, obj, and returns an array of property IDs for them. Enumeration occurs in a specified JSContext, cx.

On success, JS_Enumerate returns a pointer to an array of property IDs. On failure, it returns NULL.

Determines the scope of access to an object.

JSBool JS_CheckAccess(JSContext *cx, JSObject *obj, jsid id, JSAccessMode mode, jsval *vp, uintN *attrsp); JS_CheckAccess determines the scope of access to an object, obj, and its scope chain. Checking occurs in a specified JSContext, cx.

id is the JS ID of a property belonging to the object. mode determines the scope of the access check, and can be one or more of the following enumerated values OR'd:

JSACC_PROTO: Permission is granted to check both the object itself and its underlying propotype object.

JSACC_PARENT: Permission is granted to check both the object itself and its underlying parent object.

JSACC_IMPORT: Permission is granted to check an imported object.

JSACC_WATCH: Permission is granted to check a debugger watch object.

]]> On success, JS_CheckAccess returns JS_TRUE, vp points to the current value of the specified property, identified by id, and attrsp points to the value of the attribute flag for that property. On failure, JS_CheckAccess returns JS_FALSE, and both vp and attrsp are undefined.

Creates a new JS function that wraps a native C function.

JSFunction * JS_NewFunction(JSContext *cx, JSNative call, uintN nargs, uintN flags, JSObject *parent, const char *name); Pointer to a JS context from which to derive runtime information.
Native C function call wrapped by this function.
Number of arguments that are passed to the underlying C function.
Function attributes.
Pointer to the parent object for this function.
Name to assign to the new function. If you do not assign a name to the function, it is assigned the name "anonymous".
JS_NewFunction creates a new JS function based on the parameters you pass. call is a native C function call that this function wraps. If you are not wrapping a native function, use JS_DefineFunction, instead. nargs is the number of arguments passed to the underlying C function. JS uses this information to allocate space for each argument.

flags lists the attributes to apply to the function. Currently documented attributes, JSFUN_BOUND_METHOD and JSFUN_GLOBAL_PARENT, are deprecated and should no longer be used. They continue to be supported only for existing applications that already depend on them.

parent is the parent object for this function. If a function has no parent, you can set parent to NULL. name is the name to assign to the function. If you pass an empty value, JS sets the function's name to anonymous.

If JS_NewFunction is successful, it returns a pointer to the newly created function. Otherwise it returns NULL.

Retrieves the object for a specified function.

JSObject * JS_GetFunctionObject(JSFunction *fun); JS_GetFunctionObject retrieves the object for a specified function pointer, fun. All functions are associated with an underlying object. For functions you create with JS_NewFunction, the object is automatically created for you. For functions you define with JS_DefineFunction and JS_DefineFunctions, you specify the object(s) as a parameter.

JS_GetFunctionObject always returns a pointer to an object.

Retrieves the given name for a specified function.

const char * JS_GetFunctionName(JSFunction *fun); JS_GetFunctionName retrieves the function name associated with a function pointer, fun. 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.

The pointer returned by this function is valid only as long as the specified function, fun, is in existence.

Creates one or more functions for a JS object.

JSBool JS_DefineFunctions(JSContext *cx, JSObject *obj, JSFunctionSpec *fs); Pointer to a JS context from which to derive runtime information.
Object for which to define functions.
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.
JS_DefineFunctions creates one or more functions and makes them properties (methods) of a specified object, obj.

fs is a pointer to the first element of an array of JSFunctionSpec. 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. JS_DefineFunctions creates one function for each non-zero element in the array.

JS_DefineFunctions always returns JS_TRUE, indicating it has created all functions specified in the array.

To define only a single function for an object, call JS_DefineFunction.

Creates a function and assigns it as a property to a specified JS object.

JSFunction * JS_DefineFunction(JSContext *cx, JSObject *obj, const char *name, JSNative call, uintN nargs, uintN flags); Pointer to a JS context from which to derive runtime information.
Object for which to define a function as a property (method).
Name to assign to the function.
Indicates the built-in, native C call wrapped by this function.
Number of arguments that are passed to the function when it is called.
Function attributes.
JS_DefineFunction defines a single function and assigns it as a property (method) to a specified object, obj.

name is the name to assign to the function in the object. call is a built-in, native C call that is wrapped by your function. nargs indicates the number of arguments the function expects to receive. JS uses this information to allocate storage space for each argument.

If it succesfully creates the property, JS_DefineFunction returns a pointer to the function. Otherwise it returns NULL.

Creates a new function object from an existing function structure.

JSObject * JS_CloneFunctionObject(JSContext *cx, JSObject *funobj, JSObject *parent); JS_CloneFunctionObject creates a new function object. The new object shares an underlying function structure with funobj. funobj becomes the prototype for the newly cloned object, which means that its argument properties are not copied. The cloned object has parent as its parent object.

On success, JS_CloneFunctionObject returns a pointer to the newly created object. On failure, it returns NULL.

Compiles a script for execution.

JSScript * JS_CompileScript(JSContext *cx, JSObject *obj, const char *bytes, size_t length, const char *filename, uintN lineno); Pointer to a JS context from which to derive runtime information.
Object with which the script is associated.
String containing the script to compile.
Size, in bytes, of the script to compile.
Name of file or URL containing the script. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
JS_CompileScript compiles a script, bytes, for execution. The script is associated with a JS object. bytes is the string containing the text of the script. length indicates the size of the text version of the script in bytes.

To compile a script using a Unicode character set, call JS_CompileUCScript instead of this function.

filename 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, lineno is used to report the line number of the script or file where an error occurred during compilation.

If a script compiles successfully, JS_CompileScript returns a pointer to the compiled script. Otherwise JS_CompileScript returns NULL, and reports an error.

To compile a script from an external file source rather than passing the actual script as an argument, use JS_CompileFile instead of JS_CompileScript.

Compiles a security-enabled script for execution.

JSScript * JS_CompileScriptForPrincipals(JSContext *cx, JSObject *obj, JSPrincipals *principals, const char *bytes, size_t length, const char *filename, uintN lineno); Pointer to a JS context from which to derive runtime information.
Object with which the script is associated.
Pointer to the structure holding the security information for this script.
String containing the script to compile.
Size, in bytes, of the script to compile.
Name of file or URL containing the script. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
JS_CompileScriptForPrincipals compiles a security-enabled script, bytes, for execution. The script is associated with a JS object.

principals is a pointer to the JSPrincipals structure that contains the security information to associate with this script.

bytes is the string containing the text of the script. length indicates the size of the text version of the script in bytes.

To compile a secure script using a Unicode character set, call JS_CompileUCScriptForPrincipals instead of this function.

If a script compiles successfully, JS_CompileScriptForPrincipals returns a pointer to the compiled script. Otherwise JS_CompileScriptForPrincipals returns NULL, and reports an error.

Compiles a Unicode-encoded script for execution.

JSScript * JS_CompileUCScript(JSContext *cx, JSObject *obj, const jschar *chars, size_t length, const char *filename, uintN lineno); Pointer to a JS context from which to derive runtime information.
Object with which the script is associated.
String containing the script to compile.
Number of Unicode characters in the script to compile.
Name of file or URL containing the script. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
JS_CompileUCScript compiles a script using a Unicode character set, chars, for execution. The script is associated with a JS object. chars is the Unicode string containing the text of the script. length indicates the size of the script in characters.

If a script compiles successfully, JS_CompileUCScript returns a pointer to the compiled script. Otherwise JS_UCCompileScript returns NULL, and reports an error.

To compile a script from an external file source rather than passing the actual script as an argument, use JS_CompileFile instead of JS_CompileScript.

Compiles a security-enabled, Unicode-encoded script for execution.

JSScript * JS_CompileUCScriptForPrincipals(JSContext *cx, JSObject *obj,JSPrincipals *principals, const jschar *chars, size_t length, const char *filename, uintN lineno); Pointer to a JS context from which to derive runtime information.
Object with which the script is associated.
Pointer to the structure holding the security information for this script.
String containing the script to compile.
Number of Unicode characters in the script to compile.
Name of file or URL containing the script. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
JS_CompileUCScriptForPrincipals compiles a security-enabled script using a Unicode character set, chars, for execution. The script is associated with a JS object.

principals is a pointer to the JSPrincipals structure that contains the security information to associate with this script.

chars is the Unicode string containing the text of the script. length indicates the size of the script in characters.

filename is the name of the file (or URL) containing the script. This information in messages if an eror occurs during compilation. Similarly, lineno is used to report the line number of the script or file where an error occurred during compilation.

If a script compiles successfully, JS_CompileUCScriptForPrincipals returns a pointer to the compiled script. Otherwise JS_CompileUCScriptForPrincipals returns NULL, and reports an error.

Compiles a script stored in an external file.

JSScript * JS_CompileFile(JSContext *cx, JSObject *obj, const char *filename); Pointer to a JS context from which to derive runtime information.
Object with which the script is associated.
Name of file or URL containing the script to compile.
JS_CompileFile compiles the text of script in an external file location for execution by the JS engine.

JS_CompileFile is only available if you compile the JS engine with the JSFILE macro defined.

filename is the name of the file (or URL) containing the script to compile.

If a script compiles successfully, JS_CompileFile returns a pointer to the compiled script. Otherwise JS_CompileFile returns NULL.

To pass a script as an argument to a function rather than having to specify a file location, use JS_CompileScript instead of JS_CompileFile.

Creates a new object and associates a script with it.

JSObject * JS_NewScriptObject(JSContext *cx, JSScript *script); JS_NewScriptObject creates a new object, assigns script to the object, and sets the script's object to the newly created object. Object creation occurs in a specified JSContext, cx.

On success, JS_NewScriptObject returns a pointer to the newly created object. On failure, it returns NULL.

Frees a compiled script when no longer needed.

void) JS_DestroyScript(JSContext *cx, JSScript *script); Pointer to a JS context from which to derive runtime information.
Compiled script to destroy.
JS_DestroyScript destroys the compiled script object, script, thereby freeing the space allocated to it for other purposes. Generally, after you compile a script you do not want to call JS_DestroyScript until you no longer need to use the script. Othewise you will have to recompile the script to use it again.

Creates a JS function from a text string.

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); Pointer to a JS context from which to derive runtime information.
Object with which the function is associated.
Name to assign the newly compiled function.
Number of arguments to pass to the function.
Names to assign to the arguments passed to the function.
String containing the function to compile.
Size, in bytes, of the function to compile.
Name of file or URL containing the function. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
JS_CompileFunction compiles a function from a text string, bytes, and associated it with a JS object, obj.

name is the name to assign to the newly created function. nargs is the number of arguments the function takes, and argnames 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 nargs.

bytes is the string containing the text of the function. length indicates the size of the text version of the function in bytes.

filename is the name of the file (or URL) containing the function. This information in messages if an eror occurs during compilation. Similarly, lineno is used to report the line number of the function or file where an error occurred during compilation.

If a function compiles successfully, JS_CompileFunction returns a pointer to the function. Otherwise JS_CompileFunction returns NULL.

Creates a security-enabled JS function from a text string.

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); Pointer to a JS context from which to derive runtime information.
Object with which the function is associated.
Pointer to the structure holding the security information for this function.
Name to assign the newly compiled function.
Number of arguments to pass to the function.
Names to assign to the arguments passed to the function.
String containing the function to compile.
Size, in bytes, of the function to compile.
Name of file or URL containing the function. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
JS_CompileFunctionForPrincipals compiles a security-enabled function from a text string, bytes, and associated it with a JS object, obj.

principals is a pointer to the JSPrincipals structure that contains the security information to associate with this function.

bytes is the string containing the text of the function. length indicates the size of the text version of the function in bytes.

If a function compiles successfully, JS_CompileFunctionForPrincipals returns a pointer to the function. Otherwise JS_CompileFunctionForPrincipals returns NULL.

Creates a JS function from a Unicode-encoded character string.

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); Pointer to a JS context from which to derive runtime information.
Object with which the function is associated.
Name to assign the newly compiled function.
Number of arguments to pass to the function.
Names to assign to the arguments passed to the function.
Unicode string containing the function to compile.
Size, in Unicode characters, of the function to compile.
Name of file or URL containing the function. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
JS_CompileUCFunction compiles a function from a Unicode-encoded character string, chars, and associated it with a JS object, obj.

chars is the Unicode-encoded string containing the function. length indicates the size of the function in Unicode characters.

If a function compiles successfully, JS_CompileUCFunction returns a pointer to the function. Otherwise JS_CompileUCFunction returns NULL.

Creates a JS function with security informtion from a Unicode-encoded character string.

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); Pointer to a JS context from which to derive runtime information.
Object with which the function is associated.
Pointer to the structure holding the security information for this function.
Name to assign the newly compiled function.
Number of arguments to pass to the function.
Names to assign to the arguments passed to the function.
Unicode string containing the function to compile.
Size, in Unicode characters, of the function to compile.
Name of file or URL containing the function. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
JS_CompileUCFunctionForPrincipals compiles a security-enabled function from a Unicode-encoded character string, chars, and associated it with a JS object, obj.

principals is a pointer to the JSPrincipals structure that contains the security information to associate with this function.

chars is the Unicode-encoded string containing the function. length indicates the size of the function in Unicode characters.

filename is the name of the file (or URL) containing the function. This information is included in messages if an eror occurs during compilation. Similarly, lineno is used to report the line number of the function or file where an error occurred during compilation.

If a function compiles successfully, JS_CompileUCFunctionForPrincipals returns a pointer to the function. Otherwise JS_CompileUCFunctionForPrincipals returns NULL.

Creates the source code of a script from a script's compiled form.

JSString * JS_DecompileScript(JSContext *cx, JSScript *script, const char *name, uintN indent); Pointer to a JS context.
Script to decompile.
Name to assign to the decompiled script.
Number of spaces to use for indented code.
JS_DecompileScript creates the source code version of a script from a script's compiled form, script. name 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.

If successful, JS_DecompileScript returns a string containing the source code of the script. Otherwise, it returns NULL. 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 JS_DecompileFunction on a compiled version of each function to generate the function declarations.

Generates the complete source code of a function declaration from a compiled function.

JSString * JS_DecompileFunction(JSContext *cx, JSFunction *fun, uintN indent); Pointer to a JS context from which to derive runtime information.
Function to decompile.
Number of spaces to use for indented code.
JS_DecompileFunction generates the complete source code of a function declaration from a function's compiled form, fun.

If successful, JS_DecompileFunction returns a string containing the text of the function. Otherwise, it returns NULL.

If you decompile a function that does not make a native C call, then the text created by JS_DecompileFunction 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.

Generates the source code representing the body of a function, minus the function keyword, name, parameters, and braces.

JSString * JS_DecompileFunctionBody(JSContext *cx, JSFunction *fun, uintN indent); Pointer to a JS context from which to derive runtime information.
Function to decompile.
Number of spaces to use for indented code.
JS_DecompileFunctionBody generates the source code of a function's body, minus the function keyword, name, parameters, and braces, from a function's compiled form, fun.

If successful, JS_DecompileFunctionBody returns a string containing the source code of the function body. Otherwise, it returns NULL.

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]".

To decompile a complete function, including its body and declaration, call JS_DecompileFunction instead of JS_DecompileFunctionBody.

Executes a compiled script.

JSBool JS_ExecuteScript(JSContext *cx, JSObject *obj, JSScript *script, jsval *rval); JS context in which the script executes.
Object with which the script is associated.
Previously compiled script to execute.
Pointer to the value from the last executed expression statement processed in the script.
JS_ExecuteScript executes a previously compiled script, script. On successful completion, rval is a pointer to a variable that holds the value from the last executed expression statement processed in the script.

If a script executes successfully, JS_ExecuteScript returns JS_TRUE. Otherwise it returns JS_FALSE. On failure, your application should assume that rval is undefined.

To execute an uncompiled script, compile it with JS_CompileScript, and then call JS_ExecuteScript, or call JS_EvaluateScript to both compile and execute the script.

Compiles and executes a script.

JSBool JS_EvaluateScript(JSContext *cx, JSObject *obj, const char *bytes, uintN length, const char *filename, uintN lineno, jsval *rval); JS context in which the script compiles and executes.
Object with which the script is associated.
String containing the script to compile and execute.
Size, in bytes, of the script to compile and execute.
Name of file or URL containing the script. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
Pointer to the value from the last executed expression statement processed in the script.
JS_EvaluateScript compiles and executes a script associated with a JS object, obj. On successful completion, rval is a pointer to a variable that holds the value from the last executed expression statement processed in the script.

bytes is the string containing the text of the script. length indicates the size of the text version of the script in bytes.

If a script compiles and executes successfully, JS_EvaluateScript returns JS_TRUE. Otherwise it returns JS_FALSE. On failure, your application should assume that rval is undefined.

Compiles and executes a Unicode-encoded script.

JSBool JS_EvaluateUCScript(JSContext *cx, JSObject *obj, const jschar *chars, uintN length, const char *filename, uintN lineno, jsval *rval); JS context in which the script compiles and executes.
Object with which the script is associated.
Unicode character array ontaining the script to compile and execute.
Size, in Unicode characters, of the script to compile and execute.
Name of file or URL containing the script. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
Pointer to the value from the last executed expression statement processed in the script.
JS_EvaluateUCScript compiles and executes a script associated with a JS object, obj. On successful completion, rval is a pointer to a variable that holds the value from the last executed expression statement processed in the script.

chars is the Unicode character array containing the text of the script. length indicates the size of the text version of the script in Unicode characters.

filename is the name of the file (or URL) containing the script. This information is included in messages if an eror occurs during compilation. Similarly, lineno is used to report the line number of the script or file where an error occurred during compilation.

If a script compiles and executes successfully, JS_EvaluateUCScript returns JS_TRUE. Otherwise it returns JS_FALSE. On failure, your application should assume that rval is undefined.

Compiles and executes a security-enabled script.

JSBool JS_EvaluateScriptForPrincipals(JSContext *cx, JSObject *obj, JSPrincipals *principals, const char *bytes, uintN length, const char *filename, uintN lineno, jsval *rval); JS context in which the script compiles and executes.
Object with which the script is associated.
Pointer to the structure holding the security information for this script.
String containing the script to compile and execute.
Size, in bytes, of the script to compile and execute.
Name of file or URL containing the script. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
Pointer to the value from the last executed expression statement processed in the script.
JS_EvaluateScriptForPrincipals compiles and executes a script associated with a JS object, obj. On successful completion, rval is a pointer to a variable that holds the value from the last executed expression statement processed in the script.

principals is a pointer to the JSPrincipals structure that contains the security information to associate with this script.

bytes is the string containing the text of the script. length indicates the size of the text version of the script in bytes.

If a secure script compiles and executes successfully, JS_EvaluateScriptForPrincipals returns JS_TRUE. Otherwise it returns JS_FALSE. On failure, your application should assume that rval is undefined.

Compiles and executes a security-enabled,Unicode-encoded character script.

JSBool JS_EvaluateScriptUCForPrincipals(JSContext *cx, JSObject *obj, JSPrincipals *principals, const jschar *chars, uintN length, const char *filename, uintN lineno, jsval *rval); JS context in which the script compiles and executes.
Object with which the script is associated.
Pointer to the structure holding the security information for this script.
Unicode-encoded character array containing the script to compile and execute.
Size, in Unicode characters, of the script to compile and execute.
Name of file or URL containing the script. Used to report filename or URL in error messages.
Line number. Used to report the offending line in the file or URL if an error occurs.
Pointer to the value from the last executed expression statement processed in the script.
JS_EvaluateUCScriptForPrincipals compiles and executes a Unicode-encoded script associated with a JS object, obj. On successful completion, rval is a pointer to a variable that holds the value from the last executed expression statement processed in the script.

principals is a pointer to the JSPrincipals structure that contains the security information to associate with this script.

chars is the Unicode-encoded character array containing the text of the script. length indicates the number of characters in the text version of the script.

If a secure script compiles and executes successfully, JS_EvaluateUCScriptForPrincipals returns JS_TRUE. Otherwise it returns JS_FALSE. On failure, your application should assume that rval is undefined.

Calls a specified function.

JSBool JS_CallFunction(JSContext *cx, JSObject *obj, JSFunction *fun, uintN argc, jsval *argv, jsval *rval); Pointer to a JS context from which to derive runtime information.
The "current" object on which the function operates; the object specified here is "this" when the function executes.
Pointer to the function to call.
Number of arguments you are passing to the function.
Pointer to the array of argument values to pass to the function.
Pointer to a variable to hold the return value from the function call.
JS_CallFunction calls a specified function, fun, on an object, obj. In terns of function execution, the object is treated as this.

To call a method on an object, use JS_CallFunctionName.

In argc, indicate the number of arguments passed to the function. In argv, 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.

rval is a pointer to a variable that will hold the function's return value, if any, on successful function execution.

If the called function executes successfully, JS_CallFunction returns JS_TRUE. Otherwise it returns JS_FALSE, and rval is undefined.

Calls a function-valued property belonging to an object.

JSBool JS_CallFunctionName(JSContext *cx, JSObject *obj, const char *name, uintN argc, jsval *argv, jsval *rval); Pointer to a JS context from which to derive runtime information.
The object containing the method to execute.
The name of the function to execute.
Number of arguments you are passing to the function.
Pointer to the array of argument values to pass to the function.
Pointer to a variable to hold the return value from the function call.
JS_CallFunctionName executes a function-valued property, name, belonging to a specified JS object, obj.

To call a function stored in a jsval, use JS_CallFunctionValue.

rval is a pointer to a variable that will hold the function's return value, if any, on successful function execution.

If the called function executes successfully, JS_CallFunctionName returns JS_TRUE. Otherwise it returns JS_FALSE, and rval is undefined.

Calls a function referenced by a jsval.

JSBool JS_CallFunctionValue(JSContext *cx, JSObject *obj, jsval fval, uintN argc, jsval *argv, jsval *rval); Pointer to a JS context from which to derive runtime information.
The "current" object on which the function operates; the object specified here is "this" when the function executes.
The jsval containing the function to execute.
Number of arguments you are passing to the function.
Pointer to the array of argument values to pass to the function.
Pointer to a variable to hold the return value from the function call.
JS_CallFunctionValue executes a function referenced by a jsval, fval, on an object, obj. In terns of function execution, the object is treated as this.

rval is a pointer to a variable that will hold the function's return value, if any, on successful function execution.

If the called function executes successfully, JS_CallFunctionValue returns JS_TRUE. Otherwise it returns JS_FALSE, and rval is undefined.

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.

JSBranchCallback JS_SetBranchCallback(JSContext *cx, JSBranchCallback cb); Pointer to a JS context from which to derive runtime information.
The object that encapsulates the callback function.
JS_SetBranchCallback 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.

Indicates whether or not a script or function is currently executing in a given context.

JSBool JS_IsRunning(JSContext *cx); JS_IsRunning determines if a script or function is currently executing in a specified JSContext, cx. If a script is executing, JS_IsRunning returns JS_TRUE. Otherwise it returns JS_FALSE.

Indicates the current constructor status of a given context.

JSBool JS_IsConstructing(JSContext *cx); JS_IsConstructing determines whether or not a function constructor is in action within a given context, cx. If it is, JS_IsConstructing returns JS_TRUE. Otherwise it returns JS_FALSE.

Allocates a new JS string.

JSString * JS_NewString(JSContext *cx, char *bytes, size_t length); Pointer to a JS context from which to derive runtime information.
Pointer to the byte array containing the text for the JS string to create.
Number of characters in the text string.
JS_NewString uses the memory starting at bytes and ending at bytes + length as storage for the JS string it returns. The char array, bytes, must be allocated on the heap using JS_malloc. 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.

Using JS_NewString is analogous to assigning char * variables in C, and can save needless copying of data. If successful, JS_NewString returns a pointer to the JS string. Otherwise it returns NULL.

Allocates a new JS Unicode-encoded string.

JSString * JS_NewUCString(JSContext *cx, jschar *chars, size_t length); Pointer to a JS context from which to derive runtime information.
Pointer to the Unicode-encoded character array containing the text for the JS string to create.
Number of characters in the text string.
JS_NewUCString uses the memory starting at chars and ending at chars + length 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.

Using JS_NewUCString is analogous to assigning char * variables in C, and can save needless copying of data. If successful, JS_NewUCString returns a pointer to the JS string. Otherwise it returns NULL.

Creates a new JS string of a specified size.

JSString * JS_NewStringCopyN(JSContext *cx, const char *s, size_t n); Pointer to a JS context from which to derive runtime information.
Pointer to the character array containing the text for the JS string to create.
Maximum number of characters to copy from s into the JS string.
JS_NewStringCopyN allocates space for a JS string and its underlying storage, and copies as many characters from a C character array, s, as possible, up to n bytes, into the new JS string. If the number of bytes in s is greater than the number of characters specified in n, the new JS string contains a truncated version of the original string. If the number of characters in s is less than the number of bytes specified in n, the new JS string is padded with nulls to the specified length.

You can use JS_NewStringCopyN 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.

If the allocation is successful, JS_NewStringCopyN returns a pointer to the JS string. Otherwise it returns NULL.

Creates a new Unicode-encoded JS string of a specified size.

JSString * JS_NewUCStringCopyN(JSContext *cx, const jschar *s, size_t n); Pointer to a JS context from which to derive runtime information.
Pointer to the Unicode character array containing the text for the JS string to create.
Maximum number of Unicode characters to copy from s into the JS string.
JS_NewUCStringCopyN allocates space for a JS string and its underlying storage, and copies as many characters from a Unicode-encoded character array, s, as possible, up to n characters, into the new JS string. If the number of characters in s is greater than the number of characters specified in n, the new JS string contains a truncated version of the original string. If the number of characters in s is less than the number of bytes specified in n, the new JS string is padded with nulls to the specified length.

You can use JS_NewUCStringCopyN 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.

If the allocation is successful, JS_NewUCStringCopyN returns a pointer to the JS string. Otherwise it returns NULL.

Creates a new JS string and ensures that the resulting string is null-terminated.

JSString * JS_NewStringCopyZ(JSContext *cx, const char *s); Pointer to a JS context from which to derive runtime information.
Pointer to the character array containing the text for the JS string to create.
JS_NewStringCopyZ allocates space for a new JS string and its underlying storage, and then copies the contents of a C character array, s, into the new string. The new JS string is guaranteed to be null-terminated.

If the allocation is successful, JS_NewStringCopyZ returns a pointer to the JS string. Otherwise it returns an empty string.

Creates a new Unicode-encoded JS string and ensures that the resulting string is null-terminated.

JSString * JS_NewUCStringCopyZ(JSContext *cx, const jschar *s); Pointer to a JS context from which to derive runtime information.
Pointer to the character array containing the text for the JS string to create.
JS_NewUCStringCopyZ allocates space for a new, Unicode-encoded JS string and its underlying storage, and then copies the contents of a character array, s, into the new string. The new JS string is guaranteed to be null-terminated.

If the allocation is successful, JS_NewUCStringCopyZ returns a pointer to the JS string. Otherwise it returns an empty string.

Creates a new, static JS string whose value is automatically shared by all string literals that are identical.

JSString * JS_InternString(JSContext *cx, const char *s); Pointer to a JS context from which to derive runtime information.
Pointer to the character array containing the text for the JS string to create.
JS_InternString creates a new JS string with a specified value, s, if it does not already exist. The char array, s, must be allocated on the heap. The JS string is an interned, Unicode version of s, meaning that independent C variables that define a matching string will, when translated to a JS string value using JS_InternString, 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.

If it creates or reuses an interned string, JS_InternString returns a pointer to the string. Otherwise, on error, it returns NULL.

Creates a new, static, Unicode-encoded JS string whose value is automatically shared by all string literals that are identical.

JSString * JS_InternUCString(JSContext *cx, const jschar *s); JS_InternUCString creates a new, Unicode-encoded JS string with a specified value, s, if it does not already exist. The char array, s, must be allocated on the heap. The JS string is an interned, Unicode version of s, meaning that independent C variables that define a matching string will, when translated to a JS string value using JS_InternUCString, 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.

If it creates or reuses an interned string, JS_InternUCString returns a pointer to the string. Otherwise, on error, it returns NULL.

Creates a new, static, Unicode-encoded, JS string of a specified size whose value is automatically shared by all string literals that are identical.

JSString * JS_InternUCStringN(JSContext *cx, const jschar *s, size_t length); JS_InternUCStringN creates a new, Unicode-encoded JS string with a specified value, s, up to length characters in size, if it does not already exist. If the number of characters in s is greater than the number of characters specified in length, the new JS string contains a truncated version of the original string. If the number of characters in s is less than the number of bytes specified in length, the new JS string is padded with nulls to the specified length.

The char array, s, must be allocated on the heap. The JS string is an interned, Unicode version of s, meaning that independent C variables that define a matching string will, when translated to a JS string value using JS_InternUCStringN, 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.

If it creates or reuses an interned string, JS_InternUCStringN returns a pointer to the string. Otherwise, on error, it returns NULL.

Retrieves the pointer to a specified string.

jschar * JS_GetStringChars(JSString *str); JS_GetStringChars provides a Unicode-enabled pointer to a JS string, str.

Translates a JS string into a C character array.

char * JS_GetStringBytes(JSString *str); JS_GetStringBytes translates a specified JS string, str, into a C character array. If successful, JS_GetStringBytes returns a pointer to the array. The array is automatically freed when str is finalized by the JavaScript garbage collection mechanism.

Determines the length, in characters, of a JS string.

size_t JS_GetStringLength(JSString *str); JS_GetStringLength reports the length, in characters, of a specified JS string, str. Note that JS strings are stored in Unicode format, so JS_GetStringLength does not report the number of bytes allocated to a string, but the number of characters in the string.

Compares two JS strings, and reports the results of the comparison.

intN JS_CompareStrings(JSString *str1, JSString *str2); First string to compare.
Second string to compare.
JS_CompareStrings compares two JS strings, str1 and str2. If the strings are identical in content and size, JS_CompareStrings returns 0.

If str1 is greater than str2, either in terms of its internal alphabetic sort order, or because it is longer in length, JS_CompareStrings returns a positive value.

If str1 is less than str2, either in terms of its internal alphabetic sort order, or because it is shorter in length, JS_CompareStrings returns a negative value.

Creates a formatted error message to pass to a user-defined error reporting function.

void JS_ReportError(JSContext *cx, const char *format, ...); Pointer to a JS context from which to derive runtime information.
Format string to convert into an error message using a standard C sprintf conversion routine.
Error message variables to insert into the format string.
JS_ReportError converts a format string and its arguments, format, 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.

Specify an error reporting mechanism for your application using JS_SetErrorReporter.

Reports a memory allocation error for a specified JS execution context.

void JS_ReportOutOfMemory(JSContext *cx); JS_ReportOutOfMemory calls JS_ReportError 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.

Specifies the error reporting mechanism for an application.

JSErrorReporter JS_SetErrorReporter(JSContext *cx, JSErrorReporter er); Pointer to a JS context from which to derive runtime information.
The user-defined error reporting function to use in your application.
JS_SetErrorReporter enables you to define and use your own error reporting mechanism in your applications. The reporter you define is automatically passed a JSErrorReport structure when an error occurs and has been parsed by JS_ReportError.

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 JSErrorReport structure.