Make a JSClass accessible to JavaScript code by creating its prototype, constructor, properties, and functions.
Syntax
JSObject *
JS_InitClass(JSContext *cx, JS::HandleObject obj, JS::HandleObject parent_proto,
const JSClass *clasp, JSNative constructor, unsigned nargs,
const JSPropertySpec *ps, const JSFunctionSpec *fs,
const JSPropertySpec *static_ps, const JSFunctionSpec *static_fs);
| Name | Type | Description |
|---|---|---|
cx |
JSContext * |
Pointer to a JS context from which to derive runtime information. Requires request. In a JS_THREADSAFE build, the caller must be in a request on this JSContext. |
obj |
JS::HandleObject |
Pointer to the "globals" object to use for initializing the class. This must not be NULL. Once JS_InitClass creates the new class's constructor, it stores the constructor as a property in this object. So, for example, if this object is |
parent_proto |
JS::HandleObject |
Pointer to an object to be used as a prototype. JS_InitClass always creates a new prototype object that serves as the __proto__ for class instances; parent_proto becomes the __proto__ of that prototype object. |
clasp |
JSClass * |
Pointer to the class structure to initialize. This structure defines the class for use by other API functions. |
constructor |
JSNative |
The constructor for the class. Its scope matches that of the Unlike other |
nargs |
unsigned |
Number of arguments for the constructor. |
ps |
JSPropertySpec * |
Either NULL or a pointer to the first element of an array of JSPropertySpecs, terminated by the null JSPropertySpec, which can be written {0, 0, 0, 0, 0}. These properties, if any, are added to the class's new prototype object. All instances of the new class will inherit these properties via the prototype chain. |
fs |
JSFunctionSpec * |
Either NULL or a pointer to the first element of an array of JSFunctionSpecs, terminated by JS_FS_END. These functions, if any, are added to the class's new prototype object. All instances of the new class will inherit these methods via the prototype chain. (This is the JavaScript equivalent of public, non-static methods in C++ or Java.) |
static_ps |
JSPropertySpec * |
Either NULL or a pointer to the first element of an array of JSPropertySpecs, terminated by the null JSPropertySpec. These properties, if any, are added to the new class's constructor. (This is the nearest JavaScript equivalent of public static member variables in C++ or public static fields in Java.) |
static_fs |
JSFunctionSpec * |
Either NULL or a pointer to the first element of an array of JSFunctionSpecs, terminated by JS_FS_END. These functions, if any, are added to the new class's constructor. (This is the JavaScript equivalent of public static methods in C++ or Java.) |
Description
JS_InitClass initializes a JSClass and (optionally) makes it visible to JavaScript code.
This is one way to create JSObjects whose properties and methods are implemented in native C/C++. If you need a native function but you don't need to support instances or inheritance, JS_InitClass might be overkill. JS_DefineFunction is simpler.
A JSAPI class consists of a JSClass structure, a constructor, a prototype object, and properties and functions. The JSClass is an internal data structure that is not exposed outside the JavaScript engine. It specifies the name of the class, its flags, and its property access functions. These include native C functions for instance finalization, adding and deleting properties, getting and setting property values, and enumerating, converting, and resolving properties. The JSAPI provides reasonable default behavior for all of these; ordinarily you don't want to overload any of them.
After a successful call to JS_InitClass, JavaScript code can see and manipulate the class's constructor and prototype just as if it were an ordinary JavaScript function with a prototype property. JavaScript code can create new instances using the new keyword. Classes can have methods and properties that are present on all instances. They can also have methods and properties that are only present on the constructor; these are called "static methods" and "static properties" because they serve the same purpose and use the same syntax as static methods and fields in Java.
On success, JS_InitClass returns a pointer to a JS object that is the prototype for the newly initialized class. If JS_InitClass fails, it returns NULL.
The constructor for the class is built in the same context as cx, and in the same scope as obj. If you pass NULL as the constructor parameter, then a constructor is not built, and you cannot specify static properties and functions for the class.
If you provide a constructor for the class, then you should also pass an object to parent_proto. JS_InitClass uses parent_proto to build a prototype object for the class. The prototype object inherits properties and methods from the parent_proto object you provide.
Once the constructor or prototype is created, JS_InitClass defines a property on obj. The name of the property is clasp->name. Its value is the constructor function if constructor is non-null, and the prototype object otherwise. The property has the stub getter and setter and no property attributes. (If your constructor function requires property attributes, such as JSPROP_ENUMERATE, use JS_SetPropertyAttributes to modify the attributes of the property created by JS_InitClass.)
After building the constructor and prototype, JS_InitClass adds properties and methods. Ordinary properties and methods are added to the prototype. Static properties and methods are added to the constructor. The properties are defined as though by calling JS_DefineProperties, and the methods as though by calling JS_DefineFunctions.
JS_InitClass creates a prototype object but does not invoke the constructor (JSClass.construct) on it. However, the prototype object will eventually be finalized (JSClass.finalize). This inconsistency can cause problems; for example, if the finalizer calls JS_GetPrivate()JS_SetPrivate()NULL. The JSCLASS_CONSTRUCT_PROTOTYPE flag is one way to avoid this inconsistency.Warning: If the class is a JSExtendedClass, make sure that the additional reserved fields at the end of the JSExtendedClass are NULL. JSExtendedClass structs should usually be global, and in this case the compiler automatically initializes these fields to NULL. (This is a feature of the C and C++ languages.) Otherwise, use memset.