JS_DefineProperty

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_DefineProperty
  • Revision title: JS_DefineProperty
  • Revision id: 79296
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment no wording changes

Revision Content

Create a new property on an object.

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);

JSBool JS_DefinePropertyById(JSContext *cx, JSObject *obj,
    jsid id, jsval value, JSPropertyOp getter,
    JSPropertyOp setter, uintN attrs); {{ jsapi_minversion_inline("1.8.1 (not yet released)") }}
Name Type Description
cx JSContext * The context in which to define the property. {{ Jsapi-requires-request() }}
obj JSObject * The object on which to create the new property.
name or id const char * or const jschar * or jsid 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 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.

 

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 jsid 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, beyond what JavaScript code is allowed to specify;
  • 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).

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.  Also note that certain JSAPI functions, including JS_LookupProperty, JS_HasProperty, and JS_GetPropertyAttributes, 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 JS_TRUE. If the property already exists or cannot be created, JS_DefineProperty returns JS_FALSE.

See Also

{{ LXRSearch("ident", "i", "JS_DefineProperty") }}
{{ LXRSearch("ident", "i", "JS_DefineUCProperty") }}
{{ LXRSearch("ident", "i", "JS_DefinePropertyById") }}

JS_DefineElement, JS_DefinePropertyWithTinyId

Revision Source

<p>Create a new property on an object.</p>
<h2 name="Syntax">Syntax</h2>
<pre class="eval"><a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> <strong>JS_DefineProperty</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *obj,
    const char *name, <a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="en/jsval">jsval</a> value, <a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSPropertyOp</a> getter,
    <a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSPropertyOp</a> setter, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> attrs);

<a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> <strong>JS_DefineUCProperty</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *obj,
    const <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *name, size_t namelen, <a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="en/jsval">jsval</a> value,
    <a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSPropertyOp</a> getter, <a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSPropertyOp</a> setter, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> attrs);

<a href="/En/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a> <strong>JS_DefinePropertyById</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *obj,
    <a href="/en/SpiderMonkey/JSAPI_Reference/jsid" title="en/SpiderMonkey/JSAPI_Reference/jsid">jsid</a> id, <a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="en/jsval">jsval</a> value, <a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSPropertyOp</a> getter,
    <a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSPropertyOp</a> setter, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a> attrs); {{ jsapi_minversion_inline("1.8.1 (not yet released)") }}
