JSClass

From MDC

A JSClass describes a class of JavaScript objects. A C/C++ program can use a JSClass with the JS_InitClass and JS_NewObject APIs to create objects that have custom methods and properties implemented in C/C++.

[edit] Syntax

struct JSClass {
    char *name;
    uint32 flags;

    /* Mandatory non-null function pointer members. */
    JSPropertyOp        addProperty;
    JSPropertyOp        delProperty;
    JSPropertyOp        getProperty;
    JSPropertyOp        setProperty;
    JSEnumerateOp       enumerate;
    JSResolveOp         resolve;
    JSConvertOp         convert;
    JSFinalizeOp        finalize;

    /* Optionally non-null members start here. */
    JSGetObjectOps      getObjectOps;
    JSCheckAccessOp     checkAccess;
    JSNative            call;
    JSNative            construct;
    JSXDRObjectOp       xdrObject;
    JSHasInstanceOp     hasInstance;
    JSMarkOp            mark;
    JSReserveSlotsOp    reserveSlots;
};

Name	Type	Description
name	char *	Class name
flags	uint32	Class flags. This field is the bitwise OR of one or more of the JSCLASS_* constants described in JSClass.flags.
addProperty	JSPropertyOp	A hook called just after adding a new property. May modify the new property value. Use JS_PropertyStub for default behavior.
delProperty	JSPropertyOp	A hook called when deleting a property. May veto. Use JS_PropertyStub for default behavior.
getProperty	JSPropertyOp	A hook called when getting a property. This is the default getter for the class. Use JS_PropertyStub for default behavior.
setProperty	JSPropertyOp	A hook called when setting a property. When a script creates a new property, this is called after addProperty. Use JS_PropertyStub for default behavior.
enumerate	JSEnumerateOp	Method for enumerating object properties. Use JS_EnumerateStub for default behavior. The JSCLASS_NEW_ENUMERATE flag instructs SpiderMonkey to call this as a JSNewEnumerateOp.
resolve	JSResolveOp	Hook for implementing lazy properties. See JSClass.resolve for details. Use JS_ResolveStub if your class does not need lazily resolved properties. The JSCLASS_NEW_RESOLVE flag instructs SpiderMonkey to call this as a JSNewResolveOp. The JSCLASS_NEW_RESOLVE_GETS_START flag further affects this hook.
convert	JSConvertOp	Method for converting property values. Use JS_ConvertStub for default behavior.
finalize	JSFinalizeOp	The object finalizer hook. This is like the Java finalize() method. Use JS_FinalizeStub for default behavior.
getObjectOps	JSGetObjectOps	Pointer to an optional hook that returns a JSObjectOps, a set of additional object hooks. SpiderMonkey calls the getObjectOps hook each time a new object of this JSClass is created. To use the default JSObjectOps, set getObjectOps to NULL.
checkAccess	JSCheckAccessOp	Optional method for access checks. Implements JS_CheckAccess. If your application does not use the JSAPI's security features, use NULL.
call	JSNative	This is called when a script calls an object as though it were a function: obj(). If objects of your class shouldn't be callable, use NULL. Most objects are not callable.
construct	JSNative	Pointer to the constructor for the object that represents this class.
xdrObject	JSXDRObjectOp	Implements object serialization. If you do not use JSXDR, set this value to NULL.
hasInstance	JSHasInstanceOp	Pointer to an optional hasInstance method for this object. If you do not provide a method for hasInstance, set this pointer to NULL.
mark	JSMarkOp	Hook for the mark phase of garbage collection. A class must implement this hook if it has private data that contains references to JavaScript values. Otherwise, set this pointer to NULL. The JS_MARK_IS_TRACE flag instructs the JavaScript engine to call this callback as a JSTraceOp.
reserveSlots	JSReserveSlotsOp	A hook, called on object creation allowing the object to request reserved slots. If your class does not need any reserved slots, set this pointer to NULL. If your class requires a fixed number of reserved slots, use the JSCLASS_HAS_RESERVED_SLOTS(n) flags instead.

[edit] Description

Use JSClass to define a custom class of JavaScript objects. A JSClass has a name, flags, and several callback functions for advanced customization of object behavior.

Simple classes. A simple custom class does not require any special JSClass callbacks. Instead, all the native code is in JSPropertyOps (property getters and setters) and JSNatives or JSFastNatives (methods). The code for such a class is simple:

static JSClass robot_class = {
    "Robot",  /* name */
    0,  /* flags */
    JS_PropertyStub, JS_PropertyStub, JS_PropertyStub, JS_PropertyStub,
    JS_EnumerateStub, JS_ResolveStub, JS_ConvertStub, JS_FinalizeStub,
    JSCLASS_NO_OPTIONAL_MEMBERS
};

To expose this class to scripts, and to attach methods and properties to it, use JS_InitClass.

Private data. Custom classes very often need to store private C/C++ data that should not be visible to scripts. To do this, use the JSCLASS_HAS_PRIVATE and JSCLASS_CONSTRUCT_PROTOTYPE flags. Implement a JSClass.construct callback that allocates this private data and stores it in the new object using JS_SetPrivate. Implement a JSClass.finalize callback that frees the private data. Each native getter, setter, or method can access the private data using JS_GetInstancePrivate.

(This example uses the C++ new and delete keywords, but the application can allocate the memory for private data however it likes. The JavaScript engine never touches the private data; it is for the application's use only.)

JSBool printer_construct(JSContext *cx, JSObject *obj,
                         uintN argc, jsval *argv, jsval *rval)
{
    MyPrinter *p = new MyPrinter;
    if (p == NULL) {
        JS_ReportOutOfMemory(cx);
        return JS_FALSE;
    }
    JS_SetPrivate(cx, obj, p);
    return JS_TRUE;
}

void printer_finalize(JSContext *cx, JSObject *obj)
{
    MyPrinter *p = (MyPrinter *) JS_GetPrivate(cx, obj);
    delete p;
}

static JSClass printer_class = {
    "Printer",
    JSCLASS_HAS_PRIVATE | JSCLASS_CONSTRUCT_PROTOTYPE,
    JS_PropertyStub, JS_PropertyStub, JS_PropertyStub, JS_PropertyStub,
    JS_EnumerateStub, JS_ResolveStub, JS_ConvertStub, printer_finalize,
    NULL, NULL, NULL, printer_construct, NULL, NULL, NULL, NULL
};

[edit] See Also

LXR ID Search for JSClass

JSClass.flags, JSObjectOps, JS_GET_CLASS, JS_InitClass, JS_InstanceOf