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 #include "jsval.h"
  48
  49 JS_BEGIN_EXTERN_C
  50
  51 /* Scalar typedefs. */
  52 typedef JSInt32   jsint;
  53 typedef JSUint32  jsuint;
  54 typedef float64   jsdouble;
  55 typedef JSInt32   jsrefcount;   /* PRInt32 if JS_THREADSAFE, see jslock.h */
  56
  57 #ifdef WIN32
  58 typedef wchar_t   jschar;
  59 #else
  60 typedef JSUint16  jschar;
  61 #endif
  62
  63
  64 /*
  65  * Run-time version enumeration.  See jsversion.h for compile-time counterparts
  66  * to these values that may be selected by the JS_VERSION macro, and tested by
  67  * #if expressions.
  68  */
  69 typedef enum JSVersion {
  70     JSVERSION_1_0     = 100,
  71     JSVERSION_1_1     = 110,
  72     JSVERSION_1_2     = 120,
  73     JSVERSION_1_3     = 130,
  74     JSVERSION_1_4     = 140,
  75     JSVERSION_ECMA_3  = 148,
  76     JSVERSION_1_5     = 150,
  77     JSVERSION_1_6     = 160,
  78     JSVERSION_1_7     = 170,
  79     JSVERSION_1_8     = 180,
  80     JSVERSION_ECMA_5  = 185,
  81     JSVERSION_DEFAULT = 0,
  82     JSVERSION_UNKNOWN = -1,
  83     JSVERSION_LATEST  = JSVERSION_ECMA_5
  84 } JSVersion;
  85
  86 #define JSVERSION_IS_ECMA(version) \
  87     ((version) == JSVERSION_DEFAULT || (version) >= JSVERSION_1_3)
  88
  89 /* Result of typeof operator enumeration. */
  90 typedef enum JSType {
  91     JSTYPE_VOID,                /* undefined */
  92     JSTYPE_OBJECT,              /* object */
  93     JSTYPE_FUNCTION,            /* function */
  94     JSTYPE_STRING,              /* string */
  95     JSTYPE_NUMBER,              /* number */
  96     JSTYPE_BOOLEAN,             /* boolean */
  97     JSTYPE_NULL,                /* null */
  98     JSTYPE_XML,                 /* xml object */
  99     JSTYPE_LIMIT
 100 } JSType;
 101
 102 /* Dense index into cached prototypes and class atoms for standard objects. */
 103 typedef enum JSProtoKey {
 104 #define JS_PROTO(name,code,init) JSProto_##name = code,
 105 #include "jsproto.tbl"
 106 #undef JS_PROTO
 107     JSProto_LIMIT
 108 } JSProtoKey;
 109
 110 /* js_CheckAccess mode enumeration. */
 111 typedef enum JSAccessMode {
 112     JSACC_PROTO  = 0,           /* XXXbe redundant w.r.t. id */
 113     JSACC_PARENT = 1,           /* XXXbe redundant w.r.t. id */
 114
 115                                 /*
 116                                  * enum value #2 formerly called JSACC_IMPORT,
 117                                  * gap preserved for ABI compatibility.
 118                                  */
 119
 120     JSACC_WATCH  = 3,           /* a watchpoint on object foo for id 'bar' */
 121     JSACC_READ   = 4,           /* a "get" of foo.bar */
 122     JSACC_WRITE  = 8,           /* a "set" of foo.bar = baz */
 123     JSACC_LIMIT
 124 } JSAccessMode;
 125
 126 #define JSACC_TYPEMASK          (JSACC_WRITE - 1)
 127
 128 /*
 129  * This enum type is used to control the behavior of a JSObject property
 130  * iterator function that has type JSNewEnumerate.
 131  */
 132 typedef enum JSIterateOp {
 133     /* Create new iterator state over enumerable properties. */
 134     JSENUMERATE_INIT,
 135
 136     /* Create new iterator state over all properties. */
 137     JSENUMERATE_INIT_ALL,
 138
 139     /* Iterate once. */
 140     JSENUMERATE_NEXT,
 141
 142     /* Destroy iterator state. */
 143     JSENUMERATE_DESTROY
 144 } JSIterateOp;
 145
 146 /* Struct typedefs. */
 147 typedef struct JSClass           JSClass;
 148 typedef struct JSConstDoubleSpec JSConstDoubleSpec;
 149 typedef struct JSContext         JSContext;
 150 typedef struct JSErrorReport     JSErrorReport;
 151 typedef struct JSFunction        JSFunction;
 152 typedef struct JSFunctionSpec    JSFunctionSpec;
 153 typedef struct JSTracer          JSTracer;
 154 typedef struct JSIdArray         JSIdArray;
 155 typedef struct JSPropertyDescriptor JSPropertyDescriptor;
 156 typedef struct JSPropertySpec    JSPropertySpec;
 157 typedef struct JSObjectMap       JSObjectMap;
 158 typedef struct JSRuntime         JSRuntime;
 159 typedef struct JSStackFrame      JSStackFrame;
 160 typedef struct JSXDRState        JSXDRState;
 161 typedef struct JSExceptionState  JSExceptionState;
 162 typedef struct JSLocaleCallbacks JSLocaleCallbacks;
 163 typedef struct JSSecurityCallbacks JSSecurityCallbacks;
 164 typedef struct JSONParser        JSONParser;
 165 typedef struct JSCompartment     JSCompartment;
 166 typedef struct JSCrossCompartmentCall JSCrossCompartmentCall;
 167 typedef struct JSStructuredCloneWriter JSStructuredCloneWriter;
 168 typedef struct JSStructuredCloneReader JSStructuredCloneReader;
 169 typedef struct JSStructuredCloneCallbacks JSStructuredCloneCallbacks;
 170
 171 #ifdef __cplusplus
 172 typedef class JSWrapper          JSWrapper;
 173 typedef class JSCrossCompartmentWrapper JSCrossCompartmentWrapper;
 174 #endif
 175
 176 /* JSClass (and js::ObjectOps where appropriate) function pointer typedefs. */
 177
 178 /*
 179  * Add, delete, or get a property named by id in obj.  Note the jsid id
 180  * type -- id may be a string (Unicode property identifier) or an int (element
 181  * index).  The *vp out parameter, on success, is the new property value after
 182  * an add or get.  After a successful delete, *vp is JSVAL_FALSE iff
 183  * obj[id] can't be deleted (because it's permanent).
 184  */
 185 typedef JSBool
 186 (* JSPropertyOp)(JSContext *cx, JSObject *obj, jsid id, jsval *vp);
 187
 188 /*
 189  * Set a property named by id in obj, treating the assignment as strict
 190  * mode code if strict is true. Note the jsid id type -- id may be a string
 191  * (Unicode property identifier) or an int (element index). The *vp out
 192  * parameter, on success, is the new property value after the
 193  * set.
 194  */
 195 typedef JSBool
 196 (* JSStrictPropertyOp)(JSContext *cx, JSObject *obj, jsid id, JSBool strict, jsval *vp);
 197
 198 /*
 199  * This function type is used for callbacks that enumerate the properties of
 200  * a JSObject.  The behavior depends on the value of enum_op:
 201  *
 202  *  JSENUMERATE_INIT
 203  *    A new, opaque iterator state should be allocated and stored in *statep.
 204  *    (You can use PRIVATE_TO_JSVAL() to tag the pointer to be stored).
 205  *
 206  *    The number of properties that will be enumerated should be returned as
 207  *    an integer jsval in *idp, if idp is non-null, and provided the number of
 208  *    enumerable properties is known.  If idp is non-null and the number of
 209  *    enumerable properties can't be computed in advance, *idp should be set
 210  *    to JSVAL_ZERO.
 211  *
 212  *  JSENUMERATE_INIT_ALL
 213  *    Used identically to JSENUMERATE_INIT, but exposes all properties of the
 214  *    object regardless of enumerability.
 215  *
 216  *  JSENUMERATE_NEXT
 217  *    A previously allocated opaque iterator state is passed in via statep.
 218  *    Return the next jsid in the iteration using *idp.  The opaque iterator
 219  *    state pointed at by statep is destroyed and *statep is set to JSVAL_NULL
 220  *    if there are no properties left to enumerate.
 221  *
 222  *  JSENUMERATE_DESTROY
 223  *    Destroy the opaque iterator state previously allocated in *statep by a
 224  *    call to this function when enum_op was JSENUMERATE_INIT or
 225  *    JSENUMERATE_INIT_ALL.
 226  *
 227  * The return value is used to indicate success, with a value of JS_FALSE
 228  * indicating failure.
 229  */
 230 typedef JSBool
 231 (* JSNewEnumerateOp)(JSContext *cx, JSObject *obj, JSIterateOp enum_op,
 232                      jsval *statep, jsid *idp);
 233
 234 /*
 235  * The old-style JSClass.enumerate op should define all lazy properties not
 236  * yet reflected in obj.
 237  */
 238 typedef JSBool
 239 (* JSEnumerateOp)(JSContext *cx, JSObject *obj);
 240
 241 /*
 242  * Resolve a lazy property named by id in obj by defining it directly in obj.
 243  * Lazy properties are those reflected from some peer native property space
 244  * (e.g., the DOM attributes for a given node reflected as obj) on demand.
 245  *
 246  * JS looks for a property in an object, and if not found, tries to resolve
 247  * the given id.  If resolve succeeds, the engine looks again in case resolve
 248  * defined obj[id].  If no such property exists directly in obj, the process
 249  * is repeated with obj's prototype, etc.
 250  *
 251  * NB: JSNewResolveOp provides a cheaper way to resolve lazy properties.
 252  */
 253 typedef JSBool
 254 (* JSResolveOp)(JSContext *cx, JSObject *obj, jsid id);
 255
 256 /*
 257  * Like JSResolveOp, but flags provide contextual information as follows:
 258  *
 259  *  JSRESOLVE_QUALIFIED   a qualified property id: obj.id or obj[id], not id
 260  *  JSRESOLVE_ASSIGNING   obj[id] is on the left-hand side of an assignment
 261  *  JSRESOLVE_DETECTING   'if (o.p)...' or similar detection opcode sequence
 262  *  JSRESOLVE_DECLARING   var, const, or function prolog declaration opcode
 263  *  JSRESOLVE_CLASSNAME   class name used when constructing
 264  *
 265  * The *objp out parameter, on success, should be null to indicate that id
 266  * was not resolved; and non-null, referring to obj or one of its prototypes,
 267  * if id was resolved.
 268  *
 269  * This hook instead of JSResolveOp is called via the JSClass.resolve member
 270  * if JSCLASS_NEW_RESOLVE is set in JSClass.flags.
 271  *
 272  * Setting JSCLASS_NEW_RESOLVE and JSCLASS_NEW_RESOLVE_GETS_START further
 273  * extends this hook by passing in the starting object on the prototype chain
 274  * via *objp.  Thus a resolve hook implementation may define the property id
 275  * being resolved in the object in which the id was first sought, rather than
 276  * in a prototype object whose class led to the resolve hook being called.
 277  *
 278  * When using JSCLASS_NEW_RESOLVE_GETS_START, the resolve hook must therefore
 279  * null *objp to signify "not resolved".  With only JSCLASS_NEW_RESOLVE and no
 280  * JSCLASS_NEW_RESOLVE_GETS_START, the hook can assume *objp is null on entry.
 281  * This is not good practice, but enough existing hook implementations count
 282  * on it that we can't break compatibility by passing the starting object in
 283  * *objp without a new JSClass flag.
 284  */
 285 typedef JSBool
 286 (* JSNewResolveOp)(JSContext *cx, JSObject *obj, jsid id, uintN flags,
 287                    JSObject **objp);
 288
 289 /*
 290  * Convert obj to the given type, returning true with the resulting value in
 291  * *vp on success, and returning false on error or exception.
 292  */
 293 typedef JSBool
 294 (* JSConvertOp)(JSContext *cx, JSObject *obj, JSType type, jsval *vp);
 295
 296 /*
 297  * Delegate typeof to an object so it can cloak a primitive or another object.
 298  */
 299 typedef JSType
 300 (* JSTypeOfOp)(JSContext *cx, JSObject *obj);
 301
 302 /*
 303  * Finalize obj, which the garbage collector has determined to be unreachable
 304  * from other live objects or from GC roots.  Obviously, finalizers must never
 305  * store a reference to obj.
 306  */
 307 typedef void
 308 (* JSFinalizeOp)(JSContext *cx, JSObject *obj);
 309
 310 /*
 311  * Used by JS_AddExternalStringFinalizer and JS_RemoveExternalStringFinalizer
 312  * to extend and reduce the set of string types finalized by the GC.
 313  */
 314 typedef void
 315 (* JSStringFinalizeOp)(JSContext *cx, JSString *str);
 316
 317 /*
 318  * JSClass.checkAccess type: check whether obj[id] may be accessed per mode,
 319  * returning false on error/exception, true on success with obj[id]'s last-got
 320  * value in *vp, and its attributes in *attrsp.  As for JSPropertyOp above, id
 321  * is either a string or an int jsval.
 322  */
 323 typedef JSBool
 324 (* JSCheckAccessOp)(JSContext *cx, JSObject *obj, jsid id, JSAccessMode mode,
 325                     jsval *vp);
 326
 327 /*
 328  * Encode or decode an object, given an XDR state record representing external
 329  * data.  See jsxdrapi.h.
 330  */
 331 typedef JSBool
 332 (* JSXDRObjectOp)(JSXDRState *xdr, JSObject **objp);
 333
 334 /*
 335  * Check whether v is an instance of obj.  Return false on error or exception,
 336  * true on success with JS_TRUE in *bp if v is an instance of obj, JS_FALSE in
 337  * *bp otherwise.
 338  */
 339 typedef JSBool
 340 (* JSHasInstanceOp)(JSContext *cx, JSObject *obj, const jsval *v, JSBool *bp);
 341
 342 /*
 343  * Deprecated function type for JSClass.mark. All new code should define
 344  * JSTraceOp instead to ensure the traversal of traceable things stored in
 345  * the native structures.
 346  */
 347 typedef uint32
 348 (* JSMarkOp)(JSContext *cx, JSObject *obj, void *arg);
 349
 350 /*
 351  * Function type for trace operation of the class called to enumerate all
 352  * traceable things reachable from obj's private data structure. For each such
 353  * thing, a trace implementation must call
 354  *
 355  *    JS_CallTracer(trc, thing, kind);
 356  *
 357  * or one of its convenience macros as described in jsapi.h.
 358  *
 359  * JSTraceOp implementation can assume that no other threads mutates object
 360  * state. It must not change state of the object or corresponding native
 361  * structures. The only exception for this rule is the case when the embedding
 362  * needs a tight integration with GC. In that case the embedding can check if
 363  * the traversal is a part of the marking phase through calling
 364  * JS_IsGCMarkingTracer and apply a special code like emptying caches or
 365  * marking its native structures.
 366  *
 367  * To define the tracer for a JSClass, the implementation must add
 368  * JSCLASS_MARK_IS_TRACE to class flags and use JS_CLASS_TRACE(method)
 369  * macro below to convert JSTraceOp to JSMarkOp when initializing or
 370  * assigning JSClass.mark field.
 371  */
 372 typedef void
 373 (* JSTraceOp)(JSTracer *trc, JSObject *obj);
 374
 375 #if defined __GNUC__ && __GNUC__ >= 4 && !defined __cplusplus
 376 # define JS_CLASS_TRACE(method)                                               \
 377     (__builtin_types_compatible_p(JSTraceOp, __typeof(&(method)))             \
 378      ? (JSMarkOp)(method)                                                     \
 379      : js_WrongTypeForClassTracer)
 380
 381 extern JSMarkOp js_WrongTypeForClassTracer;
 382
 383 #else
 384 # define JS_CLASS_TRACE(method) ((JSMarkOp)(method))
 385 #endif
 386
 387 /*
 388  * Tracer callback, called for each traceable thing directly referenced by a
 389  * particular object or runtime structure. It is the callback responsibility
 390  * to ensure the traversal of the full object graph via calling eventually
 391  * JS_TraceChildren on the passed thing. In this case the callback must be
 392  * prepared to deal with cycles in the traversal graph.
 393  *
 394  * kind argument is one of JSTRACE_OBJECT, JSTRACE_STRING or a tag denoting
 395  * internal implementation-specific traversal kind. In the latter case the only
 396  * operations on thing that the callback can do is to call JS_TraceChildren or
 397  * DEBUG-only JS_PrintTraceThingInfo.
 398  */
 399 typedef void
 400 (* JSTraceCallback)(JSTracer *trc, void *thing, uint32 kind);
 401
 402 /*
 403  * DEBUG only callback that JSTraceOp implementation can provide to return
 404  * a string describing the reference traced with JS_CallTracer.
 405  */
 406 typedef void
 407 (* JSTraceNamePrinter)(JSTracer *trc, char *buf, size_t bufsize);
 408
 409 typedef JSBool
 410 (* JSEqualityOp)(JSContext *cx, JSObject *obj, const jsval *v, JSBool *bp);
 411
 412 /*
 413  * Typedef for native functions called by the JS VM.
 414  *
 415  * See jsapi.h, the JS_CALLEE, JS_THIS, etc. macros.
 416  */
 417
 418 typedef JSBool
 419 (* JSNative)(JSContext *cx, uintN argc, jsval *vp);
 420
 421 /* Callbacks and their arguments. */
 422
 423 typedef enum JSContextOp {
 424     JSCONTEXT_NEW,
 425     JSCONTEXT_DESTROY
 426 } JSContextOp;
 427
 428 /*
 429  * The possible values for contextOp when the runtime calls the callback are:
 430  *   JSCONTEXT_NEW      JS_NewContext successfully created a new JSContext
 431  *                      instance. The callback can initialize the instance as
 432  *                      required. If the callback returns false, the instance
 433  *                      will be destroyed and JS_NewContext returns null. In
 434  *                      this case the callback is not called again.
 435  *   JSCONTEXT_DESTROY  One of JS_DestroyContext* methods is called. The
 436  *                      callback may perform its own cleanup and must always
 437  *                      return true.
 438  *   Any other value    For future compatibility the callback must do nothing
 439  *                      and return true in this case.
 440  */
 441 typedef JSBool
 442 (* JSContextCallback)(JSContext *cx, uintN contextOp);
 443
 444 #ifndef JS_THREADSAFE
 445 typedef void
 446 (* JSHeartbeatCallback)(JSRuntime *rt);
 447 #endif
 448
 449 typedef enum JSGCStatus {
 450     JSGC_BEGIN,
 451     JSGC_END,
 452     JSGC_MARK_END,
 453     JSGC_FINALIZE_END
 454 } JSGCStatus;
 455
 456 typedef JSBool
 457 (* JSGCCallback)(JSContext *cx, JSGCStatus status);
 458
 459 /*
 460  * Generic trace operation that calls JS_CallTracer on each traceable thing
 461  * stored in data.
 462  */
 463 typedef void
 464 (* JSTraceDataOp)(JSTracer *trc, void *data);
 465
 466 typedef JSBool
 467 (* JSOperationCallback)(JSContext *cx);
 468
 469 typedef void
 470 (* JSErrorReporter)(JSContext *cx, const char *message, JSErrorReport *report);
 471
 472 /*
 473  * Possible exception types. These types are part of a JSErrorFormatString
 474  * structure. They define which error to throw in case of a runtime error.
 475  * JSEXN_NONE marks an unthrowable error.
 476  */
 477 typedef enum JSExnType {
 478     JSEXN_NONE = -1,
 479       JSEXN_ERR,
 480         JSEXN_INTERNALERR,
 481         JSEXN_EVALERR,
 482         JSEXN_RANGEERR,
 483         JSEXN_REFERENCEERR,
 484         JSEXN_SYNTAXERR,
 485         JSEXN_TYPEERR,
 486         JSEXN_URIERR,
 487         JSEXN_LIMIT
 488 } JSExnType;
 489
 490 typedef struct JSErrorFormatString {
 491     /* The error format string (UTF-8 if js_CStringsAreUTF8). */
 492     const char *format;
 493
 494     /* The number of arguments to expand in the formatted error message. */
 495     uint16 argCount;
 496
 497     /* One of the JSExnType constants above. */
 498     int16 exnType;
 499 } JSErrorFormatString;
 500
 501 typedef const JSErrorFormatString *
 502 (* JSErrorCallback)(void *userRef, const char *locale,
 503                     const uintN errorNumber);
 504
 505 #ifdef va_start
 506 #define JS_ARGUMENT_FORMATTER_DEFINED 1
 507
 508 typedef JSBool
 509 (* JSArgumentFormatter)(JSContext *cx, const char *format, JSBool fromJS,
 510                         jsval **vpp, va_list *app);
 511 #endif
 512
 513 typedef JSBool
 514 (* JSLocaleToUpperCase)(JSContext *cx, JSString *src, jsval *rval);
 515
 516 typedef JSBool
 517 (* JSLocaleToLowerCase)(JSContext *cx, JSString *src, jsval *rval);
 518
 519 typedef JSBool
 520 (* JSLocaleCompare)(JSContext *cx, JSString *src1, JSString *src2,
 521                     jsval *rval);
 522
 523 typedef JSBool
 524 (* JSLocaleToUnicode)(JSContext *cx, const char *src, jsval *rval);
 525
 526 /*
 527  * Security protocol types.
 528  */
 529 typedef struct JSPrincipals JSPrincipals;
 530
 531 /*
 532  * XDR-encode or -decode a principals instance, based on whether xdr->mode is
 533  * JSXDR_ENCODE, in which case *principalsp should be encoded; or JSXDR_DECODE,
 534  * in which case implementations must return a held (via JSPRINCIPALS_HOLD),
 535  * non-null *principalsp out parameter.  Return true on success, false on any
 536  * error, which the implementation must have reported.
 537  */
 538 typedef JSBool
 539 (* JSPrincipalsTranscoder)(JSXDRState *xdr, JSPrincipals **principalsp);
 540
 541 /*
 542  * Return a weak reference to the principals associated with obj, possibly via
 543  * the immutable parent chain leading from obj to a top-level container (e.g.,
 544  * a window object in the DOM level 0).  If there are no principals associated
 545  * with obj, return null.  Therefore null does not mean an error was reported;
 546  * in no event should an error be reported or an exception be thrown by this
 547  * callback's implementation.
 548  */
 549 typedef JSPrincipals *
 550 (* JSObjectPrincipalsFinder)(JSContext *cx, JSObject *obj);
 551
 552 /*
 553  * Used to check if a CSP instance wants to disable eval() and friends.
 554  * See js_CheckCSPPermitsJSAction() in jsobj.
 555  */
 556 typedef JSBool
 557 (* JSCSPEvalChecker)(JSContext *cx);
 558
 559 /*
 560  * Callback used to ask the embedding for the cross compartment wrapper handler
 561  * that implements the desired prolicy for this kind of object in the
 562  * destination compartment.
 563  */
 564 typedef JSObject *
 565 (* JSWrapObjectCallback)(JSContext *cx, JSObject *obj, JSObject *proto, JSObject *parent,
 566                          uintN flags);
 567
 568 /*
 569  * Callback used by the wrap hook to ask the embedding to prepare an object
 570  * for wrapping in a context. This might include unwrapping other wrappers
 571  * or even finding a more suitable object for the new compartment.
 572  */
 573 typedef JSObject *
 574 (* JSPreWrapCallback)(JSContext *cx, JSObject *scope, JSObject *obj, uintN flags);
 575
 576 typedef enum {
 577     JSCOMPARTMENT_NEW, /* XXX Does it make sense to have a NEW? */
 578     JSCOMPARTMENT_DESTROY
 579 } JSCompartmentOp;
 580
 581 typedef JSBool
 582 (* JSCompartmentCallback)(JSContext *cx, JSCompartment *compartment, uintN compartmentOp);
 583
 584 /*
 585  * Read structured data from the reader r. This hook is used to read a value
 586  * previously serialized by a call to the WriteStructuredCloneOp hook.
 587  *
 588  * tag and data are the pair of uint32 values from the header. The callback may
 589  * use the JS_Read* APIs to read any other relevant parts of the object from
 590  * the reader r. closure is any value passed to the JS_ReadStructuredClone
 591  * function. Return the new object on success, NULL on error/exception.
 592  */
 593 typedef JSObject *(*ReadStructuredCloneOp)(JSContext *cx, JSStructuredCloneReader *r,
 594                                            uint32 tag, uint32 data, void *closure);
 595
 596 /*
 597  * Structured data serialization hook. The engine can write primitive values,
 598  * Objects, Arrays, Dates, RegExps, TypedArrays, and ArrayBuffers. Any other
 599  * type of object requires application support. This callback must first use
 600  * the JS_WriteUint32Pair API to write an object header, passing a value
 601  * greater than JS_SCTAG_USER to the tag parameter. Then it can use the
 602  * JS_Write* APIs to write any other relevant parts of the value v to the
 603  * writer w. closure is any value passed to the JS_WriteStructuredCLone function.
 604  *
 605  * Return true on success, false on error/exception.
 606  */
 607 typedef JSBool (*WriteStructuredCloneOp)(JSContext *cx, JSStructuredCloneWriter *w,
 608                                          JSObject *obj, void *closure);
 609
 610 /*
 611  * This is called when JS_WriteStructuredClone finds that the object to be
 612  * written is recursive. To follow HTML5, the application must throw a
 613  * DATA_CLONE_ERR DOMException. errorid is always JS_SCERR_RECURSION.
 614  */
 615 typedef void (*StructuredCloneErrorOp)(JSContext *cx, uint32 errorid);
 616
 617 JS_END_EXTERN_C
 618
 619 #endif /* jspubtd_h___ */