JSPropertyOp

この記事はまだ日本語に翻訳されていません。MDN の翻訳はボランティアによって行われています。是非 MDN に登録し、私たちの力になって下さい。

JSPropertyOp is the type of property getter and setter callbacks in the JSAPI.

It is also the type of the JSClass.addProperty, delProperty, getProperty, and setProperty callbacks, which are called during object property accesses.

Syntax

typedef JSBool (*JSPropertyOp)(
    JSContext *cx, JSObject *obj, jsval idval, jsval *vp); JSAPI 1.8 and earlier
typedef JSBool (*JSPropertyOp)(
    JSContext *cx, JSObject *obj, jsid id, jsval *vp); Added in SpiderMonkey 1.8.1
Name Type Description
cx JSContext *

The context in which the property access is taking place.

Provides request. In JS_THREADSAFE builds, the JavaScript engine calls this callback only from within an active request on cx. The callback does not need to call JS_BeginRequest()).

obj JSObject * The object whose properties are being accessed.
idval jsval JSAPI 1.8 and earlier The name or index of the property being accessed. This is either a string (Unicode property identifier) or an integer (element index).
id jsid Added in SpiderMonkey 1.8.1 The name or index of the property being accessed. This is either a string (Unicode property identifier) or an integer (element index).
vp jsval * In/out parameter. Points to a jsval variable. The meaning of this variable is different for each of the hooks; see below.

Description

JSPropertyOp callbacks are hooks that applications may install to be called at some point during property access. A JSPropertyOp may be installed on an individual property as a getter or setter; or it may be installed on a JSClass to hook property gets, sets, adds, or deletes. These different cases are described in more detail in the sections below.

If a JSPropertyOp does nothing and returns JS_TRUE, then property get, set, add, or delete is unaffected. It proceeds as normal. (Contrast JSObjectOps.getProperty and friends, which implement all 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.

Getters and setters

When a JSAPI application creates a property on an object (for example, using JS_DefineProperty or JS_DefineProperties) it can specify getter and setter callbacks for the new property.

Getters. The getter callback is called each time JavaScript code accesses the property's value using the syntax obj.prop or obj[propname]. It is also called when the property's value is accessed via JSAPI functions such as JS_GetProperty or (less obviously) JS_CallFunctionName. On entry, *vp contains the property's stored value or JSVAL_VOID if the property doesn't have a stored value. The callback may modify *vp. On success, the callback returns JS_TRUE and the value left in *vp is returned to the script or JSAPI caller.

Setters. The setter callback is called each time JavaScript code assigns to the property using any assignment operator (=, +=, etc.) or the ++ or -- operators. It is also called when the property is set via JSAPI functions such as JS_SetProperty. On entry, *vp contains the value being assigned to the property. The callback may modify *vp. On success, the callback returns JS_TRUE. If the property has a stored value, it is then updated to the value left in *vp after the callback.

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.

Inherited properties. Note that in JavaScript, an object can inherit properties from its prototype. Getters (and sometimes setters; see JS_SetProperty for details) are called even when the property being accessed is found on a prototype and not on obj itself.  In this case obj points to the object from which the property is being accessed, not the object on which the property was defined.

JSClass hooks

JSClass offers four hooks of type JSPropertyOp.

  • JSClass.addProperty is called just after 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.

    In JS_THREADSAFE builds, this callback is called with obj locked. It is therefore dangerous for the callback to call JSAPI functions, particularly if obj may have been visible to more than one thread.

  • JSClass.getProperty is the default getter for new properties. See the section on getters and setters above.

    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. See the section on getters and setters above.

    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.

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

    JS_ClearScope does not call this hook either.

Document Tags and Contributors

Contributors to this page: Philip Taylor, Jorend
最終更新者: Philip Taylor,