Obsolete since JSAPI 39
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.
Sets the parent for an object.
Syntax
bool JS_SetParent(JSContext *cx, JS::HandleObject obj, JS::HandleObject parent);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
Pointer to a JS context from which to derive runtime information. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext. |
obj |
JS::HandleObject |
Pointer to the object for which to set the parent. This must be an object that has not yet been exposed to script. See the Description for details. |
parent |
JS::HandleObject |
Pointer to the parent object to use. |
Description
JS_SetParent sets an object's parent.
Each object may have at most one parent, which is another object. Applications that use SpiderMonkey's security features typically use the parent relation to determine both (a) what security principals are attached to the currently executing script; and (b) what security principals are attached to the object being accessed. (For some function objects, the parent chain is also used to implement lexical scoping, but this should be considered an implementation detail.)
Ordinarily an application sets a new object's parent by passing the parent object to JS_NewObject, and that is the preferred approach. But an application may instead use JS_SetParent after the object is created.
Applications can get an object's parent using JS_GetParent. Scripts can determine an object's parent by using the __parent__ property, but scripts cannot assign to the __parent__ property. In fact, once an object is exposed to a script, the object's parent must not change. The JavaScript engine relies on this invariant. JS_SetParent has no way to check that this is the case, but nonetheless, applications must not call JS_SetParent on an object that has already been exposed to a script. If an application does this, the behavior is undefined.
On success, JS_SetParent returns JS_TRUE. Otherwise, it reports an error or sets an exception and returns JS_FALSE.
See Also
- MXR ID Search for
JS_SetParent - bug 1136980 - removed