src/dom/js/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_DEFAULT = 0,
  73     JSVERSION_UNKNOWN = -1
  74 } JSVersion;
  75
  76 #define JSVERSION_IS_ECMA(version) \
  77     ((version) == JSVERSION_DEFAULT || (version) >= JSVERSION_1_3)
  78
  79 /* Result of typeof operator enumeration. */
  80 typedef enum JSType {
  81     JSTYPE_VOID,                /* undefined */
  82     JSTYPE_OBJECT,              /* object */
  83     JSTYPE_FUNCTION,            /* function */
  84     JSTYPE_STRING,              /* string */
  85     JSTYPE_NUMBER,              /* number */
  86     JSTYPE_BOOLEAN,             /* boolean */
  87     JSTYPE_LIMIT
  88 } JSType;
  89
  90 /* JSObjectOps.checkAccess mode enumeration. */
  91 typedef enum JSAccessMode {
  92     JSACC_PROTO  = 0,           /* XXXbe redundant w.r.t. id */
  93     JSACC_PARENT = 1,           /* XXXbe redundant w.r.t. id */
  94     JSACC_IMPORT = 2,           /* import foo.bar */
  95     JSACC_WATCH  = 3,           /* a watchpoint on object foo for id 'bar' */
  96     JSACC_READ   = 4,           /* a "get" of foo.bar */
  97     JSACC_WRITE  = 8,           /* a "set" of foo.bar = baz */
  98     JSACC_LIMIT
  99 } JSAccessMode;
 100
 101 #define JSACC_TYPEMASK          (JSACC_WRITE - 1)
 102
 103 /*
 104  * This enum type is used to control the behavior of a JSObject property
 105  * iterator function that has type JSNewEnumerate.
 106  */
 107 typedef enum JSIterateOp {
 108     JSENUMERATE_INIT,       /* Create new iterator state */
 109     JSENUMERATE_NEXT,       /* Iterate once */
 110     JSENUMERATE_DESTROY     /* Destroy iterator state */
 111 } JSIterateOp;
 112
 113 /* Struct typedefs. */
 114 typedef struct JSClass           JSClass;
 115 typedef struct JSConstDoubleSpec JSConstDoubleSpec;
 116 typedef struct JSContext         JSContext;
 117 typedef struct JSErrorReport     JSErrorReport;
 118 typedef struct JSFunction        JSFunction;
 119 typedef struct JSFunctionSpec    JSFunctionSpec;
 120 typedef struct JSIdArray         JSIdArray;
 121 typedef struct JSProperty        JSProperty;
 122 typedef struct JSPropertySpec    JSPropertySpec;
 123 typedef struct JSObject          JSObject;
 124 typedef struct JSObjectMap       JSObjectMap;
 125 typedef struct JSObjectOps       JSObjectOps;
 126 typedef struct JSRuntime         JSRuntime;
 127 typedef struct JSRuntime         JSTaskState;   /* XXX deprecated name */
 128 typedef struct JSScript          JSScript;
 129 typedef struct JSString          JSString;
 130 typedef struct JSXDRState        JSXDRState;
 131 typedef struct JSExceptionState  JSExceptionState;
 132 typedef struct JSLocaleCallbacks JSLocaleCallbacks;
 133
 134 /* JSClass (and JSObjectOps where appropriate) function pointer typedefs. */
 135
 136 /*
 137  * Add, delete, get or set a property named by id in obj.  Note the jsval id
 138  * type -- id may be a string (Unicode property identifier) or an int (element
 139  * index).  The *vp out parameter, on success, is the new property value after
 140  * an add, get, or set.  After a successful delete, *vp is JSVAL_FALSE iff
 141  * obj[id] can't be deleted (because it's permanent).
 142  */
 143 typedef JSBool
 144 (* JS_DLL_CALLBACK JSPropertyOp)(JSContext *cx, JSObject *obj, jsval id,
 145                                  jsval *vp);
 146
 147 /*
 148  * This function type is used for callbacks that enumerate the properties of
 149  * a JSObject.  The behavior depends on the value of enum_op:
 150  *
 151  *  JSENUMERATE_INIT
 152  *    A new, opaque iterator state should be allocated and stored in *statep.
 153  *    (You can use PRIVATE_TO_JSVAL() to tag the pointer to be stored).
 154  *
 155  *    The number of properties that will be enumerated should be returned as
 156  *    an integer jsval in *idp, if idp is non-null, and provided the number of
 157  *    enumerable properties is known.  If idp is non-null and the number of
 158  *    enumerable properties can't be computed in advance, *idp should be set
 159  *    to JSVAL_ZERO.
 160  *
 161  *  JSENUMERATE_NEXT
 162  *    A previously allocated opaque iterator state is passed in via statep.
 163  *    Return the next jsid in the iteration using *idp.  The opaque iterator
 164  *    state pointed at by statep is destroyed and *statep is set to JSVAL_NULL
 165  *    if there are no properties left to enumerate.
 166  *
 167  *  JSENUMERATE_DESTROY
 168  *    Destroy the opaque iterator state previously allocated in *statep by a
 169  *    call to this function when enum_op was JSENUMERATE_INIT.
 170  *
 171  * The return value is used to indicate success, with a value of JS_FALSE
 172  * indicating failure.
 173  */
 174 typedef JSBool
 175 (* JS_DLL_CALLBACK JSNewEnumerateOp)(JSContext *cx, JSObject *obj,
 176                                      JSIterateOp enum_op,
 177                                      jsval *statep, jsid *idp);
 178
 179 /*
 180  * The old-style JSClass.enumerate op should define all lazy properties not
 181  * yet reflected in obj.
 182  */
 183 typedef JSBool
 184 (* JS_DLL_CALLBACK JSEnumerateOp)(JSContext *cx, JSObject *obj);
 185
 186 /*
 187  * Resolve a lazy property named by id in obj by defining it directly in obj.
 188  * Lazy properties are those reflected from some peer native property space
 189  * (e.g., the DOM attributes for a given node reflected as obj) on demand.
 190  *
 191  * JS looks for a property in an object, and if not found, tries to resolve
 192  * the given id.  If resolve succeeds, the engine looks again in case resolve
 193  * defined obj[id].  If no such property exists directly in obj, the process
 194  * is repeated with obj's prototype, etc.
 195  *
 196  * NB: JSNewResolveOp provides a cheaper way to resolve lazy properties.
 197  */
 198 typedef JSBool
 199 (* JS_DLL_CALLBACK JSResolveOp)(JSContext *cx, JSObject *obj, jsval id);
 200
 201 /*
 202  * Like JSResolveOp, but flags provide contextual information as follows:
 203  *
 204  *  JSRESOLVE_QUALIFIED   a qualified property id: obj.id or obj[id], not id
 205  *  JSRESOLVE_ASSIGNING   obj[id] is on the left-hand side of an assignment
 206  *
 207  * The *objp out parameter, on success, should be null to indicate that id
 208  * was not resolved; and non-null, referring to obj or one of its prototypes,
 209  * if id was resolved.
 210  *
 211  * This hook instead of JSResolveOp is called via the JSClass.resolve member
 212  * if JSCLASS_NEW_RESOLVE is set in JSClass.flags.
 213  *
 214  * Setting JSCLASS_NEW_RESOLVE and JSCLASS_NEW_RESOLVE_GETS_START further
 215  * extends this hook by passing in the starting object on the prototype chain
 216  * via *objp.  Thus a resolve hook implementation may define the property id
 217  * being resolved in the object in which the id was first sought, rather than
 218  * in a prototype object whose class led to the resolve hook being called.
 219  *
 220  * When using JSCLASS_NEW_RESOLVE_GETS_START, the resolve hook must therefore
 221  * null *objp to signify "not resolved".  With only JSCLASS_NEW_RESOLVE and no
 222  * JSCLASS_NEW_RESOLVE_GETS_START, the hook can assume *objp is null on entry.
 223  * This is not good practice, but enough existing hook implementations count
 224  * on it that we can't break compatibility by passing the starting object in
 225  * *objp without a new JSClass flag.
 226  */
 227 typedef JSBool
 228 (* JS_DLL_CALLBACK JSNewResolveOp)(JSContext *cx, JSObject *obj, jsval id,
 229                                    uintN flags, JSObject **objp);
 230
 231 /*
 232  * Convert obj to the given type, returning true with the resulting value in
 233  * *vp on success, and returning false on error or exception.
 234  */
 235 typedef JSBool
 236 (* JS_DLL_CALLBACK JSConvertOp)(JSContext *cx, JSObject *obj, JSType type,
 237                                 jsval *vp);
 238
 239 /*
 240  * Finalize obj, which the garbage collector has determined to be unreachable
 241  * from other live objects or from GC roots.  Obviously, finalizers must never
 242  * store a reference to obj.
 243  */
 244 typedef void
 245 (* JS_DLL_CALLBACK JSFinalizeOp)(JSContext *cx, JSObject *obj);
 246
 247 /*
 248  * Used by JS_AddExternalStringFinalizer and JS_RemoveExternalStringFinalizer
 249  * to extend and reduce the set of string types finalized by the GC.
 250  */
 251 typedef void
 252 (* JS_DLL_CALLBACK JSStringFinalizeOp)(JSContext *cx, JSString *str);
 253
 254 /*
 255  * The signature for JSClass.getObjectOps, used by JS_NewObject's internals
 256  * to discover the set of high-level object operations to use for new objects
 257  * of the given class.  All native objects have a JSClass, which is stored as
 258  * a private (int-tagged) pointer in obj->slots[JSSLOT_CLASS].  In contrast,
 259  * all native and host objects have a JSObjectMap at obj->map, which may be
 260  * shared among a number of objects, and which contains the JSObjectOps *ops
 261  * pointer used to dispatch object operations from API calls.
 262  *
 263  * Thus JSClass (which pre-dates JSObjectOps in the API) provides a low-level
 264  * interface to class-specific code and data, while JSObjectOps allows for a
 265  * higher level of operation, which does not use the object's class except to
 266  * find the class's JSObjectOps struct, by calling clasp->getObjectOps.
 267  *
 268  * If this seems backwards, that's because it is!  API compatibility requires
 269  * a JSClass *clasp parameter to JS_NewObject, etc.  Most host objects do not
 270  * need to implement the larger JSObjectOps, and can share the common JSScope
 271  * code and data used by the native (js_ObjectOps, see jsobj.c) ops.
 272  */
 273 typedef JSObjectOps *
 274 (* JS_DLL_CALLBACK JSGetObjectOps)(JSContext *cx, JSClass *clasp);
 275
 276 /*
 277  * JSClass.checkAccess type: check whether obj[id] may be accessed per mode,
 278  * returning false on error/exception, true on success with obj[id]'s last-got
 279  * value in *vp, and its attributes in *attrsp.  As for JSPropertyOp above, id
 280  * is either a string or an int jsval.
 281  *
 282  * See JSCheckAccessIdOp, below, for the JSObjectOps counterpart, which takes
 283  * a jsid (a tagged int or aligned, unique identifier pointer) rather than a
 284  * jsval.  The native js_ObjectOps.checkAccess simply forwards to the object's
 285  * clasp->checkAccess, so that both JSClass and JSObjectOps implementors may
 286  * specialize access checks.
 287  */
 288 typedef JSBool
 289 (* JS_DLL_CALLBACK JSCheckAccessOp)(JSContext *cx, JSObject *obj, jsval id,
 290                                     JSAccessMode mode, jsval *vp);
 291
 292 /*
 293  * Encode or decode an object, given an XDR state record representing external
 294  * data.  See jsxdrapi.h.
 295  */
 296 typedef JSBool
 297 (* JS_DLL_CALLBACK JSXDRObjectOp)(JSXDRState *xdr, JSObject **objp);
 298
 299 /*
 300  * Check whether v is an instance of obj.  Return false on error or exception,
 301  * true on success with JS_TRUE in *bp if v is an instance of obj, JS_FALSE in
 302  * *bp otherwise.
 303  */
 304 typedef JSBool
 305 (* JS_DLL_CALLBACK JSHasInstanceOp)(JSContext *cx, JSObject *obj, jsval v,
 306                                     JSBool *bp);
 307
 308 /*
 309  * Function type for JSClass.mark and JSObjectOps.mark, called from the GC to
 310  * scan live GC-things reachable from obj's private data structure.  For each
 311  * such thing, a mark implementation must call
 312  *
 313  *    JS_MarkGCThing(cx, thing, name, arg);
 314  *
 315  * The trailing name and arg parameters are used for GC_MARK_DEBUG-mode heap
 316  * dumping and ref-path tracing.  The mark function should pass a (typically
 317  * literal) string naming the private data member for name, and it must pass
 318  * the opaque arg parameter through from its caller.
 319  *
 320  * For the JSObjectOps.mark hook, the return value is the number of slots at
 321  * obj->slots to scan.  For JSClass.mark, the return value is ignored.
 322  *
 323  * NB: JSMarkOp implementations cannot allocate new GC-things (JS_NewObject
 324  * called from a mark function will fail silently, e.g.).
 325  */
 326 typedef uint32
 327 (* JS_DLL_CALLBACK JSMarkOp)(JSContext *cx, JSObject *obj, void *arg);
 328
 329 /*
 330  * The optional JSClass.reserveSlots hook allows a class to make computed
 331  * per-instance object slots reservations, in addition to or instead of using
 332  * JSCLASS_HAS_RESERVED_SLOTS(n) in the JSClass.flags initializer to reserve
 333  * a constant-per-class number of slots.  Implementations of this hook should
 334  * return the number of slots to reserve, not including any reserved by using
 335  * JSCLASS_HAS_RESERVED_SLOTS(n) in JSClass.flags.
 336  *
 337  * NB: called with obj locked by the JSObjectOps-specific mutual exclusion
 338  * mechanism appropriate for obj, so don't nest other operations that might
 339  * also lock obj.
 340  */
 341 typedef uint32
 342 (* JS_DLL_CALLBACK JSReserveSlotsOp)(JSContext *cx, JSObject *obj);
 343
 344 /* JSObjectOps function pointer typedefs. */
 345
 346 /*
 347  * Create a new subclass of JSObjectMap (see jsobj.h), with the nrefs and ops
 348  * members initialized from the same-named parameters, and with the nslots and
 349  * freeslot members initialized according to ops and clasp.  Return null on
 350  * error, non-null on success.
 351  *
 352  * JSObjectMaps are reference-counted by generic code in the engine.  Usually,
 353  * the nrefs parameter to JSObjectOps.newObjectMap will be 1, to count the ref
 354  * returned to the caller on success.  After a successful construction, some
 355  * number of js_HoldObjectMap and js_DropObjectMap calls ensue.  When nrefs
 356  * reaches 0 due to a js_DropObjectMap call, JSObjectOps.destroyObjectMap will
 357  * be called to dispose of the map.
 358  */
 359 typedef JSObjectMap *
 360 (* JS_DLL_CALLBACK JSNewObjectMapOp)(JSContext *cx, jsrefcount nrefs,
 361                                      JSObjectOps *ops, JSClass *clasp,
 362                                      JSObject *obj);
 363
 364 /*
 365  * Generic type for an infallible JSObjectMap operation, used currently by
 366  * JSObjectOps.destroyObjectMap.
 367  */
 368 typedef void
 369 (* JS_DLL_CALLBACK JSObjectMapOp)(JSContext *cx, JSObjectMap *map);
 370
 371 /*
 372  * Look for id in obj and its prototype chain, returning false on error or
 373  * exception, true on success.  On success, return null in *propp if id was
 374  * not found.  If id was found, return the first object searching from obj
 375  * along its prototype chain in which id names a direct property in *objp, and
 376  * return a non-null, opaque property pointer in *propp.
 377  *
 378  * If JSLookupPropOp succeeds and returns with *propp non-null, that pointer
 379  * may be passed as the prop parameter to a JSAttributesOp, as a short-cut
 380  * that bypasses id re-lookup.  In any case, a non-null *propp result after a
 381  * successful lookup must be dropped via JSObjectOps.dropProperty.
 382  *
 383  * NB: successful return with non-null *propp means the implementation may
 384  * have locked *objp and added a reference count associated with *propp, so
 385  * callers should not risk deadlock by nesting or interleaving other lookups
 386  * or any obj-bearing ops before dropping *propp.
 387  */
 388 typedef JSBool
 389 (* JS_DLL_CALLBACK JSLookupPropOp)(JSContext *cx, JSObject *obj, jsid id,
 390                                    JSObject **objp, JSProperty **propp
 391 #if defined JS_THREADSAFE && defined DEBUG
 392                                  , const char *file, uintN line
 393 #endif
 394                                   );
 395
 396 /*
 397  * Define obj[id], a direct property of obj named id, having the given initial
 398  * value, with the specified getter, setter, and attributes.  If the propp out
 399  * param is non-null, *propp on successful return contains an opaque property
 400  * pointer usable as a speedup hint with JSAttributesOp.  But note that propp
 401  * may be null, indicating that the caller is not interested in recovering an
 402  * opaque pointer to the newly-defined property.
 403  *
 404  * If propp is non-null and JSDefinePropOp succeeds, its caller must be sure
 405  * to drop *propp using JSObjectOps.dropProperty in short order, just as with
 406  * JSLookupPropOp.
 407  */
 408 typedef JSBool
 409 (* JS_DLL_CALLBACK JSDefinePropOp)(JSContext *cx, JSObject *obj,
 410                                    jsid id, jsval value,
 411                                    JSPropertyOp getter, JSPropertyOp setter,
 412                                    uintN attrs, JSProperty **propp);
 413
 414 /*
 415  * Get, set, or delete obj[id], returning false on error or exception, true
 416  * on success.  If getting or setting, the new value is returned in *vp on
 417  * success.  If deleting without error, *vp will be JSVAL_FALSE if obj[id] is
 418  * permanent, and JSVAL_TRUE if id named a direct property of obj that was in
 419  * fact deleted, or if id names no direct property of obj (id could name a
 420  * prototype property, or no property in obj or its prototype chain).
 421  */
 422 typedef JSBool
 423 (* JS_DLL_CALLBACK JSPropertyIdOp)(JSContext *cx, JSObject *obj, jsid id,
 424                                    jsval *vp);
 425
 426 /*
 427  * Get or set attributes of the property obj[id].  Return false on error or
 428  * exception, true with current attributes in *attrsp.  If prop is non-null,
 429  * it must come from the *propp out parameter of a prior JSDefinePropOp or
 430  * JSLookupPropOp call.
 431  */
 432 typedef JSBool
 433 (* JS_DLL_CALLBACK JSAttributesOp)(JSContext *cx, JSObject *obj, jsid id,
 434                                    JSProperty *prop, uintN *attrsp);
 435
 436 /*
 437  * JSObjectOps.checkAccess type: check whether obj[id] may be accessed per
 438  * mode, returning false on error/exception, true on success with obj[id]'s
 439  * last-got value in *vp, and its attributes in *attrsp.
 440  */
 441 typedef JSBool
 442 (* JS_DLL_CALLBACK JSCheckAccessIdOp)(JSContext *cx, JSObject *obj, jsid id,
 443                                       JSAccessMode mode, jsval *vp,
 444                                       uintN *attrsp);
 445
 446 /*
 447  * A generic type for functions mapping an object to another object, or null
 448  * if an error or exception was thrown on cx.  Used by JSObjectOps.thisObject
 449  * at present.
 450  */
 451 typedef JSObject *
 452 (* JS_DLL_CALLBACK JSObjectOp)(JSContext *cx, JSObject *obj);
 453
 454 /*
 455  * A generic type for functions taking a context, object, and property, with
 456  * no return value.  Used by JSObjectOps.dropProperty currently (see above,
 457  * JSDefinePropOp and JSLookupPropOp, for the object-locking protocol in which
 458  * dropProperty participates).
 459  */
 460 typedef void
 461 (* JS_DLL_CALLBACK JSPropertyRefOp)(JSContext *cx, JSObject *obj,
 462                                     JSProperty *prop);
 463
 464 /*
 465  * Function type for JSObjectOps.setProto and JSObjectOps.setParent.  These
 466  * hooks must check for cycles without deadlocking, and otherwise take special
 467  * steps.  See jsobj.c, js_SetProtoOrParent, for an example.
 468  */
 469 typedef JSBool
 470 (* JS_DLL_CALLBACK JSSetObjectSlotOp)(JSContext *cx, JSObject *obj,
 471                                       uint32 slot, JSObject *pobj);
 472
 473 /*
 474  * Get and set a required slot, one that should already have been allocated.
 475  * These operations are infallible, so required slots must be pre-allocated,
 476  * or implementations must suppress out-of-memory errors.  The native ops
 477  * (js_ObjectOps, see jsobj.c) access slots reserved by including a call to
 478  * the JSCLASS_HAS_RESERVED_SLOTS(n) macro in the JSClass.flags initializer.
 479  *
 480  * NB: the slot parameter is a zero-based index into obj->slots[], unlike the
 481  * index parameter to the JS_GetReservedSlot and JS_SetReservedSlot API entry
 482  * points, which is a zero-based index into the JSCLASS_RESERVED_SLOTS(clasp)
 483  * reserved slots that come after the initial well-known slots: proto, parent,
 484  * class, and optionally, the private data slot.
 485  */
 486 typedef jsval
 487 (* JS_DLL_CALLBACK JSGetRequiredSlotOp)(JSContext *cx, JSObject *obj,
 488                                         uint32 slot);
 489
 490 typedef JSBool
 491 (* JS_DLL_CALLBACK JSSetRequiredSlotOp)(JSContext *cx, JSObject *obj,
 492                                         uint32 slot, jsval v);
 493
 494 /* Typedef for native functions called by the JS VM. */
 495
 496 typedef JSBool
 497 (* JS_DLL_CALLBACK JSNative)(JSContext *cx, JSObject *obj, uintN argc,
 498                              jsval *argv, jsval *rval);
 499
 500 /* Callbacks and their arguments. */
 501
 502 typedef enum JSGCStatus {
 503     JSGC_BEGIN,
 504     JSGC_END,
 505     JSGC_MARK_END,
 506     JSGC_FINALIZE_END
 507 } JSGCStatus;
 508
 509 typedef JSBool
 510 (* JS_DLL_CALLBACK JSGCCallback)(JSContext *cx, JSGCStatus status);
 511
 512 typedef JSBool
 513 (* JS_DLL_CALLBACK JSBranchCallback)(JSContext *cx, JSScript *script);
 514
 515 typedef void
 516 (* JS_DLL_CALLBACK JSErrorReporter)(JSContext *cx, const char *message,
 517                                     JSErrorReport *report);
 518
 519 typedef struct JSErrorFormatString {
 520     const char *format;
 521     uintN argCount;
 522 } JSErrorFormatString;
 523
 524 typedef const JSErrorFormatString *
 525 (* JS_DLL_CALLBACK JSErrorCallback)(void *userRef, const char *locale,
 526                                     const uintN errorNumber);
 527
 528 #ifdef va_start
 529 #define JS_ARGUMENT_FORMATTER_DEFINED 1
 530
 531 typedef JSBool
 532 (* JS_DLL_CALLBACK JSArgumentFormatter)(JSContext *cx, const char *format,
 533                                         JSBool fromJS, jsval **vpp,
 534                                         va_list *app);
 535 #endif
 536
 537 typedef JSBool
 538 (* JS_DLL_CALLBACK JSLocaleToUpperCase)(JSContext *cx, JSString *src,
 539                                         jsval *rval);
 540
 541 typedef JSBool
 542 (* JS_DLL_CALLBACK JSLocaleToLowerCase)(JSContext *cx, JSString *src,
 543                                         jsval *rval);
 544
 545 typedef JSBool
 546 (* JS_DLL_CALLBACK JSLocaleCompare)(JSContext *cx,
 547                                     JSString *src1, JSString *src2,
 548                                     jsval *rval);
 549
 550 typedef JSBool
 551 (* JS_DLL_CALLBACK JSLocaleToUnicode)(JSContext *cx, char *src, jsval *rval);
 552
 553 /*
 554  * Security protocol types.
 555  */
 556 typedef struct JSPrincipals JSPrincipals;
 557
 558 /*
 559  * XDR-encode or -decode a principals instance, based on whether xdr->mode is
 560  * JSXDR_ENCODE, in which case *principalsp should be encoded; or JSXDR_DECODE,
 561  * in which case implementations must return a held (via JSPRINCIPALS_HOLD),
 562  * non-null *principalsp out parameter.  Return true on success, false on any
 563  * error, which the implementation must have reported.
 564  */
 565 typedef JSBool
 566 (* JS_DLL_CALLBACK JSPrincipalsTranscoder)(JSXDRState *xdr,
 567                                            JSPrincipals **principalsp);
 568
 569 /*
 570  * Return a weak reference to the principals associated with obj, possibly via
 571  * the immutable parent chain leading from obj to a top-level container (e.g.,
 572  * a window object in the DOM level 0).  If there are no principals associated
 573  * with obj, return null.  Therefore null does not mean an error was reported;
 574  * in no event should an error be reported or an exception be thrown by this
 575  * callback's implementation.
 576  */
 577 typedef JSPrincipals *
 578 (* JS_DLL_CALLBACK JSObjectPrincipalsFinder)(JSContext *cx, JSObject *obj);
 579
 580 JS_END_EXTERN_C
 581
 582 #endif /* jspubtd_h___ */