This article needs a technical review. How you can help.
Find a specified property and retrieve its value.
Syntax
bool JS_GetProperty(JSContext *cx, JS::HandleObject obj, const char *name, JS::MutableHandleValue vp); bool JS_GetUCProperty(JSContext *cx, JS::HandleObject obj, const char16_t *name, size_t namelen, JS::MutableHandleValue vp); bool JS_GetPropertyById(JSContext *cx, JS::HandleObject obj, JS::HandleId id, JS::MutableHandleValue vp); // Added in SpiderMonkey 1.8.1
Name | Type | Description |
---|---|---|
cx |
JSContext * |
A context. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext . |
obj |
JS::HandleObject |
Object to search on for the property. |
name or id |
const char * or const char16_t * or JS::HandleId |
Name of the property to look up. |
namelen |
size_t |
(in JS_GetUCProperty only) The length of name , in characters; or -1 to indicate that name is null-terminated. |
vp |
JS::MutableHandleValue |
Out parameter. On success, *vp receives the current value of the property, or undefined if no such property is found. |
Description
JS_GetProperty
examines a specified JS object obj
and its prototype chain for a property with the specified name
. It behaves like the JavaScript expression obj[name]
. JS_GetUCProperty
is the Unicode version of the function. JS_GetPropertyById
is the same but takes a JS::HandleId
for the property name.
In the simplest case, JS_GetProperty stores the value of the property in *vp and returns true
. However, several different hooks can affect property gets. The full algorithm is described below.
Details
First, a property lookup is performed. If the lookup proceeds without error, exactly one of the following cases applies:
- If the property is not found, then
*vp
is set toundefined
. Then theJSClass.getProperty
hook ofobj
's class is called with the arguments(cx, obj, id, vp)
. For many objects, including objects of standard classes such asObject
andArray
, this hook does nothing and returnstrue
, so the property get succeeds andundefined
is left in*vp
. - If the property is found on a non-native object, get handler of
Proxy
(only if the object is a Proxy) or itsJSObjectOps.getProperty
method is called. - Otherwise the property is found on a native object. If the property has a JavaScript getter, it is called. Otherwise
*vp
is set to the property's stored value, orundefined
if the property does not have a stored value, and then the property's getter is called with the arguments(cx, obj, id, vp)
. For many properties, the getter does nothing and returnstrue
, so the property get succeeds and the property's stored value is left in*vp
.
Internally, property retrieval, including all the behavior described above, is implemented by obj
's JSObjectOps.getProperty
callback.
On success, these functions set *vp
to the current value of the property, or undefined
if obj
has no such property, and return true
. On an error or exception, these functions return false
, and the value left in *vp
is undefined.