mozilla
Your Search Results

    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

    Contributors to this page: Jorend
    Last updated by: Jorend,