JS DefineProperty

From MDC

Create a new property on an object.

[edit] Syntax

JSBool JS_DefineProperty(JSContext *cx, JSObject *obj,
    const char *name, jsval value, JSPropertyOp getter,
    JSPropertyOp setter, uintN attrs);

JSBool JS_DefineUCProperty(JSContext *cx, JSObject *obj,
    const jschar *name, size_t namelen, jsval value,
    JSPropertyOp getter, JSPropertyOp setter, uintN attrs);

Name	Type	Description
cx	JSContext *	The context in which to define the property. Requires request. (In a JS_THREADSAFE build, the caller must be in a request on this JSContext.)
obj	JSObject *	The object on which to create the new property.
name	const char * or const jschar *	Name for the property to create.
namelen	size_t	(only in JS_DefineUCProperty) The length of name, in characters; or (size_t) -1 to indicate that name is null-terminated.
value	jsval	Initial stored value for the new property.
getter	JSPropertyOp	The property getter callback, which the JavaScript engine will call each time the property's value is accessed; or NULL.
setter	JSPropertyOp	The property setter callback, which the JavaScript engine will call each time the property is assigned; or NULL.
attrs	uintN	Property attributes.

[edit] Description

JS_DefineProperty defines a single property in a specified object, obj. JS_DefineUCProperty is the Unicode version of the function.

JS_DefineProperty is the fundamental operation on which several more convenient, higher-level functions are based, including JS_DefineFunction, JS_DefineFunctions, JS_DefineProperties, JS_DefineConstDoubles, JS_DefineObject, and JS_InitClass. It differs from JS_SetProperty in that:

• it does not behave like ordinary property assignment in the JavaScript language;
• it allows the application to specify additional details (getter, setter, and attrs) governing the new property's behavior, beyond what JavaScript code is allowed to specify; and
• it reports an error if obj already has an own property with the specified name.

The parameters specify the new property's name, initial stored value, getter, setter, and property attributes (attrs).

The JavaScript engine will call the getter or setter callback each time the property is read or written, whether from JavaScript code or via JSAPI functions like JS_GetProperty and JS_SetProperty. (Exception: If attrs contains the JSPROP_READONLY flag, the setter will never be called, as property assignment will silently fail before it gets that far.) If getter (or setter) is NULL, the new property will use the JSClass.getProperty (or JSClass.setProperty) callback from obj's class.

If attrs contains the JSPROP_GETTER (or JSPROP_SETTER) flag, then getter (or setter) must point to a JavaScript Function, not a C/C++ function. That is, it must be a JSObject * that points to a JavaScript Function, cast to type JSPropertyOp. For more about JavaScript getters and setters, see Defining Getters and Setters.

On success, JS_DefineProperty returns JS_TRUE. If the property already exists or cannot be created, JS_DefineProperty returns JS_FALSE.

[edit] See Also

LXR ID Search for JS_DefineProperty
LXR ID Search for JS_DefineUCProperty

JS_DefineElement, JS_DefinePropertyWithTinyId