js/src/jspubtd.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla Communicator client code, released
  17  * March 31, 1998.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 1998
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either of the GNU General Public License Version 2 or later (the "GPL"),
  28  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #ifndef jspubtd_h___
  41 #define jspubtd_h___
  42 /*
  43  * JS public API typedefs.
  44  */
  45 #include "jstypes.h"
  46 #include "jscompat.h"
  47
  48 JS_BEGIN_EXTERN_C
  49
  50 /* Scalar typedefs. */
  51 typedef uint16    jschar;
  52 typedef int32     jsint;
  53 typedef uint32    jsuint;
  54 typedef float64   jsdouble;
  55 typedef jsword    jsval;
  56 typedef jsword    jsid;
  57 typedef int32     jsrefcount;   /* PRInt32 if JS_THREADSAFE, see jslock.h */
  58
  59 /*
  60  * Run-time version enumeration.  See jsconfig.h for compile-time counterparts
  61  * to these values that may be selected by the JS_VERSION macro, and tested by
  62  * #if expressions.
  63  */
  64 typedef enum JSVersion {
  65     JSVERSION_1_0     = 100,
  66     JSVERSION_1_1     = 110,
  67     JSVERSION_1_2     = 120,
  68     JSVERSION_1_3     = 130,
  69     JSVERSION_1_4     = 140,
  70     JSVERSION_ECMA_3  = 148,
  71     JSVERSION_1_5     = 150,
  72     JSVERSION_1_6     = 160,
  73     JSVERSION_1_7     = 170,
  74     JSVERSION_1_8     = 180,
  75     JSVERSION_DEFAULT = 0,
  76     JSVERSION_UNKNOWN = -1,
  77     JSVERSION_LATEST  = JSVERSION_1_8
  78 } JSVersion;
  79
  80 #define JSVERSION_IS_ECMA(version) \
  81     ((version) == JSVERSION_DEFAULT || (version) >= JSVERSION_1_3)
  82
  83 /* Result of typeof operator enumeration. */
  84 typedef enum JSType {
  85     JSTYPE_VOID,                /* undefined */
  86     JSTYPE_OBJECT,              /* object */
  87     JSTYPE_FUNCTION,            /* function */
  88     JSTYPE_STRING,              /* string */
  89     JSTYPE_NUMBER,              /* number */
  90     JSTYPE_BOOLEAN,             /* boolean */
  91     JSTYPE_NULL,                /* null */
  92     JSTYPE_XML,                 /* xml object */
  93     JSTYPE_LIMIT
  94 } JSType;
  95
  96 /* Dense index into cached prototypes and class atoms for standard objects. */
  97 typedef enum JSProtoKey {
  98 #define JS_PROTO(name,code,init) JSProto_##name = code,
  99 #include "jsproto.tbl"
 100 #undef JS_PROTO
 101     JSProto_LIMIT
 102 } JSProtoKey;
 103
 104 /* JSObjectOps.checkAccess mode enumeration. */
 105 typedef enum JSAccessMode {
 106     JSACC_PROTO  = 0,           /* XXXbe redundant w.r.t. id */
 107     JSACC_PARENT = 1,           /* XXXbe redundant w.r.t. id */
 108     JSACC_IMPORT = 2,           /* import foo.bar */
 109     JSACC_WATCH  = 3,           /* a watchpoint on object foo for id 'bar' */
 110     JSACC_READ   = 4,           /* a "get" of foo.bar */
 111     JSACC_WRITE  = 8,           /* a "set" of foo.bar = baz */
 112     JSACC_LIMIT
 113 } JSAccessMode;
 114
 115 #define JSACC_TYPEMASK          (JSACC_WRITE - 1)
 116
 117 /*
 118  * This enum type is used to control the behavior of a JSObject property
 119  * iterator function that has type JSNewEnumerate.
 120  */
 121 typedef enum JSIterateOp {
 122     JSENUMERATE_INIT,       /* Create new iterator state */
 123     JSENUMERATE_NEXT,       /* Iterate once */
 124     JSENUMERATE_DESTROY     /* Destroy iterator state */
 125 } JSIterateOp;
 126
 127 /* Struct typedefs. */
 128 typedef struct JSClass           JSClass;
 129 typedef struct JSExtendedClass   JSExtendedClass;
 130 typedef struct JSConstDoubleSpec JSConstDoubleSpec;
 131 typedef struct JSContext         JSContext;
 132 typedef struct JSErrorReport     JSErrorReport;
 133 typedef struct JSFunction        JSFunction;
 134 typedef struct JSFunctionSpec    JSFunctionSpec;
 135 typedef struct JSFastNativeSpec  JSFastNativeSpec;
 136 typedef struct JSFastNativeBlock JSFastNativeBlock;
 137 typedef struct JSTracer          JSTracer;
 138 typedef struct JSIdArray         JSIdArray;
 139 typedef struct JSProperty        JSProperty;
 140 typedef struct JSPropertySpec    JSPropertySpec;
 141 typedef struct JSObject          JSObject;
 142 typedef struct JSObjectMap       JSObjectMap;
 143 typedef struct JSObjectOps       JSObjectOps;
 144 typedef struct JSXMLObjectOps    JSXMLObjectOps;
 145 typedef struct JSRuntime         JSRuntime;
 146 typedef struct JSRuntime         JSTaskState;   /* XXX deprecated name */
 147 typedef struct JSScript          JSScript;
 148 typedef struct JSStackFrame      JSStackFrame;
 149 typedef struct JSString          JSString;
 150 typedef struct JSXDRState        JSXDRState;
 151 typedef struct JSExceptionState  JSExceptionState;
 152 typedef struct JSLocaleCallbacks JSLocaleCallbacks;
 153
 154 /* JSClass (and JSObjectOps where appropriate) function pointer typedefs. */
 155
 156 /*
 157  * Add, delete, get or set a property named by id in obj.  Note the jsval id
 158  * type -- id may be a string (Unicode property identifier) or an int (element
 159  * index).  The *vp out parameter, on success, is the new property value after
 160  * an add, get, or set.  After a successful delete, *vp is JSVAL_FALSE iff
 161  * obj[id] can't be deleted (because it's permanent).
 162  */
 163 typedef JSBool
 164 (* JS_DLL_CALLBACK JSPropertyOp)(JSContext *cx, JSObject *obj, jsval id,
 165                                  jsval *vp);
 166
 167 /*
 168  * This function type is used for callbacks that enumerate the properties of
 169  * a JSObject.  The behavior depends on the value of enum_op:
 170  *
 171  *  JSENUMERATE_INIT
 172  *    A new, opaque iterator state should be allocated and stored in *statep.
 173  *    (You can use PRIVATE_TO_JSVAL() to tag the pointer to be stored).
 174  *
 175  *    The number of properties that will be enumerated should be returned as
 176  *    an integer jsval in *idp, if idp is non-null, and provided the number of
 177  *    enumerable properties is known.  If idp is non-null and the number of
 178  *    enumerable properties can't be computed in advance, *idp should be set
 179  *    to JSVAL_ZERO.
 180  *
 181  *  JSENUMERATE_NEXT
 182  *    A previously allocated opaque iterator state is passed in via statep.
 183  *    Return the next jsid in the iteration using *idp.  The opaque iterator
 184  *    state pointed at by statep is destroyed and *statep is set to JSVAL_NULL
 185  *    if there are no properties left to enumerate.
 186  *
 187  *  JSENUMERATE_DESTROY
 188  *    Destroy the opaque iterator state previously allocated in *statep by a
 189  *    call to this function when enum_op was JSENUMERATE_INIT.
 190  *
 191  * The return value is used to indicate success, with a value of JS_FALSE
 192  * indicating failure.
 193  */
 194 typedef JSBool
 195 (* JS_DLL_CALLBACK JSNewEnumerateOp)(JSContext *cx, JSObject *obj,
 196                                      JSIterateOp enum_op,
 197                                      jsval *statep, jsid *idp);
 198
 199 /*
 200  * The old-style JSClass.enumerate op should define all lazy properties not
 201  * yet reflected in obj.
 202  */
 203 typedef JSBool
 204 (* JS_DLL_CALLBACK JSEnumerateOp)(JSContext *cx, JSObject *obj);
 205
 206 /*
 207  * Resolve a lazy property named by id in obj by defining it directly in obj.
 208  * Lazy properties are those reflected from some peer native property space
 209  * (e.g., the DOM attributes for a given node reflected as obj) on demand.
 210  *
 211  * JS looks for a property in an object, and if not found, tries to resolve
 212  * the given id.  If resolve succeeds, the engine looks again in case resolve
 213  * defined obj[id].  If no such property exists directly in obj, the process
 214  * is repeated with obj's prototype, etc.
 215  *
 216  * NB: JSNewResolveOp provides a cheaper way to resolve lazy properties.
 217  */
 218 typedef JSBool
 219 (* JS_DLL_CALLBACK JSResolveOp)(JSContext *cx, JSObject *obj, jsval id);
 220
 221 /*
 222  * Like JSResolveOp, but flags provide contextual information as follows:
 223  *
 224  *  JSRESOLVE_QUALIFIED   a qualified property id: obj.id or obj[id], not id
 225  *  JSRESOLVE_ASSIGNING   obj[id] is on the left-hand side of an assignment
 226  *  JSRESOLVE_DETECTING   'if (o.p)...' or similar detection opcode sequence
 227  *  JSRESOLVE_DECLARING   var, const, or function prolog declaration opcode
 228  *  JSRESOLVE_CLASSNAME   class name used when constructing
 229  *
 230  * The *objp out parameter, on success, should be null to indicate that id
 231  * was not resolved; and non-null, referring to obj or one of its prototypes,
 232  * if id was resolved.
 233  *
 234  * This hook instead of JSResolveOp is called via the JSClass.resolve member
 235  * if JSCLASS_NEW_RESOLVE is set in JSClass.flags.
 236  *
 237  * Setting JSCLASS_NEW_RESOLVE and JSCLASS_NEW_RESOLVE_GETS_START further
 238  * extends this hook by passing in the starting object on the prototype chain
 239  * via *objp.  Thus a resolve hook implementation may define the property id
 240  * being resolved in the object in which the id was first sought, rather than
 241  * in a prototype object whose class led to the resolve hook being called.
 242  *
 243  * When using JSCLASS_NEW_RESOLVE_GETS_START, the resolve hook must therefore
 244  * null *objp to signify "not resolved".  With only JSCLASS_NEW_RESOLVE and no
 245  * JSCLASS_NEW_RESOLVE_GETS_START, the hook can assume *objp is null on entry.
 246  * This is not good practice, but enough existing hook implementations count
 247  * on it that we can't break compatibility by passing the starting object in
 248  * *objp without a new JSClass flag.
 249  */
 250 typedef JSBool
 251 (* JS_DLL_CALLBACK JSNewResolveOp)(JSContext *cx, JSObject *obj, jsval id,
 252                                    uintN flags, JSObject **objp);
 253
 254 /*
 255  * Convert obj to the given type, returning true with the resulting value in
 256  * *vp on success, and returning false on error or exception.
 257  */
 258 typedef JSBool
 259 (* JS_DLL_CALLBACK JSConvertOp)(JSContext *cx, JSObject *obj, JSType type,
 260                                 jsval *vp);
 261
 262 /*
 263  * Finalize obj, which the garbage collector has determined to be unreachable
 264  * from other live objects or from GC roots.  Obviously, finalizers must never
 265  * store a reference to obj.
 266  */
 267 typedef void
 268 (* JS_DLL_CALLBACK JSFinalizeOp)(JSContext *cx, JSObject *obj);
 269
 270 /*
 271  * Used by JS_AddExternalStringFinalizer and JS_RemoveExternalStringFinalizer
 272  * to extend and reduce the set of string types finalized by the GC.
 273  */
 274 typedef void
 275 (* JS_DLL_CALLBACK JSStringFinalizeOp)(JSContext *cx, JSString *str);
 276
 277 /*
 278  * The signature for JSClass.getObjectOps, used by JS_NewObject's internals
 279  * to discover the set of high-level object operations to use for new objects
 280  * of the given class.  All native objects have a JSClass, which is stored as
 281  * a private (int-tagged) pointer in obj slots. In contrast, all native and
 282  * host objects have a JSObjectMap at obj->map, which may be shared among a
 283  * number of objects, and which contains the JSObjectOps *ops pointer used to
 284  * dispatch object operations from API calls.
 285  *
 286  * Thus JSClass (which pre-dates JSObjectOps in the API) provides a low-level
 287  * interface to class-specific code and data, while JSObjectOps allows for a
 288  * higher level of operation, which does not use the object's class except to
 289  * find the class's JSObjectOps struct, by calling clasp->getObjectOps, and to
 290  * finalize the object.
 291  *
 292  * If this seems backwards, that's because it is!  API compatibility requires
 293  * a JSClass *clasp parameter to JS_NewObject, etc.  Most host objects do not
 294  * need to implement the larger JSObjectOps, and can share the common JSScope
 295  * code and data used by the native (js_ObjectOps, see jsobj.c) ops.
 296  *
 297  * Further extension to preserve API compatibility: if this function returns
 298  * a pointer to JSXMLObjectOps.base, not to JSObjectOps, then the engine calls
 299  * extended hooks needed for E4X.
 300  */
 301 typedef JSObjectOps *
 302 (* JS_DLL_CALLBACK JSGetObjectOps)(JSContext *cx, JSClass *clasp);
 303
 304 /*
 305  * JSClass.checkAccess type: check whether obj[id] may be accessed per mode,
 306  * returning false on error/exception, true on success with obj[id]'s last-got
 307  * value in *vp, and its attributes in *attrsp.  As for JSPropertyOp above, id
 308  * is either a string or an int jsval.
 309  *
 310  * See JSCheckAccessIdOp, below, for the JSObjectOps counterpart, which takes
 311  * a jsid (a tagged int or aligned, unique identifier pointer) rather than a
 312  * jsval.  The native js_ObjectOps.checkAccess simply forwards to the object's
 313  * clasp->checkAccess, so that both JSClass and JSObjectOps implementors may
 314  * specialize access checks.
 315  */
 316 typedef JSBool
 317 (* JS_DLL_CALLBACK JSCheckAccessOp)(JSContext *cx, JSObject *obj, jsval id,
 318                                     JSAccessMode mode, jsval *vp);
 319
 320 /*
 321  * Encode or decode an object, given an XDR state record representing external
 322  * data.  See jsxdrapi.h.
 323  */
 324 typedef JSBool
 325 (* JS_DLL_CALLBACK JSXDRObjectOp)(JSXDRState *xdr, JSObject **objp);
 326
 327 /*
 328  * Check whether v is an instance of obj.  Return false on error or exception,
 329  * true on success with JS_TRUE in *bp if v is an instance of obj, JS_FALSE in
 330  * *bp otherwise.
 331  */
 332 typedef JSBool
 333 (* JS_DLL_CALLBACK JSHasInstanceOp)(JSContext *cx, JSObject *obj, jsval v,
 334                                     JSBool *bp);
 335
 336 /*
 337  * Deprecated function type for JSClass.mark. All new code should define
 338  * JSTraceOp instead to ensure the traversal of traceable things stored in
 339  * the native structures.
 340  */
 341 typedef uint32
 342 (* JS_DLL_CALLBACK JSMarkOp)(JSContext *cx, JSObject *obj, void *arg);
 343
 344 /*
 345  * Function type for trace operation of the class called to enumerate all
 346  * traceable things reachable from obj's private data structure. For each such
 347  * thing, a trace implementation must call
 348  *
 349  *    JS_CallTracer(trc, thing, kind);
 350  *
 351  * or one of its convenience macros as described in jsapi.h.
 352  *
 353  * JSTraceOp implementation can assume that no other threads mutates object
 354  * state. It must not change state of the object or corresponding native
 355  * structures. The only exception for this rule is the case when the embedding
 356  * needs a tight integration with GC. In that case the embedding can check if
 357  * the traversal is a part of the marking phase through calling
 358  * JS_IsGCMarkingTracer and apply a special code like emptying caches or
 359  * marking its native structures.
 360  *
 361  * To define the tracer for a JSClass, the implementation must add
 362  * JSCLASS_MARK_IS_TRACE to class flags and use JS_CLASS_TRACE(method)
 363  * macro below to convert JSTraceOp to JSMarkOp when initializing or
 364  * assigning JSClass.mark field.
 365  */
 366 typedef void
 367 (* JS_DLL_CALLBACK JSTraceOp)(JSTracer *trc, JSObject *obj);
 368
 369 #if defined __GNUC__ && __GNUC__ >= 4 && !defined __cplusplus
 370 # define JS_CLASS_TRACE(method)                                               \
 371     (__builtin_types_compatible_p(JSTraceOp, __typeof(&(method)))             \
 372      ? (JSMarkOp)(method)                                                     \
 373      : js_WrongTypeForClassTracer)
 374
 375 extern JSMarkOp js_WrongTypeForClassTracer;
 376
 377 #else
 378 # define JS_CLASS_TRACE(method) ((JSMarkOp)(method))
 379 #endif
 380
 381 /*
 382  * Tracer callback, called for each traceable thing directly refrenced by a
 383  * particular object or runtime structure. It is the callback responsibility
 384  * to ensure the traversal of the full object graph via calling eventually
 385  * JS_TraceChildren on the passed thing. In this case the callback must be
 386  * prepared to deal with cycles in the traversal graph.
 387  *
 388  * kind argument is one of JSTRACE_OBJECT, JSTRACE_DOUBLE, JSTRACE_STRING or
 389  * a tag denoting internal implementation-specific traversal kind. In the
 390  * latter case the only operations on thing that the callback can do is to call
 391  * JS_TraceChildren or DEBUG-only JS_PrintTraceThingInfo.
 392  */
 393 typedef void
 394 (* JS_DLL_CALLBACK JSTraceCallback)(JSTracer *trc, void *thing, uint32 kind);
 395
 396 /*
 397  * DEBUG only callback that JSTraceOp implementation can provide to return
 398  * a string describing the reference traced with JS_CallTracer.
 399  */
 400 #ifdef DEBUG
 401 typedef void
 402 (* JS_DLL_CALLBACK JSTraceNamePrinter)(JSTracer *trc, char *buf,
 403                                        size_t bufsize);
 404 #endif
 405
 406 /*
 407  * The optional JSClass.reserveSlots hook allows a class to make computed
 408  * per-instance object slots reservations, in addition to or instead of using
 409  * JSCLASS_HAS_RESERVED_SLOTS(n) in the JSClass.flags initializer to reserve
 410  * a constant-per-class number of slots.  Implementations of this hook should
 411  * return the number of slots to reserve, not including any reserved by using
 412  * JSCLASS_HAS_RESERVED_SLOTS(n) in JSClass.flags.
 413  *
 414  * NB: called with obj locked by the JSObjectOps-specific mutual exclusion
 415  * mechanism appropriate for obj, so don't nest other operations that might
 416  * also lock obj.
 417  */
 418 typedef uint32
 419 (* JS_DLL_CALLBACK JSReserveSlotsOp)(JSContext *cx, JSObject *obj);
 420
 421 /* JSObjectOps function pointer typedefs. */
 422
 423 /*
 424  * Create a new subclass of JSObjectMap (see jsobj.h), with the nrefs and ops
 425  * members initialized from the same-named parameters, and with the nslots and
 426  * freeslot members initialized according to ops and clasp.  Return null on
 427  * error, non-null on success.
 428  *
 429  * JSObjectMaps are reference-counted by generic code in the engine.  Usually,
 430  * the nrefs parameter to JSObjectOps.newObjectMap will be 1, to count the ref
 431  * returned to the caller on success.  After a successful construction, some
 432  * number of js_HoldObjectMap and js_DropObjectMap calls ensue.  When nrefs
 433  * reaches 0 due to a js_DropObjectMap call, JSObjectOps.destroyObjectMap will
 434  * be called to dispose of the map.
 435  */
 436 typedef JSObjectMap *
 437 (* JS_DLL_CALLBACK JSNewObjectMapOp)(JSContext *cx, jsrefcount nrefs,
 438                                      JSObjectOps *ops, JSClass *clasp,
 439                                      JSObject *obj);
 440
 441 /*
 442  * Generic type for an infallible JSObjectMap operation, used currently by
 443  * JSObjectOps.destroyObjectMap.
 444  */
 445 typedef void
 446 (* JS_DLL_CALLBACK JSObjectMapOp)(JSContext *cx, JSObjectMap *map);
 447
 448 /*
 449  * Look for id in obj and its prototype chain, returning false on error or
 450  * exception, true on success.  On success, return null in *propp if id was
 451  * not found.  If id was found, return the first object searching from obj
 452  * along its prototype chain in which id names a direct property in *objp, and
 453  * return a non-null, opaque property pointer in *propp.
 454  *
 455  * If JSLookupPropOp succeeds and returns with *propp non-null, that pointer
 456  * may be passed as the prop parameter to a JSAttributesOp, as a short-cut
 457  * that bypasses id re-lookup.  In any case, a non-null *propp result after a
 458  * successful lookup must be dropped via JSObjectOps.dropProperty.
 459  *
 460  * NB: successful return with non-null *propp means the implementation may
 461  * have locked *objp and added a reference count associated with *propp, so
 462  * callers should not risk deadlock by nesting or interleaving other lookups
 463  * or any obj-bearing ops before dropping *propp.
 464  */
 465 typedef JSBool
 466 (* JS_DLL_CALLBACK JSLookupPropOp)(JSContext *cx, JSObject *obj, jsid id,
 467                                    JSObject **objp, JSProperty **propp);
 468
 469 /*
 470  * Define obj[id], a direct property of obj named id, having the given initial
 471  * value, with the specified getter, setter, and attributes.  If the propp out
 472  * param is non-null, *propp on successful return contains an opaque property
 473  * pointer usable as a speedup hint with JSAttributesOp.  But note that propp
 474  * may be null, indicating that the caller is not interested in recovering an
 475  * opaque pointer to the newly-defined property.
 476  *
 477  * If propp is non-null and JSDefinePropOp succeeds, its caller must be sure
 478  * to drop *propp using JSObjectOps.dropProperty in short order, just as with
 479  * JSLookupPropOp.
 480  */
 481 typedef JSBool
 482 (* JS_DLL_CALLBACK JSDefinePropOp)(JSContext *cx, JSObject *obj,
 483                                    jsid id, jsval value,
 484                                    JSPropertyOp getter, JSPropertyOp setter,
 485                                    uintN attrs, JSProperty **propp);
 486
 487 /*
 488  * Get, set, or delete obj[id], returning false on error or exception, true
 489  * on success.  If getting or setting, the new value is returned in *vp on
 490  * success.  If deleting without error, *vp will be JSVAL_FALSE if obj[id] is
 491  * permanent, and JSVAL_TRUE if id named a direct property of obj that was in
 492  * fact deleted, or if id names no direct property of obj (id could name a
 493  * prototype property, or no property in obj or its prototype chain).
 494  */
 495 typedef JSBool
 496 (* JS_DLL_CALLBACK JSPropertyIdOp)(JSContext *cx, JSObject *obj, jsid id,
 497                                    jsval *vp);
 498
 499 /*
 500  * Get or set attributes of the property obj[id].  Return false on error or
 501  * exception, true with current attributes in *attrsp.  If prop is non-null,
 502  * it must come from the *propp out parameter of a prior JSDefinePropOp or
 503  * JSLookupPropOp call.
 504  */
 505 typedef JSBool
 506 (* JS_DLL_CALLBACK JSAttributesOp)(JSContext *cx, JSObject *obj, jsid id,
 507                                    JSProperty *prop, uintN *attrsp);
 508
 509 /*
 510  * JSObjectOps.checkAccess type: check whether obj[id] may be accessed per
 511  * mode, returning false on error/exception, true on success with obj[id]'s
 512  * last-got value in *vp, and its attributes in *attrsp.
 513  */
 514 typedef JSBool
 515 (* JS_DLL_CALLBACK JSCheckAccessIdOp)(JSContext *cx, JSObject *obj, jsid id,
 516                                       JSAccessMode mode, jsval *vp,
 517                                       uintN *attrsp);
 518
 519 /*
 520  * A generic type for functions mapping an object to another object, or null
 521  * if an error or exception was thrown on cx.  Used by JSObjectOps.thisObject
 522  * at present.
 523  */
 524 typedef JSObject *
 525 (* JS_DLL_CALLBACK JSObjectOp)(JSContext *cx, JSObject *obj);
 526
 527 /*
 528  * A generic type for functions taking a context, object, and property, with
 529  * no return value.  Used by JSObjectOps.dropProperty currently (see above,
 530  * JSDefinePropOp and JSLookupPropOp, for the object-locking protocol in which
 531  * dropProperty participates).
 532  */
 533 typedef void
 534 (* JS_DLL_CALLBACK JSPropertyRefOp)(JSContext *cx, JSObject *obj,
 535                                     JSProperty *prop);
 536
 537 /*
 538  * Function type for JSObjectOps.setProto and JSObjectOps.setParent.  These
 539  * hooks must check for cycles without deadlocking, and otherwise take special
 540  * steps.  See jsobj.c, js_SetProtoOrParent, for an example.
 541  */
 542 typedef JSBool
 543 (* JS_DLL_CALLBACK JSSetObjectSlotOp)(JSContext *cx, JSObject *obj,
 544                                       uint32 slot, JSObject *pobj);
 545
 546 /*
 547  * Get and set a required slot, one that should already have been allocated.
 548  * These operations are infallible, so required slots must be pre-allocated,
 549  * or implementations must suppress out-of-memory errors.  The native ops
 550  * (js_ObjectOps, see jsobj.c) access slots reserved by including a call to
 551  * the JSCLASS_HAS_RESERVED_SLOTS(n) macro in the JSClass.flags initializer.
 552  *
 553  * NB: the slot parameter is a zero-based index into obj slots, unlike the
 554  * index parameter to the JS_GetReservedSlot and JS_SetReservedSlot API entry
 555  * points, which is a zero-based index into the JSCLASS_RESERVED_SLOTS(clasp)
 556  * reserved slots that come after the initial well-known slots: proto, parent,
 557  * class, and optionally, the private data slot.
 558  */
 559 typedef jsval
 560 (* JS_DLL_CALLBACK JSGetRequiredSlotOp)(JSContext *cx, JSObject *obj,
 561                                         uint32 slot);
 562
 563 typedef JSBool
 564 (* JS_DLL_CALLBACK JSSetRequiredSlotOp)(JSContext *cx, JSObject *obj,
 565                                         uint32 slot, jsval v);
 566
 567 typedef JSObject *
 568 (* JS_DLL_CALLBACK JSGetMethodOp)(JSContext *cx, JSObject *obj, jsid id,
 569                                   jsval *vp);
 570
 571 typedef JSBool
 572 (* JS_DLL_CALLBACK JSSetMethodOp)(JSContext *cx, JSObject *obj, jsid id,
 573                                   jsval *vp);
 574
 575 typedef JSBool
 576 (* JS_DLL_CALLBACK JSEnumerateValuesOp)(JSContext *cx, JSObject *obj,
 577                                         JSIterateOp enum_op,
 578                                         jsval *statep, jsid *idp, jsval *vp);
 579
 580 typedef JSBool
 581 (* JS_DLL_CALLBACK JSEqualityOp)(JSContext *cx, JSObject *obj, jsval v,
 582                                  JSBool *bp);
 583
 584 typedef JSBool
 585 (* JS_DLL_CALLBACK JSConcatenateOp)(JSContext *cx, JSObject *obj, jsval v,
 586                                     jsval *vp);
 587
 588 /* Typedef for native functions called by the JS VM. */
 589
 590 typedef JSBool
 591 (* JS_DLL_CALLBACK JSNative)(JSContext *cx, JSObject *obj, uintN argc,
 592                              jsval *argv, jsval *rval);
 593
 594 /* See jsapi.h, the JS_CALLEE, JS_THIS, etc. macros. */
 595 typedef JSBool
 596 (* JS_DLL_CALLBACK JSFastNative)(JSContext *cx, uintN argc, jsval *vp);
 597
 598 /* Callbacks and their arguments. */
 599
 600 typedef enum JSContextOp {
 601     JSCONTEXT_NEW,
 602     JSCONTEXT_DESTROY
 603 } JSContextOp;
 604
 605 /*
 606  * The possible values for contextOp when the runtime calls the callback are:
 607  *   JSCONTEXT_NEW      JS_NewContext successfully created a new JSContext
 608  *                      instance. The callback can initialize the instance as
 609  *                      required. If the callback returns false, the instance
 610  *                      will be destroyed and JS_NewContext returns null. In
 611  *                      this case the callback is not called again.
 612  *   JSCONTEXT_DESTROY  One of JS_DestroyContext* methods is called. The
 613  *                      callback may perform its own cleanup and must always
 614  *                      return true.
 615  *   Any other value    For future compatibility the callback must do nothing
 616  *                      and return true in this case.
 617  */
 618 typedef JSBool
 619 (* JS_DLL_CALLBACK JSContextCallback)(JSContext *cx, uintN contextOp);
 620
 621 typedef enum JSGCStatus {
 622     JSGC_BEGIN,
 623     JSGC_END,
 624     JSGC_MARK_END,
 625     JSGC_FINALIZE_END
 626 } JSGCStatus;
 627
 628 typedef JSBool
 629 (* JS_DLL_CALLBACK JSGCCallback)(JSContext *cx, JSGCStatus status);
 630
 631 typedef void
 632 (* JS_DLL_CALLBACK JSGCThingCallback)(void *thing, uint8 flags, void *closure);
 633
 634 /*
 635  * Generic trace operation that calls JS_CallTracer on each traceable thing
 636  * stored in data.
 637  */
 638 typedef void
 639 (* JS_DLL_CALLBACK JSTraceDataOp)(JSTracer *trc, void *data);
 640
 641 typedef JSBool
 642 (* JS_DLL_CALLBACK JSBranchCallback)(JSContext *cx, JSScript *script);
 643
 644 typedef void
 645 (* JS_DLL_CALLBACK JSErrorReporter)(JSContext *cx, const char *message,
 646                                     JSErrorReport *report);
 647
 648 /*
 649  * Possible exception types. These types are part of a JSErrorFormatString
 650  * structure. They define which error to throw in case of a runtime error.
 651  * JSEXN_NONE marks an unthrowable error.
 652  */
 653 typedef enum JSExnType {
 654     JSEXN_NONE = -1,
 655       JSEXN_ERR,
 656         JSEXN_INTERNALERR,
 657         JSEXN_EVALERR,
 658         JSEXN_RANGEERR,
 659         JSEXN_REFERENCEERR,
 660         JSEXN_SYNTAXERR,
 661         JSEXN_TYPEERR,
 662         JSEXN_URIERR,
 663         JSEXN_LIMIT
 664 } JSExnType;
 665
 666 typedef struct JSErrorFormatString {
 667     /* The error format string (UTF-8 if JS_C_STRINGS_ARE_UTF8 is defined). */
 668     const char *format;
 669
 670     /* The number of arguments to expand in the formatted error message. */
 671     uint16 argCount;
 672
 673     /* One of the JSExnType constants above. */
 674     int16 exnType;
 675 } JSErrorFormatString;
 676
 677 typedef const JSErrorFormatString *
 678 (* JS_DLL_CALLBACK JSErrorCallback)(void *userRef, const char *locale,
 679                                     const uintN errorNumber);
 680
 681 #ifdef va_start
 682 #define JS_ARGUMENT_FORMATTER_DEFINED 1
 683
 684 typedef JSBool
 685 (* JS_DLL_CALLBACK JSArgumentFormatter)(JSContext *cx, const char *format,
 686                                         JSBool fromJS, jsval **vpp,
 687                                         va_list *app);
 688 #endif
 689
 690 typedef JSBool
 691 (* JS_DLL_CALLBACK JSLocaleToUpperCase)(JSContext *cx, JSString *src,
 692                                         jsval *rval);
 693
 694 typedef JSBool
 695 (* JS_DLL_CALLBACK JSLocaleToLowerCase)(JSContext *cx, JSString *src,
 696                                         jsval *rval);
 697
 698 typedef JSBool
 699 (* JS_DLL_CALLBACK JSLocaleCompare)(JSContext *cx,
 700                                     JSString *src1, JSString *src2,
 701                                     jsval *rval);
 702
 703 typedef JSBool
 704 (* JS_DLL_CALLBACK JSLocaleToUnicode)(JSContext *cx, char *src, jsval *rval);
 705
 706 /*
 707  * Security protocol types.
 708  */
 709 typedef struct JSPrincipals JSPrincipals;
 710
 711 /*
 712  * XDR-encode or -decode a principals instance, based on whether xdr->mode is
 713  * JSXDR_ENCODE, in which case *principalsp should be encoded; or JSXDR_DECODE,
 714  * in which case implementations must return a held (via JSPRINCIPALS_HOLD),
 715  * non-null *principalsp out parameter.  Return true on success, false on any
 716  * error, which the implementation must have reported.
 717  */
 718 typedef JSBool
 719 (* JS_DLL_CALLBACK JSPrincipalsTranscoder)(JSXDRState *xdr,
 720                                            JSPrincipals **principalsp);
 721
 722 /*
 723  * Return a weak reference to the principals associated with obj, possibly via
 724  * the immutable parent chain leading from obj to a top-level container (e.g.,
 725  * a window object in the DOM level 0).  If there are no principals associated
 726  * with obj, return null.  Therefore null does not mean an error was reported;
 727  * in no event should an error be reported or an exception be thrown by this
 728  * callback's implementation.
 729  */
 730 typedef JSPrincipals *
 731 (* JS_DLL_CALLBACK JSObjectPrincipalsFinder)(JSContext *cx, JSObject *obj);
 732
 733 JS_END_EXTERN_C
 734
 735 #endif /* jspubtd_h___ */