</pre>
<table class="fullwidth-table"> <tbody> <tr> <th>Name</th> <th>Type</th> <th>Description</th> </tr> <tr> <td><code>cx</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *</code></td> <td>The context in which to define the property. {{ Jsapi-requires-request() }}</td> </tr> <tr> <td><code>obj</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSObject" title="en/JSObject">JSObject</a> *</code></td> <td>The object on which to create the new property.</td> </tr> <tr> <td><code>name</code> <em>or<em> <code>id</code></em></em></td> <td><code>const char *</code> <em>or</em> <code>const <a href="/en/SpiderMonkey/JSAPI_Reference/jschar" title="en/jschar">jschar</a> *</code> <em>or</em> <a href="/en/SpiderMonkey/JSAPI_Reference/jsid" title="en/SpiderMonkey/JSAPI_Reference/jsid"><code>jsid</code></a></td> <td>The name of the new property.</td> </tr> <tr> <td><code>namelen</code></td> <td><code>size_t</code></td> <td><em>(only in <code>JS_DefineUCProperty</code>)</em> The length of <code>name</code>, in characters; or <code>(size_t) -1</code> to indicate that <code>name</code> is null-terminated.</td> </tr> <tr> <td><code>value</code></td> <td><code><a href="/En/SpiderMonkey/JSAPI_Reference/Jsval" title="en/jsval">jsval</a></code></td> <td>Initial <a href="/En/SpiderMonkey/JSAPI_Reference/Stored_value" title="en/JSAPI/Stored_value">stored value</a> for the new property.</td> </tr> <tr> <td><code>getter</code></td> <td><code><a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSPropertyOp</a></code></td> <td>The property getter callback, which the JavaScript engine will call each time the property's value is accessed; or <code>NULL</code>.</td> </tr> <tr> <td><code>setter</code></td> <td><code><a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSPropertyOp</a></code></td> <td>The property setter callback, which the JavaScript engine will call each time the property is assigned; or <code>NULL</code>.</td> </tr> <tr> <td><code>attrs</code></td> <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uintN</a></code></td> <td><a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes" title="en/SpiderMonkey/JSAPI Reference/JS GetPropertyAttributes#Property_attributes">Property attributes</a>.</td> </tr> </tbody>
</table>
<p> </p><h2 name="Description">Description</h2>
<p><strong><code>JS_DefineProperty</code></strong> defines a single property in a specified object, <code>obj</code>. <strong><code>JS_DefineUCProperty</code></strong> is the Unicode version of the function. <strong><code>JS_DefinePropertyById</code></strong> is the same but takes a <a href="/en/SpiderMonkey/JSAPI_Reference/jsid"><code>jsid</code></a> for the property name.</p>
<p><code>JS_DefineProperty</code> is the fundamental operation on which several more convenient, higher-level functions are based, including <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineFunction" title="en/JS_DefineFunction">JS_DefineFunction</a></code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineFunctions" title="en/JS_DefineFunctions">JS_DefineFunctions</a></code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineProperties" title="en/JS_DefineProperties">JS_DefineProperties</a></code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineConstDoubles" title="en/JS_DefineConstDoubles">JS_DefineConstDoubles</a></code>, <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineObject" title="en/JS_DefineObject">JS_DefineObject</a></code>, and <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_InitClass" title="en/JS_InitClass">JS_InitClass</a></code>. It differs from <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetProperty" title="en/JS_SetProperty">JS_SetProperty</a></code> in that:</p>
<ul> <li>it does not behave like ordinary property assignment in the JavaScript language;</li> <li>it allows the application to specify additional details (<code>getter</code>, <code>setter</code>, and <code>attrs</code>) governing the new property's behavior, beyond what JavaScript code is allowed to specify;</li> <li>it never calls a setter;</li> <li>it can call the <a class="internal" href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="En/SpiderMonkey/JSAPI Reference/JSClass.addProperty"><code>JSClass.addProperty</code></a> callback when <code>JS_SetProperty</code> would not, because it can replace an existing property.</li>
</ul>
<p>The parameters specify the new property's <code>name</code>, initial <a href="/En/SpiderMonkey/JSAPI_Reference/Stored_value" title="en/JSAPI/Stored_value">stored <code>value</code></a>, <code>getter</code>, <code>setter</code>, and <a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes#Property_attributes" title="en/JS_GetPropertyAttributes#Property_attributes">property attributes</a> (<code>attrs</code>).</p>
<p>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 <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetProperty" title="en/JS_GetProperty">JS_GetProperty</a></code> and <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_SetProperty" title="en/JS_SetProperty">JS_SetProperty</a></code>. (Exception: If <code>attrs</code> contains the <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes" title="en/JS_GetPropertyAttributes">JSPROP_READONLY</a></code> flag, the setter will never be called, as property assignment will silently fail before it gets that far.  Also note that certain JSAPI functions, including <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_LookupProperty" title="en/SpiderMonkey/JSAPI Reference/JS LookupProperty"><code>JS_LookupProperty</code></a>, <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_HasProperty" title="en/SpiderMonkey/JSAPI Reference/JS HasProperty"><code>JS_HasProperty</code></a>, and <a class="internal" href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes" title="en/SpiderMonkey/JSAPI Reference/JS GetPropertyAttributes"><code>JS_GetPropertyAttributes</code></a>, can detect or examine a property without calling its getter.) If <code>getter</code> (or <code>setter</code>) is <code>NULL</code>, the new property will use the <code><a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSClass.getProperty</a></code> (or <code><a href="/En/SpiderMonkey/JSAPI_Reference/JSPropertyOp" title="en/JSClass.addProperty">JSClass.setProperty</a></code>) callback from <code>obj</code>'s class.</p>
<p>If <code>attrs</code> contains the <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes" title="en/JS_GetPropertyAttributes">JSPROP_GETTER</a></code> (or <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes" title="en/JS_GetPropertyAttributes">JSPROP_SETTER</a></code>) flag, then <code>getter</code> (or <code>setter</code>) must point to a JavaScript <code>Function</code>, not a C/C++ function. That is, it must be a <code>JSObject *</code> that points to a JavaScript <code>Function</code>, cast to type <code>JSPropertyOp</code>. For more about JavaScript getters and setters, see <a href="/en/Core_JavaScript_1.5_Guide/Creating_New_Objects/Defining_Getters_and_Setters" title="en/Core_JavaScript_1.5_Guide/Creating_New_Objects/Defining_Getters_and_Setters">Defining Getters and Setters</a>.</p>
<p>On success, <code>JS_DefineProperty</code> returns <code>JS_TRUE</code>. If the property already exists or cannot be created, <code>JS_DefineProperty</code> returns <code>JS_FALSE</code>.</p>
<h2 name="See_Also">See Also</h2>
<p>{{ LXRSearch("ident", "i", "JS_DefineProperty") }}<br>
{{ LXRSearch("ident", "i", "JS_DefineUCProperty") }}<br>
{{ LXRSearch("ident", "i", "JS_DefinePropertyById") }}</p>
<p><a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefineElement" title="en/JS_DefineElement">JS_DefineElement</a>, <a href="/en/SpiderMonkey/JSAPI_Reference/JS_DefinePropertyWithTinyId" title="en/JS_DefinePropertyWithTinyId">JS_DefinePropertyWithTinyId</a></p>
Revert to this revision