Back to index

lightning-sunbird  0.9+nobinonly
jspubtd.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
00002  *
00003  * ***** BEGIN LICENSE BLOCK *****
00004  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00005  *
00006  * The contents of this file are subject to the Mozilla Public License Version
00007  * 1.1 (the "License"); you may not use this file except in compliance with
00008  * the License. You may obtain a copy of the License at
00009  * http://www.mozilla.org/MPL/
00010  *
00011  * Software distributed under the License is distributed on an "AS IS" basis,
00012  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00013  * for the specific language governing rights and limitations under the
00014  * License.
00015  *
00016  * The Original Code is Mozilla Communicator client code, released
00017  * March 31, 1998.
00018  *
00019  * The Initial Developer of the Original Code is
00020  * Netscape Communications Corporation.
00021  * Portions created by the Initial Developer are Copyright (C) 1998
00022  * the Initial Developer. All Rights Reserved.
00023  *
00024  * Contributor(s):
00025  *
00026  * Alternatively, the contents of this file may be used under the terms of
00027  * either of the GNU General Public License Version 2 or later (the "GPL"),
00028  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00029  * in which case the provisions of the GPL or the LGPL are applicable instead
00030  * of those above. If you wish to allow use of your version of this file only
00031  * under the terms of either the GPL or the LGPL, and not to allow others to
00032  * use your version of this file under the terms of the MPL, indicate your
00033  * decision by deleting the provisions above and replace them with the notice
00034  * and other provisions required by the GPL or the LGPL. If you do not delete
00035  * the provisions above, a recipient may use your version of this file under
00036  * the terms of any one of the MPL, the GPL or the LGPL.
00037  *
00038  * ***** END LICENSE BLOCK ***** */
00039 
00040 #ifndef jspubtd_h___
00041 #define jspubtd_h___
00042 /*
00043  * JS public API typedefs.
00044  */
00045 #include "jstypes.h"
00046 #include "jscompat.h"
00047 
00048 JS_BEGIN_EXTERN_C
00049 
00050 /* Scalar typedefs. */
00051 typedef uint16    jschar;
00052 typedef int32     jsint;
00053 typedef uint32    jsuint;
00054 typedef float64   jsdouble;
00055 typedef jsword    jsval;
00056 typedef jsword    jsid;
00057 typedef int32     jsrefcount;   /* PRInt32 if JS_THREADSAFE, see jslock.h */
00058 
00059 /*
00060  * Run-time version enumeration.  See jsconfig.h for compile-time counterparts
00061  * to these values that may be selected by the JS_VERSION macro, and tested by
00062  * #if expressions.
00063  */
00064 typedef enum JSVersion {
00065     JSVERSION_1_0     = 100,
00066     JSVERSION_1_1     = 110,
00067     JSVERSION_1_2     = 120,
00068     JSVERSION_1_3     = 130,
00069     JSVERSION_1_4     = 140,
00070     JSVERSION_ECMA_3  = 148,
00071     JSVERSION_1_5     = 150,
00072     JSVERSION_1_6     = 160,
00073     JSVERSION_1_7     = 170,
00074     JSVERSION_DEFAULT = 0,
00075     JSVERSION_UNKNOWN = -1
00076 } JSVersion;
00077 
00078 #define JSVERSION_IS_ECMA(version) \
00079     ((version) == JSVERSION_DEFAULT || (version) >= JSVERSION_1_3)
00080 
00081 /* Result of typeof operator enumeration. */
00082 typedef enum JSType {
00083     JSTYPE_VOID,                /* undefined */
00084     JSTYPE_OBJECT,              /* object */
00085     JSTYPE_FUNCTION,            /* function */
00086     JSTYPE_STRING,              /* string */
00087     JSTYPE_NUMBER,              /* number */
00088     JSTYPE_BOOLEAN,             /* boolean */
00089     JSTYPE_NULL,                /* null */
00090     JSTYPE_XML,                 /* xml object */
00091     JSTYPE_LIMIT
00092 } JSType;
00093 
00094 /* Dense index into cached prototypes and class atoms for standard objects. */
00095 typedef enum JSProtoKey {
00096 #define JS_PROTO(name,code,init) JSProto_##name = code,
00097 #include "jsproto.tbl"
00098 #undef JS_PROTO
00099     JSProto_LIMIT
00100 } JSProtoKey;
00101 
00102 /* JSObjectOps.checkAccess mode enumeration. */
00103 typedef enum JSAccessMode {
00104     JSACC_PROTO  = 0,           /* XXXbe redundant w.r.t. id */
00105     JSACC_PARENT = 1,           /* XXXbe redundant w.r.t. id */
00106     JSACC_IMPORT = 2,           /* import foo.bar */
00107     JSACC_WATCH  = 3,           /* a watchpoint on object foo for id 'bar' */
00108     JSACC_READ   = 4,           /* a "get" of foo.bar */
00109     JSACC_WRITE  = 8,           /* a "set" of foo.bar = baz */
00110     JSACC_LIMIT
00111 } JSAccessMode;
00112 
00113 #define JSACC_TYPEMASK          (JSACC_WRITE - 1)
00114 
00115 /*
00116  * This enum type is used to control the behavior of a JSObject property
00117  * iterator function that has type JSNewEnumerate.
00118  */
00119 typedef enum JSIterateOp {
00120     JSENUMERATE_INIT,       /* Create new iterator state */
00121     JSENUMERATE_NEXT,       /* Iterate once */
00122     JSENUMERATE_DESTROY     /* Destroy iterator state */
00123 } JSIterateOp;
00124 
00125 /* Struct typedefs. */
00126 typedef struct JSClass           JSClass;
00127 typedef struct JSExtendedClass   JSExtendedClass;
00128 typedef struct JSConstDoubleSpec JSConstDoubleSpec;
00129 typedef struct JSContext         JSContext;
00130 typedef struct JSErrorReport     JSErrorReport;
00131 typedef struct JSFunction        JSFunction;
00132 typedef struct JSFunctionSpec    JSFunctionSpec;
00133 typedef struct JSIdArray         JSIdArray;
00134 typedef struct JSProperty        JSProperty;
00135 typedef struct JSPropertySpec    JSPropertySpec;
00136 typedef struct JSObject          JSObject;
00137 typedef struct JSObjectMap       JSObjectMap;
00138 typedef struct JSObjectOps       JSObjectOps;
00139 typedef struct JSXMLObjectOps    JSXMLObjectOps;
00140 typedef struct JSRuntime         JSRuntime;
00141 typedef struct JSRuntime         JSTaskState;   /* XXX deprecated name */
00142 typedef struct JSScript          JSScript;
00143 typedef struct JSStackFrame      JSStackFrame;
00144 typedef struct JSString          JSString;
00145 typedef struct JSXDRState        JSXDRState;
00146 typedef struct JSExceptionState  JSExceptionState;
00147 typedef struct JSLocaleCallbacks JSLocaleCallbacks;
00148 
00149 /* JSClass (and JSObjectOps where appropriate) function pointer typedefs. */
00150 
00151 /*
00152  * Add, delete, get or set a property named by id in obj.  Note the jsval id
00153  * type -- id may be a string (Unicode property identifier) or an int (element
00154  * index).  The *vp out parameter, on success, is the new property value after
00155  * an add, get, or set.  After a successful delete, *vp is JSVAL_FALSE iff
00156  * obj[id] can't be deleted (because it's permanent).
00157  */
00158 typedef JSBool
00159 (* JS_DLL_CALLBACK JSPropertyOp)(JSContext *cx, JSObject *obj, jsval id,
00160                                  jsval *vp);
00161 
00162 /*
00163  * This function type is used for callbacks that enumerate the properties of
00164  * a JSObject.  The behavior depends on the value of enum_op:
00165  *
00166  *  JSENUMERATE_INIT
00167  *    A new, opaque iterator state should be allocated and stored in *statep.
00168  *    (You can use PRIVATE_TO_JSVAL() to tag the pointer to be stored).
00169  *
00170  *    The number of properties that will be enumerated should be returned as
00171  *    an integer jsval in *idp, if idp is non-null, and provided the number of
00172  *    enumerable properties is known.  If idp is non-null and the number of
00173  *    enumerable properties can't be computed in advance, *idp should be set
00174  *    to JSVAL_ZERO.
00175  *
00176  *  JSENUMERATE_NEXT
00177  *    A previously allocated opaque iterator state is passed in via statep.
00178  *    Return the next jsid in the iteration using *idp.  The opaque iterator
00179  *    state pointed at by statep is destroyed and *statep is set to JSVAL_NULL
00180  *    if there are no properties left to enumerate.
00181  *
00182  *  JSENUMERATE_DESTROY
00183  *    Destroy the opaque iterator state previously allocated in *statep by a
00184  *    call to this function when enum_op was JSENUMERATE_INIT.
00185  *
00186  * The return value is used to indicate success, with a value of JS_FALSE
00187  * indicating failure.
00188  */
00189 typedef JSBool
00190 (* JS_DLL_CALLBACK JSNewEnumerateOp)(JSContext *cx, JSObject *obj,
00191                                      JSIterateOp enum_op,
00192                                      jsval *statep, jsid *idp);
00193 
00194 /*
00195  * The old-style JSClass.enumerate op should define all lazy properties not
00196  * yet reflected in obj.
00197  */
00198 typedef JSBool
00199 (* JS_DLL_CALLBACK JSEnumerateOp)(JSContext *cx, JSObject *obj);
00200 
00201 /*
00202  * Resolve a lazy property named by id in obj by defining it directly in obj.
00203  * Lazy properties are those reflected from some peer native property space
00204  * (e.g., the DOM attributes for a given node reflected as obj) on demand.
00205  *
00206  * JS looks for a property in an object, and if not found, tries to resolve
00207  * the given id.  If resolve succeeds, the engine looks again in case resolve
00208  * defined obj[id].  If no such property exists directly in obj, the process
00209  * is repeated with obj's prototype, etc.
00210  *
00211  * NB: JSNewResolveOp provides a cheaper way to resolve lazy properties.
00212  */
00213 typedef JSBool
00214 (* JS_DLL_CALLBACK JSResolveOp)(JSContext *cx, JSObject *obj, jsval id);
00215 
00216 /*
00217  * Like JSResolveOp, but flags provide contextual information as follows:
00218  *
00219  *  JSRESOLVE_QUALIFIED   a qualified property id: obj.id or obj[id], not id
00220  *  JSRESOLVE_ASSIGNING   obj[id] is on the left-hand side of an assignment
00221  *  JSRESOLVE_DETECTING   'if (o.p)...' or similar detection opcode sequence
00222  *  JSRESOLVE_DECLARING   var, const, or function prolog declaration opcode
00223  *  JSRESOLVE_CLASSNAME   class name used when constructing
00224  *
00225  * The *objp out parameter, on success, should be null to indicate that id
00226  * was not resolved; and non-null, referring to obj or one of its prototypes,
00227  * if id was resolved.
00228  *
00229  * This hook instead of JSResolveOp is called via the JSClass.resolve member
00230  * if JSCLASS_NEW_RESOLVE is set in JSClass.flags.
00231  *
00232  * Setting JSCLASS_NEW_RESOLVE and JSCLASS_NEW_RESOLVE_GETS_START further
00233  * extends this hook by passing in the starting object on the prototype chain
00234  * via *objp.  Thus a resolve hook implementation may define the property id
00235  * being resolved in the object in which the id was first sought, rather than
00236  * in a prototype object whose class led to the resolve hook being called.
00237  *
00238  * When using JSCLASS_NEW_RESOLVE_GETS_START, the resolve hook must therefore
00239  * null *objp to signify "not resolved".  With only JSCLASS_NEW_RESOLVE and no
00240  * JSCLASS_NEW_RESOLVE_GETS_START, the hook can assume *objp is null on entry.
00241  * This is not good practice, but enough existing hook implementations count
00242  * on it that we can't break compatibility by passing the starting object in
00243  * *objp without a new JSClass flag.
00244  */
00245 typedef JSBool
00246 (* JS_DLL_CALLBACK JSNewResolveOp)(JSContext *cx, JSObject *obj, jsval id,
00247                                    uintN flags, JSObject **objp);
00248 
00249 /*
00250  * Convert obj to the given type, returning true with the resulting value in
00251  * *vp on success, and returning false on error or exception.
00252  */
00253 typedef JSBool
00254 (* JS_DLL_CALLBACK JSConvertOp)(JSContext *cx, JSObject *obj, JSType type,
00255                                 jsval *vp);
00256 
00257 /*
00258  * Finalize obj, which the garbage collector has determined to be unreachable
00259  * from other live objects or from GC roots.  Obviously, finalizers must never
00260  * store a reference to obj.
00261  */
00262 typedef void
00263 (* JS_DLL_CALLBACK JSFinalizeOp)(JSContext *cx, JSObject *obj);
00264 
00265 /*
00266  * Used by JS_AddExternalStringFinalizer and JS_RemoveExternalStringFinalizer
00267  * to extend and reduce the set of string types finalized by the GC.
00268  */
00269 typedef void
00270 (* JS_DLL_CALLBACK JSStringFinalizeOp)(JSContext *cx, JSString *str);
00271 
00272 /*
00273  * The signature for JSClass.getObjectOps, used by JS_NewObject's internals
00274  * to discover the set of high-level object operations to use for new objects
00275  * of the given class.  All native objects have a JSClass, which is stored as
00276  * a private (int-tagged) pointer in obj->slots[JSSLOT_CLASS].  In contrast,
00277  * all native and host objects have a JSObjectMap at obj->map, which may be
00278  * shared among a number of objects, and which contains the JSObjectOps *ops
00279  * pointer used to dispatch object operations from API calls.
00280  *
00281  * Thus JSClass (which pre-dates JSObjectOps in the API) provides a low-level
00282  * interface to class-specific code and data, while JSObjectOps allows for a
00283  * higher level of operation, which does not use the object's class except to
00284  * find the class's JSObjectOps struct, by calling clasp->getObjectOps, and to
00285  * finalize the object.
00286  *
00287  * If this seems backwards, that's because it is!  API compatibility requires
00288  * a JSClass *clasp parameter to JS_NewObject, etc.  Most host objects do not
00289  * need to implement the larger JSObjectOps, and can share the common JSScope
00290  * code and data used by the native (js_ObjectOps, see jsobj.c) ops.
00291  *
00292  * Further extension to preserve API compatibility: if this function returns
00293  * a pointer to JSXMLObjectOps.base, not to JSObjectOps, then the engine calls
00294  * extended hooks needed for E4X.
00295  */
00296 typedef JSObjectOps *
00297 (* JS_DLL_CALLBACK JSGetObjectOps)(JSContext *cx, JSClass *clasp);
00298 
00299 /*
00300  * JSClass.checkAccess type: check whether obj[id] may be accessed per mode,
00301  * returning false on error/exception, true on success with obj[id]'s last-got
00302  * value in *vp, and its attributes in *attrsp.  As for JSPropertyOp above, id
00303  * is either a string or an int jsval.
00304  *
00305  * See JSCheckAccessIdOp, below, for the JSObjectOps counterpart, which takes
00306  * a jsid (a tagged int or aligned, unique identifier pointer) rather than a
00307  * jsval.  The native js_ObjectOps.checkAccess simply forwards to the object's
00308  * clasp->checkAccess, so that both JSClass and JSObjectOps implementors may
00309  * specialize access checks.
00310  */
00311 typedef JSBool
00312 (* JS_DLL_CALLBACK JSCheckAccessOp)(JSContext *cx, JSObject *obj, jsval id,
00313                                     JSAccessMode mode, jsval *vp);
00314 
00315 /*
00316  * Encode or decode an object, given an XDR state record representing external
00317  * data.  See jsxdrapi.h.
00318  */
00319 typedef JSBool
00320 (* JS_DLL_CALLBACK JSXDRObjectOp)(JSXDRState *xdr, JSObject **objp);
00321 
00322 /*
00323  * Check whether v is an instance of obj.  Return false on error or exception,
00324  * true on success with JS_TRUE in *bp if v is an instance of obj, JS_FALSE in
00325  * *bp otherwise.
00326  */
00327 typedef JSBool
00328 (* JS_DLL_CALLBACK JSHasInstanceOp)(JSContext *cx, JSObject *obj, jsval v,
00329                                     JSBool *bp);
00330 
00331 /*
00332  * Function type for JSClass.mark and JSObjectOps.mark, called from the GC to
00333  * scan live GC-things reachable from obj's private data structure.  For each
00334  * such thing, a mark implementation must call
00335  *
00336  *    JS_MarkGCThing(cx, thing, name, arg);
00337  *
00338  * The trailing name and arg parameters are used for GC_MARK_DEBUG-mode heap
00339  * dumping and ref-path tracing.  The mark function should pass a (typically
00340  * literal) string naming the private data member for name, and it must pass
00341  * the opaque arg parameter through from its caller.
00342  *
00343  * For the JSObjectOps.mark hook, the return value is the number of slots at
00344  * obj->slots to scan.  For JSClass.mark, the return value is ignored.
00345  *
00346  * NB: JSMarkOp implementations cannot allocate new GC-things (JS_NewObject
00347  * called from a mark function will fail silently, e.g.).
00348  */
00349 typedef uint32
00350 (* JS_DLL_CALLBACK JSMarkOp)(JSContext *cx, JSObject *obj, void *arg);
00351 
00352 /*
00353  * The optional JSClass.reserveSlots hook allows a class to make computed
00354  * per-instance object slots reservations, in addition to or instead of using
00355  * JSCLASS_HAS_RESERVED_SLOTS(n) in the JSClass.flags initializer to reserve
00356  * a constant-per-class number of slots.  Implementations of this hook should
00357  * return the number of slots to reserve, not including any reserved by using
00358  * JSCLASS_HAS_RESERVED_SLOTS(n) in JSClass.flags.
00359  *
00360  * NB: called with obj locked by the JSObjectOps-specific mutual exclusion
00361  * mechanism appropriate for obj, so don't nest other operations that might
00362  * also lock obj.
00363  */
00364 typedef uint32
00365 (* JS_DLL_CALLBACK JSReserveSlotsOp)(JSContext *cx, JSObject *obj);
00366 
00367 /* JSObjectOps function pointer typedefs. */
00368 
00369 /*
00370  * Create a new subclass of JSObjectMap (see jsobj.h), with the nrefs and ops
00371  * members initialized from the same-named parameters, and with the nslots and
00372  * freeslot members initialized according to ops and clasp.  Return null on
00373  * error, non-null on success.
00374  *
00375  * JSObjectMaps are reference-counted by generic code in the engine.  Usually,
00376  * the nrefs parameter to JSObjectOps.newObjectMap will be 1, to count the ref
00377  * returned to the caller on success.  After a successful construction, some
00378  * number of js_HoldObjectMap and js_DropObjectMap calls ensue.  When nrefs
00379  * reaches 0 due to a js_DropObjectMap call, JSObjectOps.destroyObjectMap will
00380  * be called to dispose of the map.
00381  */
00382 typedef JSObjectMap *
00383 (* JS_DLL_CALLBACK JSNewObjectMapOp)(JSContext *cx, jsrefcount nrefs,
00384                                      JSObjectOps *ops, JSClass *clasp,
00385                                      JSObject *obj);
00386 
00387 /*
00388  * Generic type for an infallible JSObjectMap operation, used currently by
00389  * JSObjectOps.destroyObjectMap.
00390  */
00391 typedef void
00392 (* JS_DLL_CALLBACK JSObjectMapOp)(JSContext *cx, JSObjectMap *map);
00393 
00394 /*
00395  * Look for id in obj and its prototype chain, returning false on error or
00396  * exception, true on success.  On success, return null in *propp if id was
00397  * not found.  If id was found, return the first object searching from obj
00398  * along its prototype chain in which id names a direct property in *objp, and
00399  * return a non-null, opaque property pointer in *propp.
00400  *
00401  * If JSLookupPropOp succeeds and returns with *propp non-null, that pointer
00402  * may be passed as the prop parameter to a JSAttributesOp, as a short-cut
00403  * that bypasses id re-lookup.  In any case, a non-null *propp result after a
00404  * successful lookup must be dropped via JSObjectOps.dropProperty.
00405  *
00406  * NB: successful return with non-null *propp means the implementation may
00407  * have locked *objp and added a reference count associated with *propp, so
00408  * callers should not risk deadlock by nesting or interleaving other lookups
00409  * or any obj-bearing ops before dropping *propp.
00410  */
00411 typedef JSBool
00412 (* JS_DLL_CALLBACK JSLookupPropOp)(JSContext *cx, JSObject *obj, jsid id,
00413                                    JSObject **objp, JSProperty **propp);
00414 
00415 /*
00416  * Define obj[id], a direct property of obj named id, having the given initial
00417  * value, with the specified getter, setter, and attributes.  If the propp out
00418  * param is non-null, *propp on successful return contains an opaque property
00419  * pointer usable as a speedup hint with JSAttributesOp.  But note that propp
00420  * may be null, indicating that the caller is not interested in recovering an
00421  * opaque pointer to the newly-defined property.
00422  *
00423  * If propp is non-null and JSDefinePropOp succeeds, its caller must be sure
00424  * to drop *propp using JSObjectOps.dropProperty in short order, just as with
00425  * JSLookupPropOp.
00426  */
00427 typedef JSBool
00428 (* JS_DLL_CALLBACK JSDefinePropOp)(JSContext *cx, JSObject *obj,
00429                                    jsid id, jsval value,
00430                                    JSPropertyOp getter, JSPropertyOp setter,
00431                                    uintN attrs, JSProperty **propp);
00432 
00433 /*
00434  * Get, set, or delete obj[id], returning false on error or exception, true
00435  * on success.  If getting or setting, the new value is returned in *vp on
00436  * success.  If deleting without error, *vp will be JSVAL_FALSE if obj[id] is
00437  * permanent, and JSVAL_TRUE if id named a direct property of obj that was in
00438  * fact deleted, or if id names no direct property of obj (id could name a
00439  * prototype property, or no property in obj or its prototype chain).
00440  */
00441 typedef JSBool
00442 (* JS_DLL_CALLBACK JSPropertyIdOp)(JSContext *cx, JSObject *obj, jsid id,
00443                                    jsval *vp);
00444 
00445 /*
00446  * Get or set attributes of the property obj[id].  Return false on error or
00447  * exception, true with current attributes in *attrsp.  If prop is non-null,
00448  * it must come from the *propp out parameter of a prior JSDefinePropOp or
00449  * JSLookupPropOp call.
00450  */
00451 typedef JSBool
00452 (* JS_DLL_CALLBACK JSAttributesOp)(JSContext *cx, JSObject *obj, jsid id,
00453                                    JSProperty *prop, uintN *attrsp);
00454 
00455 /*
00456  * JSObjectOps.checkAccess type: check whether obj[id] may be accessed per
00457  * mode, returning false on error/exception, true on success with obj[id]'s
00458  * last-got value in *vp, and its attributes in *attrsp.
00459  */
00460 typedef JSBool
00461 (* JS_DLL_CALLBACK JSCheckAccessIdOp)(JSContext *cx, JSObject *obj, jsid id,
00462                                       JSAccessMode mode, jsval *vp,
00463                                       uintN *attrsp);
00464 
00465 /*
00466  * A generic type for functions mapping an object to another object, or null
00467  * if an error or exception was thrown on cx.  Used by JSObjectOps.thisObject
00468  * at present.
00469  */
00470 typedef JSObject *
00471 (* JS_DLL_CALLBACK JSObjectOp)(JSContext *cx, JSObject *obj);
00472 
00473 /*
00474  * A generic type for functions taking a context, object, and property, with
00475  * no return value.  Used by JSObjectOps.dropProperty currently (see above,
00476  * JSDefinePropOp and JSLookupPropOp, for the object-locking protocol in which
00477  * dropProperty participates).
00478  */
00479 typedef void
00480 (* JS_DLL_CALLBACK JSPropertyRefOp)(JSContext *cx, JSObject *obj,
00481                                     JSProperty *prop);
00482 
00483 /*
00484  * Function type for JSObjectOps.setProto and JSObjectOps.setParent.  These
00485  * hooks must check for cycles without deadlocking, and otherwise take special
00486  * steps.  See jsobj.c, js_SetProtoOrParent, for an example.
00487  */
00488 typedef JSBool
00489 (* JS_DLL_CALLBACK JSSetObjectSlotOp)(JSContext *cx, JSObject *obj,
00490                                       uint32 slot, JSObject *pobj);
00491 
00492 /*
00493  * Get and set a required slot, one that should already have been allocated.
00494  * These operations are infallible, so required slots must be pre-allocated,
00495  * or implementations must suppress out-of-memory errors.  The native ops
00496  * (js_ObjectOps, see jsobj.c) access slots reserved by including a call to
00497  * the JSCLASS_HAS_RESERVED_SLOTS(n) macro in the JSClass.flags initializer.
00498  *
00499  * NB: the slot parameter is a zero-based index into obj->slots[], unlike the
00500  * index parameter to the JS_GetReservedSlot and JS_SetReservedSlot API entry
00501  * points, which is a zero-based index into the JSCLASS_RESERVED_SLOTS(clasp)
00502  * reserved slots that come after the initial well-known slots: proto, parent,
00503  * class, and optionally, the private data slot.
00504  */
00505 typedef jsval
00506 (* JS_DLL_CALLBACK JSGetRequiredSlotOp)(JSContext *cx, JSObject *obj,
00507                                         uint32 slot);
00508 
00509 typedef JSBool
00510 (* JS_DLL_CALLBACK JSSetRequiredSlotOp)(JSContext *cx, JSObject *obj,
00511                                         uint32 slot, jsval v);
00512 
00513 typedef JSObject *
00514 (* JS_DLL_CALLBACK JSGetMethodOp)(JSContext *cx, JSObject *obj, jsid id,
00515                                   jsval *vp);
00516 
00517 typedef JSBool
00518 (* JS_DLL_CALLBACK JSSetMethodOp)(JSContext *cx, JSObject *obj, jsid id,
00519                                   jsval *vp);
00520 
00521 typedef JSBool
00522 (* JS_DLL_CALLBACK JSEnumerateValuesOp)(JSContext *cx, JSObject *obj,
00523                                         JSIterateOp enum_op,
00524                                         jsval *statep, jsid *idp, jsval *vp);
00525 
00526 typedef JSBool
00527 (* JS_DLL_CALLBACK JSEqualityOp)(JSContext *cx, JSObject *obj, jsval v,
00528                                  JSBool *bp);
00529 
00530 typedef JSBool
00531 (* JS_DLL_CALLBACK JSConcatenateOp)(JSContext *cx, JSObject *obj, jsval v,
00532                                     jsval *vp);
00533 
00534 /* Typedef for native functions called by the JS VM. */
00535 
00536 typedef JSBool
00537 (* JS_DLL_CALLBACK JSNative)(JSContext *cx, JSObject *obj, uintN argc,
00538                              jsval *argv, jsval *rval);
00539 
00540 /* Callbacks and their arguments. */
00541 
00542 typedef enum JSContextOp {
00543     JSCONTEXT_NEW,
00544     JSCONTEXT_DESTROY
00545 } JSContextOp;
00546 
00547 /*
00548  * The possible values for contextOp when the runtime calls the callback are:
00549  *   JSCONTEXT_NEW      JS_NewContext succesfully created a new JSContext
00550  *                      instance. The callback can initialize the instance as
00551  *                      required. If the callback returns false, the instance
00552  *                      will be destroyed and JS_NewContext returns null. In
00553  *                      this case the callback is not called again.
00554  *   JSCONTEXT_DESTROY  One of JS_DestroyContext* methods is called. The
00555  *                      callback may perform its own cleanup and must always
00556  *                      return true.
00557  *   Any other value    For future compatibility the callback must do nothing
00558  *                      and return true in this case.
00559  */
00560 typedef JSBool
00561 (* JS_DLL_CALLBACK JSContextCallback)(JSContext *cx, uintN contextOp);
00562 
00563 typedef enum JSGCStatus {
00564     JSGC_BEGIN,
00565     JSGC_END,
00566     JSGC_MARK_END,
00567     JSGC_FINALIZE_END
00568 } JSGCStatus;
00569 
00570 typedef JSBool
00571 (* JS_DLL_CALLBACK JSGCCallback)(JSContext *cx, JSGCStatus status);
00572 
00573 typedef JSBool
00574 (* JS_DLL_CALLBACK JSBranchCallback)(JSContext *cx, JSScript *script);
00575 
00576 typedef void
00577 (* JS_DLL_CALLBACK JSErrorReporter)(JSContext *cx, const char *message,
00578                                     JSErrorReport *report);
00579 
00580 /*
00581  * Possible exception types. These types are part of a JSErrorFormatString
00582  * structure. They define which error to throw in case of a runtime error.
00583  * JSEXN_NONE marks an unthrowable error.
00584  */
00585 typedef enum JSExnType {
00586     JSEXN_NONE = -1,
00587       JSEXN_ERR,
00588         JSEXN_INTERNALERR,
00589         JSEXN_EVALERR,
00590         JSEXN_RANGEERR,
00591         JSEXN_REFERENCEERR,
00592         JSEXN_SYNTAXERR,
00593         JSEXN_TYPEERR,
00594         JSEXN_URIERR,
00595         JSEXN_LIMIT
00596 } JSExnType;
00597 
00598 typedef struct JSErrorFormatString {
00599     /* The error format string (UTF-8 if JS_C_STRINGS_ARE_UTF8 is defined). */
00600     const char *format;
00601 
00602     /* The number of arguments to expand in the formatted error message. */
00603     uint16 argCount;
00604 
00605     /* One of the JSExnType constants above. */
00606     int16 exnType;
00607 } JSErrorFormatString;
00608 
00609 typedef const JSErrorFormatString *
00610 (* JS_DLL_CALLBACK JSErrorCallback)(void *userRef, const char *locale,
00611                                     const uintN errorNumber);
00612 
00613 #ifdef va_start
00614 #define JS_ARGUMENT_FORMATTER_DEFINED 1
00615 
00616 typedef JSBool
00617 (* JS_DLL_CALLBACK JSArgumentFormatter)(JSContext *cx, const char *format,
00618                                         JSBool fromJS, jsval **vpp,
00619                                         va_list *app);
00620 #endif
00621 
00622 typedef JSBool
00623 (* JS_DLL_CALLBACK JSLocaleToUpperCase)(JSContext *cx, JSString *src,
00624                                         jsval *rval);
00625 
00626 typedef JSBool
00627 (* JS_DLL_CALLBACK JSLocaleToLowerCase)(JSContext *cx, JSString *src,
00628                                         jsval *rval);
00629 
00630 typedef JSBool
00631 (* JS_DLL_CALLBACK JSLocaleCompare)(JSContext *cx,
00632                                     JSString *src1, JSString *src2,
00633                                     jsval *rval);
00634 
00635 typedef JSBool
00636 (* JS_DLL_CALLBACK JSLocaleToUnicode)(JSContext *cx, char *src, jsval *rval);
00637 
00638 /*
00639  * Security protocol types.
00640  */
00641 typedef struct JSPrincipals JSPrincipals;
00642 
00643 /*
00644  * XDR-encode or -decode a principals instance, based on whether xdr->mode is
00645  * JSXDR_ENCODE, in which case *principalsp should be encoded; or JSXDR_DECODE,
00646  * in which case implementations must return a held (via JSPRINCIPALS_HOLD),
00647  * non-null *principalsp out parameter.  Return true on success, false on any
00648  * error, which the implementation must have reported.
00649  */
00650 typedef JSBool
00651 (* JS_DLL_CALLBACK JSPrincipalsTranscoder)(JSXDRState *xdr,
00652                                            JSPrincipals **principalsp);
00653 
00654 /*
00655  * Return a weak reference to the principals associated with obj, possibly via
00656  * the immutable parent chain leading from obj to a top-level container (e.g.,
00657  * a window object in the DOM level 0).  If there are no principals associated
00658  * with obj, return null.  Therefore null does not mean an error was reported;
00659  * in no event should an error be reported or an exception be thrown by this
00660  * callback's implementation.
00661  */
00662 typedef JSPrincipals *
00663 (* JS_DLL_CALLBACK JSObjectPrincipalsFinder)(JSContext *cx, JSObject *obj);
00664 
00665 JS_END_EXTERN_C
00666 
00667 #endif /* jspubtd_h___ */