JS_GetPropertyAttributes

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_GetPropertyAttributes
  • Revision title: JS_GetPropertyAttributes
  • Revision id: 85809
  • Created:
  • Creator: Jorend
  • Is current revision? No
  • Comment /* Property attributes */ doc [[JSPROP_SHARED]]

Revision Content

{{template.Jsapi_ref_header("JS_GetPropertyAttributes")}}

Get the attributes of a specified property.

Syntax

JSBool JS_GetPropertyAttributes(JSContext *cx, JSObject *obj,
    const char *name, uintN *attrsp, JSBool *foundp);

JSBool JS_GetUCPropertyAttributes(JSContext *cx, JSObject *obj,
    const jschar *name, size_t namelen,
    uintN *attrsp, JSBool *foundp);
Name Type Description
cx JSContext * The context in which to look up property attributes. {{wiki.template('Jsapi-requires-request')}}
obj JSObject * The object that has the property to be queried.
name const char * or const jschar * Name of the property from which to retrieve attributes.
namelen size_t (only in JS_GetUCPropertyAttributes) The length of name in characters; or (size_t) -1 to indicate that name is null-terminated.
attrsp uintN * Out parameter. If the specified property is found on obj, *attrsp receives its attributes.
foundp JSBool * Out parameter. If no error occurs, *foundp receives JS_TRUE if the specified property is found and JS_FALSE if it is not found. If an error occurs, the value left in *foundp is undefined.

Description

JS_GetPropertyAttributes retrieves the property attributes of the property with the given name on a given object, obj. JS_GetUCPropertyAttributes is the Unicode version of the function.

cx is the context. obj and name specify the object and property to examine. attrsp and foundp are the out parameters.

If an error occurs, the return value is JS_FALSE, and the values left in *attrsp and *foundp are undefined.

If obj does not have the specified property, or if it inherits it from some other object (on its prototype chain, for example), then *foundp is set to JS_FALSE. The value left in *attrsp is undefined. The return value is JS_TRUE (to indicate that no error occurred).

If the property exists and belongs to obj, then *foundp is set to JS_TRUE, *attrsp is set to the logical OR of zero or more property attribute flags (described below), and the function returns JS_TRUE.

Property attributes

Any object property can have zero or more property attributes set. Some property attributes are defined in the ECMAScript standard, in {{template.Es3_spec("8.6.1")}}. SpiderMonkey additionally defines two non-standard property attributes.

The JSAPI expresses property attributes as a value of type uintN, the bitwise OR of zero or more of the JSPROP flags described below.

Flag Description

JSPROP_ENUMERATE

The property is visible to JavaScript forin and for eachin loops, as well as to JS_Enumerate.

This is the inverse of the ECMA standard DontEnum attribute.

{{template.LXRSearch("ident", "i", "JSPROP_ENUMERATE")}}

JSPROP_READONLY

The property's value cannot be set. In JavaScript 1.2 and lower, it is an error to attempt to assign a value to a read-only property. In JavaScript 1.3 and higher, as in ECMAScript, attempts to set a value on a read-only property are ignored.

This is the ECMA standard ReadOnly attribute.

{{template.LXRSearch("ident", "i", "JSPROP_READONLY")}}

JSPROP_PERMANENT

The property cannot be deleted. In JavaScript 1.2 and lower, it is an error to attempt to delete a permanent property. In JavaScript 1.3 and higher, as in ECMAScript, such attempts are ignored.

This is the ECMA standard DontDelete attribute.

The JavaScript language does not provide any way for a script to delete a permanent property. C/C++ code can do this by making the property non-permanent, using JS_SetPropertyAttributes, before deleting it.

{{template.LXRSearch("ident", "i", "JSPROP_PERMANENT")}}

JSPROP_EXPORTED

The property can be imported by other scripts or objects, typically to borrow security privileges. (???)

{{template.LXRSearch("ident", "i", "JSPROP_EXPORTED")}}

JSPROP_GETTER

The property's getter is a JavaScript Function, not a C/C++ function. See JS_DefineProperty and JS_GetPropertyAttrsGetterAndSetter for details.

{{template.LXRSearch("ident", "i", "JSPROP_GETTER")}}

JSPROP_SETTER

The property's setter is a JavaScript Function, not a C/C++ function. See JS_DefineProperty and JS_GetPropertyAttrsGetterAndSetter for details.

{{template.LXRSearch("ident", "i", "JSPROP_SETTER")}}

JSPROP_SHARED

The property is shared. The JavaScript engine does not allocate memory for the property's stored value.

Shared properties also affect inheritance. If an object inherits a shared property via the prototype chain, setting the property on that object does not cause it to get its own property, as it ordinarily would. Instead, the setter is called and the property remains inherited.

JSPROP_SHARED is appropriate for custom properties that are implemented as fields of a native C/C++ data structure or as C++ Get/Set method pairs. In such cases, the stored value slot is redundant at best and could entrain garbage.

{{template.LXRSearch("ident", "i", "JSPROP_SHARED")}}

JSPROP_INDEX

The property's id is represented internally as an integer, not a string.

