JS_DefineProperty

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 JS::HandleId 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, and attrs) governing the new property's behavior;
  • it never calls a setter;
  • it can call the JSClass.addProperty callback when JS_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

Document Tags and Contributors

Tags: 
 Contributors to this page: arai, fscholz, Norbert, dreddfoxx, Jorend, Dria, MMondor
 Last updated by: arai,