Obsolete since JSAPI 30
This feature is obsolete. Although it may still work in some browsers, its use is discouraged since it could be removed at any time. Try to avoid using it.
Create a new object property with a tiny id.
Syntax
JSBool JS_DefinePropertyWithTinyId( JSContext *cx, JSObject *obj, const char *name, int8 tinyid, jsval value, JSPropertyOp getter, JSPropertyOp setter, unsigned int attrs); JSBool JS_DefineUCPropertyWithTinyId( JSContext *cx, JSObject *obj, const jschar *name, size_t namelen, int8 tinyid, jsval value, JSPropertyOp getter, JSPropertyOp setter, unsigned int attrs);
Name | Type | Description |
---|---|---|
cx |
JSContext * |
The context in which to define the property. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext . |
obj |
JSObject * |
Object for which to create the new property. |
name |
const char * or const |
Name for the property to create. |
namelen |
size_t |
(only in JS_DefineUCPropertyWithTinyId ) The length of name in characters; or (size_t) -1 to indicate that name is null-terminated. |
tinyid |
int8 |
8-bit ID to aid in sharing getter and setter callbacks among properties. |
value |
jsval |
Initial stored value for the new property. |
getter |
JSPropertyOp |
getProperty method for retrieving the current property value. |
setter |
JSPropertyOp |
setProperty method for specifying a new property value. |
attrs |
unsigned int |
Property attributes. |
Description
JS_DefinePropertyWithTinyId
defines an object property with a tiny id. JS_DefineUCPropertyWithTinyId
is the Unicode version of the function. Except for the tinyid
parameter, these functions behave exactly as JS_DefineProperty
and JS_DefineUCProperty
. See those functions for more details.
tinyid
is a signed 8-bit integer that affects the id
value passed to certain callbacks. Any time the JavaScript engine would pass the name of the property as a string to the id
parameter of a tiny-id-aware callback, it passes INT_TO_JSVAL(tinyid)
instead. The tiny-id-aware callbacks are: property getters and setters; and JSClass.addProperty
, .delProperty
, .getProperty
, and .setProperty
. Tiny ids only affect the id
s passed to these hooks; the JavaScript engine does not use them as property names internally.
Tiny ids are helpful for getters and setters that are shared by several different properties. Those getters and setters can use switch (JSVAL_TO_INT(id))
, instead of checking the value of id
as a string, to determine which property is being accessed.
However, tiny ids can cause confusion when used with JSClass
callbacks. For example, if a property named "color"
is defined with tiny id 10
, then the JavaScript expressions obj[10]
and obj.color
will both result in INT_TO_JSVAL(10)
being passed to JSClass.getProperty
as the id
parameter. Per-property getters and setters do not suffer from this confusion: in the above example, obj.color
would cause the JavaScript engine to call the getter for the color
property, but obj[10]
wouldn't. Traditionally, negative tiny ids are used to minimize the potential confusion, but it is best to specify a non-null getter
and setter
when defining a property with a tiny id.
On success, JS_DefinePropertyWithTinyId
and JS_DefineUCPropertyWithTinyId
return JS_TRUE
. If the property already exists or cannot be created, they return JS_FALSE
.