This flag has an additional special meaning when used with JS_DefineProperty, JS_FS, and other APIs that define properties: it means that the name parameter is actually an integer unsafely cast to a pointer type, not a string.

{{template.LXRSearch("ident", "i", "JSPROP_INDEX")}}

An application can set property attributes when creating a property. See JS_DefineProperty, JS_FS, and JS_FN. To modify the attributes of an existing property, use JS_SetPropertyAttributes.

{{template.LXRSearch("ident", "i", "JS_GetPropertyAttributes")}}
{{template.LXRSearch("ident", "i", "JS_GetUCPropertyAttributes")}}

Revision Source

<p>{{template.Jsapi_ref_header("JS_GetPropertyAttributes")}}
</p><p>Get the attributes of a specified property.
</p>
<h2 name="Syntax"> Syntax </h2>
<pre class="eval"><a href="en/JSBool">JSBool</a> <b>JS_GetPropertyAttributes</b>(<a href="en/JSContext">JSContext</a> *cx, <a href="en/JSObject">JSObject</a> *obj,
    const char *name, <a href="en/UintN">uintN</a> *attrsp, <a href="en/JSBool">JSBool</a> *foundp);

<a href="en/JSBool">JSBool</a> <b>JS_GetUCPropertyAttributes</b>(<a href="en/JSContext">JSContext</a> *cx, <a href="en/JSObject">JSObject</a> *obj,
    const <a href="en/Jschar">jschar</a> *name, size_t namelen,
    <a href="en/UintN">uintN</a> *attrsp, <a href="en/JSBool">JSBool</a> *foundp);
