Finds a specified property and retrieves its value.
JSBool JS_GetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp); JSBool JS_GetUCProperty(JSContext *cx, JSObject *obj, const jschar *name, size_t namelen, jsval *vp); JSBool JS_GetPropertyById(JSContext *cx, JSObject *obj, jsid id, jsval *vp);
| || ||A context. Requires request. In a |
| || ||Object to search on for the property.|
| || ||Name of the property to look up.|
| || ||(in |
| || ||Out parameter. On success, |
JS_GetProperty examines a specified JS object
obj and its prototype chain for a property with the specified
JS_GetUCProperty is the Unicode version of the function.
JS_GetPropertyById is the same but takes a
jsid for the property name.
In the simplest case, JS_GetProperty stores the value of the property in *vp and returns JS_TRUE. However, several different hooks can affect property gets. The full algorithm is described below.
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
*vpis set to
JSVAL_VOID. Then the
obj's class is called with the arguments
(cx, obj, idval, vp)where
jsvalcontaining the property name. For many objects, including objects of standard classes such as
Array, this hook does nothing and returns
JS_TRUE, so the property get succeeds and
JSVAL_VOIDis left in
- If the property is found on a non-native object, its
JSObjectOps.getPropertymethod is called.
*vpis set to the property's stored value, or
JSVAL_VOIDif the property does not have a stored value, and then the property's getter is called with the arguments
(cx, obj, idval, vp), where
jsvalcontaining the property name. For many properties, the getter does nothing and returns
JS_TRUE, so the property get succeeds and the property's stored value is left in
Internally, property retrieval, including all the behavior described above, is implemented by
On success, these functions set *vp to the current value of the property, or
obj has no such property, and return
JS_TRUE. On an error or exception, these functions return
JS_FALSE, and the value left in
*vp is undefined.