JS InitClass

From MDC

Make a JSClass accessible to JavaScript code by creating its prototype, constructor, properties, and functions.

[edit] Syntax

JSObject * JS_InitClass(JSContext *cx, JSObject *obj,
    JSObject *parent_proto, JSClass *clasp,
    JSNative constructor, uintN nargs,
    JSPropertySpec *ps, JSFunctionSpec *fs,
    JSPropertySpec *static_ps, 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	JSObject *	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 JS_GetGlobalObject(cx), then JavaScript code will be able to see the new class as a global name.
parent_proto	JSObject *	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 obj argument. If constructor is NULL, then static_ps and static_fs must also be NULL.
nargs	uintN	Number of arguments for the constructor.
ps	JSPropertySpec *	Pointer to an array of JSPropertySpecs, terminated by the null JSPropertySpec, which can be written {0, 0, 0, 0, 0}. JS_InitClass adds these properties to the class's new prototype object. All instances of the new class will inherit these properties via the prototype chain.
fs	JSFunctionSpec *	Pointer to an array of JSFunctionSpecs, terminated by JS_FS_END. These functions 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 *	Pointer to an array of JSPropertySpecs, terminated by the null JSPropertySpec; or NULL. 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 *	Pointer to an array of JSFunctionSpecs, terminated by JS_FS_END; or NULL. 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.)

[edit] 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.

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.

Note: By default 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(), expecting that the constructor called JS_SetPrivate(), it may find that the private data is NULL. The JSCLASS_CONSTRUCT_PROTOTYPE flag is one way to avoid this inconsistency.

[edit] See Also

LXR ID Search for JS_InitClass

JS_GetClass, JS_InstanceOf