JSClass.addProperty

Syntax

typedef JSBool (*JSPropertyOp)(
    JSContext *cx, JSObject *obj, jsval id, jsval *vp);

Description

Add, delete, get or set a property named by id in obj. These callbacks are hooks that are called at some point during property access. If one of these callbacks does nothing and returns JS_TRUE, then property access is unaffected. Contrast JSObjectOps.getProperty and friends, which implement the nuts and bolts of property access.

Each of these callbacks may veto the ongoing property operation by optionally reporting an error or raising an exception and then returning JS_FALSE. The operation then fails, and the error is propagated to the caller. Otherwise the callback must return JS_TRUE, and the property operation proceeds.

JSPropertyOp is also the type of property getter and setter callbacks. See JS_DefineProperty, JS_DefineProperties, and JS_GetPropertyAttrsGetterAndSetter.

• JSClass.addProperty is called just before a new property is added to an object. This happens when a program sets a property that isn't already an own property of the target object. It also happens in JSAPI functions such as JS_DefineProperty. On entry, *vp contains the value provided by the code defining or setting the property. The callback may modify *vp. On success, the post-callback value of *vp becomes the initial stored value of the new property.

• JSClass.getProperty is the default getter for new properties. A property's getter is called each time the property's value is retrieved. JSClass.getProperty is also called when a program attempts to get a property that does not exist on obj or any prototype.

  On entry, *vp contains the property's stored value, or JSVAL_VOID if the property doesn't exist or doesn't have a stored value. The callback may modify *vp. On success, the post-callback value of *vp is returned to the caller. This value also becomes the property's new stored value, if the property exists and has a stored value.

• JSClass.setProperty is the default setter for new properties.

  A property's setter is called each time the property is assigned. (Hence when a script assigns to a nonexisting property, first the object's class's addProperty hook is called, then the setProperty hook.) On entry, *vp contains the value being assigned to the property. The callback may modify *vp. On success, if the property has a stored value, it is updated to the post-callback value of *vp.

  As of SpiderMonkey 1.7, the value of a property assignment expression, like (a.length = x), is the value of *vp after the setter is called. This is typically the value of the left-hand side after assignment, as opposed to the value of the right-hand side, as required by ECMA 262-3 §11.13 . This ECMAScript incompatibility is observable when assigning to the length property of an Array, for example. This incompatibility will be fixed in SpiderMonkey 1.8; see bug 312354 .

• JSClass.delProperty is called during most property deletions, even when obj has no property named id. On entry, *vp is JSVAL_TRUE. The callback may change it to JSVAL_FALSE and return JS_TRUE to indicate that obj[id] can't be deleted (because it's permanent).

  This hook is not called when the target property is JSPROP_PERMANENT and is an own property of the target object. An attempt to delete such a property fails early, returning false, before the delProperty hook is reached.