Obsolete since JSAPI 16
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
As of SpiderMonkey 1.8.8, JS_ConstructObject and JS_ConstructObjectWithArguments have been removed from the JSAPI. The preferred alternative is to save a copy of the constructor function for the class, then to call it using JS_New. A less-preferred short-term solution might be to use this reimplementation of the method, but note that this reimplementation is not guaranteed to continue working across SpiderMonkey releases.
Syntax
JSObject *
JS_ConstructObject(JSContext *cx, JSClass *clasp,
JSObject *proto, JSObject *parent);
JSObject *
JS_ConstructObjectWithArguments(JSContext *cx, JSClass *clasp,
JSObject *proto, JSObject *parent, unsigned int argc, jsval *argv);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
The context in which to create the new object. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext. |
clasp |
JSClass * |
Pointer to the class to use for the new object. If this is NULL, an ordinary JavaScript Object is created. |
proto |
JSObject * |
The object to serve as the new object's prototype, or NULL. |
parent |
JSObject * |
The object to serve as the new object's parent, or NULL. |
argc |
unsigned int |
(only in JS_ConstructObjectWithArguments) The number of arguments to pass to the constructor. |
argv |
jsval * |
(only in JS_ConstructObjectWithArguments) The array of arguments to pass to the constructor. This may be null if argc is zero. Otherwise, the first argc elements of this array must be populated with valid jsval values. The caller does not need to ensure that the array elements are rooted. |
Description
JS_ConstructObject creates a new object of the specified class, with the specified prototype and parent, then invokes a constructor function to initialize the new object. cx is a pointer to a context associated with the runtime in which to create the new object. clasp is a pointer to the class of object to create. proto and parent may specify objects to be used as the new object's prototype and parent. If either is NULL, the engine tries to find reasonable defaults.
JS_ConstructObjectWithArguments is the same but additionally passes zero or more arguments to the constructor.
Neither of these functions is quite like the JavaScript new keyword.
For details on how we find the appropriate constructor and default prototype, see JS_NewObject: Choosing a Default Prototype. Roughly speaking, we use parent or cx to find a global object, and then find clasp's constructor in that global object.
If parent is NULL, the engine chooses an object to serve as the new object's parent.
On success, JS_ConstructObject returns a pointer to the newly instantiated object. Otherwise it returns NULL.
The new object created by these functions is subject to garbage collection. The object should be made GC-reachable immediately. See the JSAPI User Guide.