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 ids 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.