JSClass

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

Syntax

struct JSClass {
    char *name;
    uint32 flags;

    /* Mandatory function pointer members. */
    JSPropertyOp        addProperty;
    JSPropertyOp        delProperty;
    JSPropertyOp        getProperty;
    JSStrictPropertyOp  setProperty;
    JSEnumerateOp       enumerate;
    JSResolveOp         resolve;
    JSConvertOp         convert;

    /* Optional members (may be null). */
    JSFinalizeOp        finalize;
    JSClassInternal     reserved;
    JSCheckAccessOp     checkAccess;
    JSNative            call;
    JSNative            construct;
    JSXDRObjectOp       xdrObject;
    JSHasInstanceOp     hasInstance;
    JSTraceOp           trace;
};
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 JSStrictPropertyOp

A hook called when setting a property. This is the default setter for the class. When a script creates a new property, this is called after addProperty.

Use JS_StrictPropertyStub 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

This hook specifies how objects of this class are converted to a primitive value.  It implements the object's [[DefaultValue]] hook, which is invoked by JavaScript when the object must be converted to a string, number, or primitive value.

Use JS_ConvertStub for default behavior, which is equivalent to that defined by ECMAScript in §8.12.8.

finalize JSFinalizeOp

The object finalizer hook. This is called at some point after the object becomes unreachable, and can be used to free any additional resources associated with the object.

If objects of this class do not need finalization, use 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 This is called when a script uses an object as though it were a constructor: new obj().  If objects of your class shouldn't be callable this way, use NULL. Most custom objects are not intended to be used as constructors.
xdrObject JSXDRObjectOp Implements object serialization. If you do not use JSXDR, set this pointer 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.

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, NULL,
    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 JSNative constructor function 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.

When initializing the class, pass the JSNative constructor function to JS_InitClass.

(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_StrictPropertyStub,
    JS_EnumerateStub, JS_ResolveStub, JS_ConvertStub, printer_finalize,
    JSCLASS_NO_OPTIONAL_MEMBERS
};

See also

MXR ID Search for JSClass

JSClass.flags, JSObjectOps, JS_GetClass, JS_InitClass, JS_InstanceOf

Document Tags and Contributors

Last updated by: Sheppy,