Create a new property on an object.
Syntax
bool JS_DefineProperty(JSContext *cx, JS::HandleObject obj, const char *name, JS::HandleValue value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineProperty(JSContext *cx, JS::HandleObject obj, const char *name, JS::HandleObject value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineProperty(JSContext *cx, JS::HandleObject obj, const char *name, JS::HandleString value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineProperty(JSContext *cx, JS::HandleObject obj, const char *name, int32_t value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineProperty(JSContext *cx, JS::HandleObject obj, const char *name, uint32_t value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineProperty(JSContext *cx, JS::HandleObject obj, const char *name, double value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen, JS::HandleValue value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen, JS::HandleObject value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen, JS::HandleString value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen, int32_t value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen, uint32_t value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefineUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen, double value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); // ---- Added in SpiderMonkey 45 ---- bool JS_DefinePropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, JS::Handle<JSPropertyDescriptor> desc, JS::ObjectOpResult &result); bool JS_DefinePropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, JS::Handle<JSPropertyDescriptor> desc); bool JS_DefineUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen, JS::Handle<JSPropertyDescriptor> desc); // ---- Added in SpiderMonkey 1.8.1 ---- bool JS_DefinePropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, JS::HandleValue value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefinePropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, JS::HandleObject value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefinePropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, JS::HandleString value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefinePropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, int32_t value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefinePropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, uint32_t value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr); bool JS_DefinePropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, double value, unsigned attrs, JSNative getter = nullptr, JSNative setter = nullptr);
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 |
JS::HandleObject |
The object on which to create the new property. |
name or id |
const char * or const char16_t *or |
The name of the new property. |
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 |
JS::HandleValue or JS::HandleObject or JS::HandleString or int32_t or uint32_t or double |
Initial stored value for the new property. |
getter |
JSNative |
The property getter callback, which the JavaScript engine will call each time the property's value is accessed; or NULL . |
setter |
JSNative |
The property setter callback, which the JavaScript engine will call each time the property is assigned; or NULL . |
attrs |
unsigned |
Property attributes. |
desc |
JS::Handle<JSPropertyDescriptor> |
The property descriptor for the property to be defined. |
result |
JS::ObjectOpResult & |
(out parameter) Receives the result of the operation. |
Description
JS_DefineProperty
defines a single property in a specified object, obj
. JS_DefineUCProperty
is the Unicode version of the function. JS_DefinePropertyById
is the same but takes a JS::HandleId
for the property name.
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
, andattrs
) governing the new property's behavior; - it never calls a setter;
- it can call the
JSClass.addProperty
callback whenJS_SetProperty
would not, because it can replace an existing property.
The parameters specify the new property's name
, initial stored value
, getter
, setter
, and Property attributes (attrs
).
If obj
already has an own property with the given name
or id
, the existing property is replaced. These functions can currently replace JSPROP_PERMANENT
properties, but such usage is deprecated.
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 fail before it gets that far. Also note that certain JSAPI functions, including JS_LookupProperty
, JS_HasProperty
, and Property_attributes
, can detect or examine a property without calling its getter.) 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 true
. On error or exception, it returns false
.
See Also
- MXR ID Search for
JS_DefineProperty
- MXR ID Search for
JS_DefineUCProperty
- MXR ID Search for
JS_DefinePropertyById
JS_DefineElement
- bug 461163
- bug 1113369 -- added
desc
andresult
parameters