JS GetProperty

Finds a specified property and retrieves its value.

Syntax

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); 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 JSObject * Object to search on for the property.
name or id const char * or const jschar * or jsid 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 jsval * Out parameter. On success, *vp receives the current value of the property, or JSVAL_VOID 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 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.

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 to JSVAL_VOID. Then the JSClass.getProperty hook of obj's class is called with the arguments (cx, obj, idval, vp) where idval is a jsval containing the property name. For many objects, including objects of standard classes such as Object and Array, this hook does nothing and returns JS_TRUE, so the property get succeeds and JSVAL_VOID is left in *vp.
  • If the property is found on a non-native object, its JSObjectOps.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, or JSVAL_VOID if the property does not have a stored value, and then the property's getter is called with the arguments (cx, obj, idval, vp), where idval is a jsval containing 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 *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 JSVAL_VOID if 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.

See Also

MXR ID Search for JS_GetProperty
MXR ID Search for JS_GetUCProperty
MXR ID Search for JS_GetPropertyById

Example in the JSAPI Phrasebook

JS_DefineProperty, JS_DefinePropertyWithTinyId, JS_DeleteProperty, JS_DeleteProperty2, JS_LookupProperty, JS_PropertyStub, JS_SetProperty

Document Tags and Contributors

Last updated by: Jorend,