</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/JSContext">JSContext</a> *</code></td>
<td>The context in which to look up property attributes.
{{wiki.template('Jsapi-requires-request')}}</td>
</tr>
<tr>
<td><code>obj</code></td>
<td><code><a href="en/JSObject">JSObject</a> *</code></td>
<td>The object that has the property to be queried.</td>
</tr>
<tr>
<td><code>name</code></td>
<td><code>const char *</code> <i>or</i> <code>const <a href="en/Jschar">jschar</a> *</code></td>
<td>Name of the property from which to retrieve attributes.</td>
</tr>
<tr>
<td><code>namelen</code></td>
<td><code>size_t</code></td>
<td><i>(only in <code>JS_GetUCPropertyAttributes</code>)</i> 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>attrsp</code></td>
<td><code><a href="en/UintN">uintN</a> *</code></td>
<td>Out parameter.  If the specified property is found on <code>obj</code>, <code>*attrsp</code> receives its attributes.</td>
</tr>
<tr>
<td><code>foundp</code></td>
<td><code><a href="en/JSBool">JSBool</a> *</code></td>
<td>Out parameter.  If no error occurs, <code>*foundp</code> receives <code>JS_TRUE</code> if the specified property is found and <code>JS_FALSE</code> if it is not found.  If an error occurs, the value left in <code>*foundp</code> is undefined.</td>
</tr>
</tbody></table>
<h2 name="Description"> Description </h2>
<p><code>JS_GetPropertyAttributes</code> retrieves the property attributes of the property with the given <code>name</code> on a given object, <code>obj</code>.  <code>JS_GetUCPropertyAttributes</code> is the Unicode version of the function.
</p><p><code>cx</code> is the context.  <code>obj</code> and <code>name</code> specify the object and property to examine.  <code>attrsp</code> and <code>foundp</code> are the out parameters.
</p><p>If an error occurs, the return value is <code>JS_FALSE</code>, and the values left in <code>*attrsp</code> and <code>*foundp</code> are undefined.
</p><p>If <code>obj</code> does not have the specified property, or if it inherits it from some other object (on its prototype chain, for example), then <code>*foundp</code> is set to <code>JS_FALSE</code>.  The value left in <code>*attrsp</code> is undefined.  The return value is <code>JS_TRUE</code> (to indicate that no error occurred).
</p><p>If the property exists and belongs to <code>obj</code>, then <code>*foundp</code> is set to <code>JS_TRUE</code>, <code>*attrsp</code> is set to the logical OR of zero or more property attribute flags (described below), and the function returns <code>JS_TRUE</code>.
</p>
<h3 name="Property_attributes">Property attributes</h3>
<p>Any object property can have zero or more <i>property attributes</i> set.  Some property attributes are defined in the ECMAScript standard, in {{template.Es3_spec("8.6.1")}}.  SpiderMonkey additionally defines two non-standard property attributes.
</p><p>The JSAPI expresses property attributes as a value of type <code><a href="en/UintN">uintN</a></code>, the bitwise OR of zero or more of the <code>JSPROP</code> flags described below.
</p>
<table class="fullwidth-table">
<tbody><tr>
<th>Flag</th>
<th>Description</th>
</tr>
<tr>
<td>
<p><code><b>JSPROP_ENUMERATE</b></code>
</p>
</td>
<td>
<p>The property is visible to JavaScript <code>for</code>…<code>in</code> and <code>for each</code>…<code>in</code> loops, as well as to <code><a href="en/JS_Enumerate">JS_Enumerate</a></code>.
</p><p>This is the inverse of the ECMA standard DontEnum attribute.
</p><p>{{template.LXRSearch("ident", "i", "JSPROP_ENUMERATE")}}
</p>
</td>
</tr>
<tr>
<td>
<p><code><b>JSPROP_READONLY</b></code>
</p>
</td>
<td>
<p>The property's value cannot be set. In JavaScript 1.2 and lower, it is an error to attempt to assign a value to a read-only property. In JavaScript 1.3 and higher, as in ECMAScript, attempts to set a value on a read-only property are ignored.
</p><p>This is the ECMA standard ReadOnly attribute.
</p><p>{{template.LXRSearch("ident", "i", "JSPROP_READONLY")}}
</p>
</td>
</tr>
<tr>
<td>
<p><code><b>JSPROP_PERMANENT</b></code>
</p>
</td>
<td>
<p>The property cannot be deleted. In JavaScript 1.2 and lower, it is an error to attempt to delete a permanent property. In JavaScript 1.3 and higher, as in ECMAScript, such attempts are ignored.
</p><p>This is the ECMA standard DontDelete attribute.
</p><p>The JavaScript language does not provide any way for a script to delete a permanent property.  C/C++ code can do this by making the property non-permanent, using <code><a href="en/JS_SetPropertyAttributes">JS_SetPropertyAttributes</a></code>, before deleting it.
</p><p>{{template.LXRSearch("ident", "i", "JSPROP_PERMANENT")}}
</p>
</td>
</tr>
<tr>
<td>
<p><code><b>JSPROP_EXPORTED</b></code>
</p>
</td>
<td>
<p>The property can be imported by other scripts or objects, typically to borrow security privileges. <i>(???)</i>
</p><p>{{template.LXRSearch("ident", "i", "JSPROP_EXPORTED")}}
</p>
</td>
</tr>
<tr>
<td>
<p><code><b>JSPROP_GETTER</b></code>
</p>
</td>
<td>
<p>The property's getter is a JavaScript <code>Function</code>, not a C/C++ function.  See <code><a href="en/JS_DefineProperty">JS_DefineProperty</a></code> and <code><a href="en/JS_GetPropertyAttrsGetterAndSetter">JS_GetPropertyAttrsGetterAndSetter</a></code> for details.
</p><p>{{template.LXRSearch("ident", "i", "JSPROP_GETTER")}}
</p>
</td>
</tr>
<tr>
<td>
<p><code><b>JSPROP_SETTER</b></code>
</p>
</td>
<td>
<p>The property's setter is a JavaScript <code>Function</code>, not a C/C++ function.  See <code><a href="en/JS_DefineProperty">JS_DefineProperty</a></code> and <code><a href="en/JS_GetPropertyAttrsGetterAndSetter">JS_GetPropertyAttrsGetterAndSetter</a></code> for details.
</p><p>{{template.LXRSearch("ident", "i", "JSPROP_SETTER")}}
</p>
</td>
</tr>
<tr>
<td>
<p><code><b>JSPROP_SHARED</b></code>
</p>
</td>
<td>
<p>The property is shared.  The JavaScript engine does not allocate memory for the property's <a href="en/JSAPI/Stored_value">stored value</a>.
</p><p>Shared properties also affect inheritance.  If an object inherits a shared property via the prototype chain, setting the property on that object does not cause it to get its own property, as it ordinarily would.  Instead, the setter is called and the property remains inherited.
</p><p><code>JSPROP_SHARED</code> is appropriate for custom properties that are implemented as fields of a native C/C++ data structure or as C++ <code>Get</code>/<code>Set</code> method pairs.  In such cases, the stored value slot is redundant at best and could entrain garbage.
</p><p>{{template.LXRSearch("ident", "i", "JSPROP_SHARED")}}
</p>
</td>
</tr>
<tr>
<td>
<p><code><b>JSPROP_INDEX</b></code>
</p>
</td>
<td>
<p>The property's id is represented internally as an integer, not a string.
</p><p>This flag has an additional special meaning when used with <code><a href="en/JS_DefineProperty">JS_DefineProperty</a></code>, <code><a href="en/JS_FS">JS_FS</a></code>, and other APIs that define properties: it means that the <code>name</code> parameter is actually an integer unsafely cast to a pointer type, not a string.
</p><p>{{template.LXRSearch("ident", "i", "JSPROP_INDEX")}}
</p>
</td>
</tr>
</tbody></table>
<p>An application can set property attributes when creating a property.  See <code><a href="en/JS_DefineProperty">JS_DefineProperty</a></code>, <code><a href="en/JS_FS">JS_FS</a></code>, and <code><a href="en/JS_FN">JS_FN</a></code>.  To modify the attributes of an existing property, use <code><a href="en/JS_SetPropertyAttributes">JS_SetPropertyAttributes</a></code>.
</p><p>{{template.LXRSearch("ident", "i", "JS_GetPropertyAttributes")}}<br>
{{template.LXRSearch("ident", "i", "JS_GetUCPropertyAttributes")}}
</p>
Revert to this revision