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 jsapi_h___ 41 #define jsapi_h___ 42 /* 43 * JavaScript API. 44 */ 45 #include <stddef.h> 46 #include <stdio.h> 47 #include "jspubtd.h" 48 49 JS_BEGIN_EXTERN_C 50 51 /* 52 * Type tags stored in the low bits of a jsval. 53 */ 54 #define JSVAL_OBJECT 0x0 /* untagged reference to object */ 55 #define JSVAL_INT 0x1 /* tagged 31-bit integer value */ 56 #define JSVAL_DOUBLE 0x2 /* tagged reference to double */ 57 #define JSVAL_STRING 0x4 /* tagged reference to string */ 58 #define JSVAL_BOOLEAN 0x6 /* tagged boolean value */ 59 60 /* Type tag bitfield length and derived macros. */ 61 #define JSVAL_TAGBITS 3 62 #define JSVAL_TAGMASK JS_BITMASK(JSVAL_TAGBITS) 63 #define JSVAL_TAG(v) ((v) & JSVAL_TAGMASK) 64 #define JSVAL_SETTAG(v,t) ((v) | (t)) 65 #define JSVAL_CLRTAG(v) ((v) & ~(jsval)JSVAL_TAGMASK) 66 #define JSVAL_ALIGN JS_BIT(JSVAL_TAGBITS) 67 68 /* Predicates for type testing. */ 69 #define JSVAL_IS_OBJECT(v) (JSVAL_TAG(v) == JSVAL_OBJECT) 70 #define JSVAL_IS_NUMBER(v) (JSVAL_IS_INT(v) || JSVAL_IS_DOUBLE(v)) 71 #define JSVAL_IS_INT(v) (((v) & JSVAL_INT) && (v) != JSVAL_VOID) 72 #define JSVAL_IS_DOUBLE(v) (JSVAL_TAG(v) == JSVAL_DOUBLE) 73 #define JSVAL_IS_STRING(v) (JSVAL_TAG(v) == JSVAL_STRING) 74 #define JSVAL_IS_BOOLEAN(v) (JSVAL_TAG(v) == JSVAL_BOOLEAN) 75 #define JSVAL_IS_NULL(v) ((v) == JSVAL_NULL) 76 #define JSVAL_IS_VOID(v) ((v) == JSVAL_VOID) 77 #define JSVAL_IS_PRIMITIVE(v) (!JSVAL_IS_OBJECT(v) || JSVAL_IS_NULL(v)) 78 79 /* Objects, strings, and doubles are GC'ed. */ 80 #define JSVAL_IS_GCTHING(v) (!((v) & JSVAL_INT) && !JSVAL_IS_BOOLEAN(v)) 81 #define JSVAL_TO_GCTHING(v) ((void *)JSVAL_CLRTAG(v)) 82 #define JSVAL_TO_OBJECT(v) ((JSObject *)JSVAL_TO_GCTHING(v)) 83 #define JSVAL_TO_DOUBLE(v) ((jsdouble *)JSVAL_TO_GCTHING(v)) 84 #define JSVAL_TO_STRING(v) ((JSString *)JSVAL_TO_GCTHING(v)) 85 #define OBJECT_TO_JSVAL(obj) ((jsval)(obj)) 86 #define DOUBLE_TO_JSVAL(dp) JSVAL_SETTAG((jsval)(dp), JSVAL_DOUBLE) 87 #define STRING_TO_JSVAL(str) JSVAL_SETTAG((jsval)(str), JSVAL_STRING) 88 89 /* Lock and unlock the GC thing held by a jsval. */ 90 #define JSVAL_LOCK(cx,v) (JSVAL_IS_GCTHING(v) \ 91 ? JS_LockGCThing(cx, JSVAL_TO_GCTHING(v)) \ 92 : JS_TRUE) 93 #define JSVAL_UNLOCK(cx,v) (JSVAL_IS_GCTHING(v) \ 94 ? JS_UnlockGCThing(cx, JSVAL_TO_GCTHING(v)) \ 95 : JS_TRUE) 96 97 /* Domain limits for the jsval int type. */ 98 #define JSVAL_INT_BITS 31 99 #define JSVAL_INT_POW2(n) ((jsval)1 << (n)) 100 #define JSVAL_INT_MIN ((jsval)1 - JSVAL_INT_POW2(30)) 101 #define JSVAL_INT_MAX (JSVAL_INT_POW2(30) - 1) 102 #define INT_FITS_IN_JSVAL(i) ((jsuint)((i)+JSVAL_INT_MAX) <= 2*JSVAL_INT_MAX) 103 #define JSVAL_TO_INT(v) ((jsint)(v) >> 1) 104 #define INT_TO_JSVAL(i) (((jsval)(i) << 1) | JSVAL_INT) 105 106 /* Convert between boolean and jsval. */ 107 #define JSVAL_TO_BOOLEAN(v) ((JSBool)((v) >> JSVAL_TAGBITS)) 108 #define BOOLEAN_TO_JSVAL(b) JSVAL_SETTAG((jsval)(b) << JSVAL_TAGBITS, \ 109 JSVAL_BOOLEAN) 110 111 /* A private data pointer (2-byte-aligned) can be stored as an int jsval. */ 112 #define JSVAL_TO_PRIVATE(v) ((void *)((v) & ~JSVAL_INT)) 113 #define PRIVATE_TO_JSVAL(p) ((jsval)(p) | JSVAL_INT) 114 115 /* Property attributes, set in JSPropertySpec and passed to API functions. */ 116 #define JSPROP_ENUMERATE 0x01 /* property is visible to for/in loop */ 117 #define JSPROP_READONLY 0x02 /* not settable: assignment is no-op */ 118 #define JSPROP_PERMANENT 0x04 /* property cannot be deleted */ 119 #define JSPROP_EXPORTED 0x08 /* property is exported from object */ 120 #define JSPROP_GETTER 0x10 /* property holds getter function */ 121 #define JSPROP_SETTER 0x20 /* property holds setter function */ 122 #define JSPROP_SHARED 0x40 /* don't allocate a value slot for this 123 property; don't copy the property on 124 set of the same-named property in an 125 object that delegates to a prototype 126 containing this property */ 127 #define JSPROP_INDEX 0x80 /* name is actually (jsint) index */ 128 129 /* Function flags, set in JSFunctionSpec and passed to JS_NewFunction etc. */ 130 #define JSFUN_LAMBDA 0x08 /* expressed, not declared, function */ 131 #define JSFUN_GETTER JSPROP_GETTER 132 #define JSFUN_SETTER JSPROP_SETTER 133 #define JSFUN_BOUND_METHOD 0x40 /* bind this to fun->object's parent */ 134 #define JSFUN_HEAVYWEIGHT 0x80 /* activation requires a Call object */ 135 136 #define JSFUN_DISJOINT_FLAGS(f) ((f) & 0x0f) 137 #define JSFUN_GSFLAGS(f) ((f) & (JSFUN_GETTER | JSFUN_SETTER)) 138 139 #ifdef MOZILLA_1_8_BRANCH 140 141 /* 142 * Squeeze three more bits into existing 8-bit flags by taking advantage of 143 * the invalid combination (JSFUN_GETTER | JSFUN_SETTER). 144 */ 145 #define JSFUN_GETTER_TEST(f) (JSFUN_GSFLAGS(f) == JSFUN_GETTER) 146 #define JSFUN_SETTER_TEST(f) (JSFUN_GSFLAGS(f) == JSFUN_SETTER) 147 #define JSFUN_FLAGS_TEST(f,t) (JSFUN_GSFLAGS(~(f)) ? (f) & (t) : 0) 148 #define JSFUN_BOUND_METHOD_TEST(f) JSFUN_FLAGS_TEST(f, JSFUN_BOUND_METHOD) 149 #define JSFUN_HEAVYWEIGHT_TEST(f) JSFUN_FLAGS_TEST(f, JSFUN_HEAVYWEIGHT) 150 151 #define JSFUN_GSFLAG2ATTR(f) (JSFUN_GETTER_TEST(f) ? JSPROP_GETTER : \ 152 JSFUN_SETTER_TEST(f) ? JSPROP_SETTER : 0) 153 154 #define JSFUN_THISP_FLAGS(f) (JSFUN_GSFLAGS(~(f)) ? 0 : \ 155 (f) & JSFUN_THISP_PRIMITIVE) 156 #define JSFUN_THISP_TEST(f,t) ((f) == (t) || (f) == JSFUN_THISP_PRIMITIVE) 157 158 #define JSFUN_THISP_STRING 0x30 /* |this| may be a primitive string */ 159 #define JSFUN_THISP_NUMBER 0x70 /* |this| may be a primitive number */ 160 #define JSFUN_THISP_BOOLEAN 0xb0 /* |this| may be a primitive boolean */ 161 #define JSFUN_THISP_PRIMITIVE 0xf0 /* |this| may be any primitive value */ 162 163 #define JSFUN_FLAGS_MASK 0xf8 /* overlay JSFUN_* attributes */ 164 165 #else 166 167 #define JSFUN_GETTER_TEST(f) ((f) & JSFUN_GETTER) 168 #define JSFUN_SETTER_TEST(f) ((f) & JSFUN_SETTER) 169 #define JSFUN_BOUND_METHOD_TEST(f) ((f) & JSFUN_BOUND_METHOD) 170 #define JSFUN_HEAVYWEIGHT_TEST(f) ((f) & JSFUN_HEAVYWEIGHT) 171 172 #define JSFUN_GSFLAG2ATTR(f) JSFUN_GSFLAGS(f) 173 174 #define JSFUN_THISP_FLAGS(f) (f) 175 #define JSFUN_THISP_TEST(f,t) ((f) & t) 176 177 #define JSFUN_THISP_STRING 0x0100 /* |this| may be a primitive string */ 178 #define JSFUN_THISP_NUMBER 0x0200 /* |this| may be a primitive number */ 179 #define JSFUN_THISP_BOOLEAN 0x0400 /* |this| may be a primitive boolean */ 180 #define JSFUN_THISP_PRIMITIVE 0x0700 /* |this| may be any primitive value */ 181 182 #define JSFUN_FLAGS_MASK 0x07f8 /* overlay JSFUN_* attributes -- 183 note that bit #15 is used internally 184 to flag interpreted functions */ 185 186 #endif 187 188 /* 189 * Re-use JSFUN_LAMBDA, which applies only to scripted functions, for use in 190 * JSFunctionSpec arrays that specify generic native prototype methods, i.e., 191 * methods of a class prototype that are exposed as static methods taking an 192 * extra leading argument: the generic |this| parameter. 193 * 194 * If you set this flag in a JSFunctionSpec struct's flags initializer, then 195 * that struct must live at least as long as the native static method object 196 * created due to this flag by JS_DefineFunctions or JS_InitClass. Typically 197 * JSFunctionSpec structs are allocated in static arrays. 198 */ 199 #define JSFUN_GENERIC_NATIVE JSFUN_LAMBDA 200 201 /* 202 * Well-known JS values. The extern'd variables are initialized when the 203 * first JSContext is created by JS_NewContext (see below). 204 */ 205 #define JSVAL_VOID INT_TO_JSVAL(0 - JSVAL_INT_POW2(30)) 206 #define JSVAL_NULL OBJECT_TO_JSVAL(0) 207 #define JSVAL_ZERO INT_TO_JSVAL(0) 208 #define JSVAL_ONE INT_TO_JSVAL(1) 209 #define JSVAL_FALSE BOOLEAN_TO_JSVAL(JS_FALSE) 210 #define JSVAL_TRUE BOOLEAN_TO_JSVAL(JS_TRUE) 211 212 /* 213 * Microseconds since the epoch, midnight, January 1, 1970 UTC. See the 214 * comment in jstypes.h regarding safe int64 usage. 215 */ 216 extern JS_PUBLIC_API(int64) 217 JS_Now(); 218 219 /* Don't want to export data, so provide accessors for non-inline jsvals. */ 220 extern JS_PUBLIC_API(jsval) 221 JS_GetNaNValue(JSContext *cx); 222 223 extern JS_PUBLIC_API(jsval) 224 JS_GetNegativeInfinityValue(JSContext *cx); 225 226 extern JS_PUBLIC_API(jsval) 227 JS_GetPositiveInfinityValue(JSContext *cx); 228 229 extern JS_PUBLIC_API(jsval) 230 JS_GetEmptyStringValue(JSContext *cx); 231 232 /* 233 * Format is a string of the following characters (spaces are insignificant), 234 * specifying the tabulated type conversions: 235 * 236 * b JSBool Boolean 237 * c uint16/jschar ECMA uint16, Unicode char 238 * i int32 ECMA int32 239 * u uint32 ECMA uint32 240 * j int32 Rounded int32 (coordinate) 241 * d jsdouble IEEE double 242 * I jsdouble Integral IEEE double 243 * s char * C string 244 * S JSString * Unicode string, accessed by a JSString pointer 245 * W jschar * Unicode character vector, 0-terminated (W for wide) 246 * o JSObject * Object reference 247 * f JSFunction * Function private 248 * v jsval Argument value (no conversion) 249 * * N/A Skip this argument (no vararg) 250 * / N/A End of required arguments 251 * 252 * The variable argument list after format must consist of &b, &c, &s, e.g., 253 * where those variables have the types given above. For the pointer types 254 * char *, JSString *, and JSObject *, the pointed-at memory returned belongs 255 * to the JS runtime, not to the calling native code. The runtime promises 256 * to keep this memory valid so long as argv refers to allocated stack space 257 * (so long as the native function is active). 258 * 259 * Fewer arguments than format specifies may be passed only if there is a / 260 * in format after the last required argument specifier and argc is at least 261 * the number of required arguments. More arguments than format specifies 262 * may be passed without error; it is up to the caller to deal with trailing 263 * unconverted arguments. 264 */ 265 extern JS_PUBLIC_API(JSBool) 266 JS_ConvertArguments(JSContext *cx, uintN argc, jsval *argv, const char *format, 267 ...); 268 269 #ifdef va_start 270 extern JS_PUBLIC_API(JSBool) 271 JS_ConvertArgumentsVA(JSContext *cx, uintN argc, jsval *argv, 272 const char *format, va_list ap); 273 #endif 274 275 /* 276 * Inverse of JS_ConvertArguments: scan format and convert trailing arguments 277 * into jsvals, GC-rooted if necessary by the JS stack. Return null on error, 278 * and a pointer to the new argument vector on success. Also return a stack 279 * mark on success via *markp, in which case the caller must eventually clean 280 * up by calling JS_PopArguments. 281 * 282 * Note that the number of actual arguments supplied is specified exclusively 283 * by format, so there is no argc parameter. 284 */ 285 extern JS_PUBLIC_API(jsval *) 286 JS_PushArguments(JSContext *cx, void **markp, const char *format, ...); 287 288 #ifdef va_start 289 extern JS_PUBLIC_API(jsval *) 290 JS_PushArgumentsVA(JSContext *cx, void **markp, const char *format, va_list ap); 291 #endif 292 293 extern JS_PUBLIC_API(void) 294 JS_PopArguments(JSContext *cx, void *mark); 295 296 #ifdef JS_ARGUMENT_FORMATTER_DEFINED 297 298 /* 299 * Add and remove a format string handler for JS_{Convert,Push}Arguments{,VA}. 300 * The handler function has this signature (see jspubtd.h): 301 * 302 * JSBool MyArgumentFormatter(JSContext *cx, const char *format, 303 * JSBool fromJS, jsval **vpp, va_list *app); 304 * 305 * It should return true on success, and return false after reporting an error 306 * or detecting an already-reported error. 307 * 308 * For a given format string, for example "AA", the formatter is called from 309 * JS_ConvertArgumentsVA like so: 310 * 311 * formatter(cx, "AA...", JS_TRUE, &sp, &ap); 312 * 313 * sp points into the arguments array on the JS stack, while ap points into 314 * the stdarg.h va_list on the C stack. The JS_TRUE passed for fromJS tells 315 * the formatter to convert zero or more jsvals at sp to zero or more C values 316 * accessed via pointers-to-values at ap, updating both sp (via *vpp) and ap 317 * (via *app) to point past the converted arguments and their result pointers 318 * on the C stack. 319 * 320 * When called from JS_PushArgumentsVA, the formatter is invoked thus: 321 * 322 * formatter(cx, "AA...", JS_FALSE, &sp, &ap); 323 * 324 * where JS_FALSE for fromJS means to wrap the C values at ap according to the 325 * format specifier and store them at sp, updating ap and sp appropriately. 326 * 327 * The "..." after "AA" is the rest of the format string that was passed into 328 * JS_{Convert,Push}Arguments{,VA}. The actual format trailing substring used 329 * in each Convert or PushArguments call is passed to the formatter, so that 330 * one such function may implement several formats, in order to share code. 331 * 332 * Remove just forgets about any handler associated with format. Add does not 333 * copy format, it points at the string storage allocated by the caller, which 334 * is typically a string constant. If format is in dynamic storage, it is up 335 * to the caller to keep the string alive until Remove is called. 336 */ 337 extern JS_PUBLIC_API(JSBool) 338 JS_AddArgumentFormatter(JSContext *cx, const char *format, 339 JSArgumentFormatter formatter); 340 341 extern JS_PUBLIC_API(void) 342 JS_RemoveArgumentFormatter(JSContext *cx, const char *format); 343 344 #endif /* JS_ARGUMENT_FORMATTER_DEFINED */ 345 346 extern JS_PUBLIC_API(JSBool) 347 JS_ConvertValue(JSContext *cx, jsval v, JSType type, jsval *vp); 348 349 extern JS_PUBLIC_API(JSBool) 350 JS_ValueToObject(JSContext *cx, jsval v, JSObject **objp); 351 352 extern JS_PUBLIC_API(JSFunction *) 353 JS_ValueToFunction(JSContext *cx, jsval v); 354 355 extern JS_PUBLIC_API(JSFunction *) 356 JS_ValueToConstructor(JSContext *cx, jsval v); 357 358 extern JS_PUBLIC_API(JSString *) 359 JS_ValueToString(JSContext *cx, jsval v); 360 361 extern JS_PUBLIC_API(JSBool) 362 JS_ValueToNumber(JSContext *cx, jsval v, jsdouble *dp); 363 364 /* 365 * Convert a value to a number, then to an int32, according to the ECMA rules 366 * for ToInt32. 367 */ 368 extern JS_PUBLIC_API(JSBool) 369 JS_ValueToECMAInt32(JSContext *cx, jsval v, int32 *ip); 370 371 /* 372 * Convert a value to a number, then to a uint32, according to the ECMA rules 373 * for ToUint32. 374 */ 375 extern JS_PUBLIC_API(JSBool) 376 JS_ValueToECMAUint32(JSContext *cx, jsval v, uint32 *ip); 377 378 /* 379 * Convert a value to a number, then to an int32 if it fits by rounding to 380 * nearest; but failing with an error report if the double is out of range 381 * or unordered. 382 */ 383 extern JS_PUBLIC_API(JSBool) 384 JS_ValueToInt32(JSContext *cx, jsval v, int32 *ip); 385 386 /* 387 * ECMA ToUint16, for mapping a jsval to a Unicode point. 388 */ 389 extern JS_PUBLIC_API(JSBool) 390 JS_ValueToUint16(JSContext *cx, jsval v, uint16 *ip); 391 392 extern JS_PUBLIC_API(JSBool) 393 JS_ValueToBoolean(JSContext *cx, jsval v, JSBool *bp); 394 395 extern JS_PUBLIC_API(JSType) 396 JS_TypeOfValue(JSContext *cx, jsval v); 397 398 extern JS_PUBLIC_API(const char *) 399 JS_GetTypeName(JSContext *cx, JSType type); 400 401 /************************************************************************/ 402 403 /* 404 * Initialization, locking, contexts, and memory allocation. 405 */ 406 #define JS_NewRuntime JS_Init 407 #define JS_DestroyRuntime JS_Finish 408 #define JS_LockRuntime JS_Lock 409 #define JS_UnlockRuntime JS_Unlock 410 411 extern JS_PUBLIC_API(JSRuntime *) 412 JS_NewRuntime(uint32 maxbytes); 413 414 extern JS_PUBLIC_API(void) 415 JS_DestroyRuntime(JSRuntime *rt); 416 417 extern JS_PUBLIC_API(void) 418 JS_ShutDown(void); 419 420 JS_PUBLIC_API(void *) 421 JS_GetRuntimePrivate(JSRuntime *rt); 422 423 JS_PUBLIC_API(void) 424 JS_SetRuntimePrivate(JSRuntime *rt, void *data); 425 426 #ifdef JS_THREADSAFE 427 428 extern JS_PUBLIC_API(void) 429 JS_BeginRequest(JSContext *cx); 430 431 extern JS_PUBLIC_API(void) 432 JS_EndRequest(JSContext *cx); 433 434 /* Yield to pending GC operations, regardless of request depth */ 435 extern JS_PUBLIC_API(void) 436 JS_YieldRequest(JSContext *cx); 437 438 extern JS_PUBLIC_API(jsrefcount) 439 JS_SuspendRequest(JSContext *cx); 440 441 extern JS_PUBLIC_API(void) 442 JS_ResumeRequest(JSContext *cx, jsrefcount saveDepth); 443 444 #ifdef __cplusplus 445 JS_END_EXTERN_C 446 447 class JSAutoRequest { 448 public: JSAutoRequest(JSContext * cx)449 JSAutoRequest(JSContext *cx) : mContext(cx), mSaveDepth(0) { 450 JS_BeginRequest(mContext); 451 } ~JSAutoRequest()452 ~JSAutoRequest() { 453 JS_EndRequest(mContext); 454 } 455 suspend()456 void suspend() { 457 mSaveDepth = JS_SuspendRequest(mContext); 458 } resume()459 void resume() { 460 JS_ResumeRequest(mContext, mSaveDepth); 461 } 462 463 protected: 464 JSContext *mContext; 465 jsrefcount mSaveDepth; 466 467 #if 0 468 private: 469 static void *operator new(size_t) CPP_THROW_NEW { return 0; }; 470 static void operator delete(void *, size_t) { }; 471 #endif 472 }; 473 474 JS_BEGIN_EXTERN_C 475 #endif 476 477 #endif /* JS_THREADSAFE */ 478 479 extern JS_PUBLIC_API(void) 480 JS_Lock(JSRuntime *rt); 481 482 extern JS_PUBLIC_API(void) 483 JS_Unlock(JSRuntime *rt); 484 485 extern JS_PUBLIC_API(JSContextCallback) 486 JS_SetContextCallback(JSRuntime *rt, JSContextCallback cxCallback); 487 488 extern JS_PUBLIC_API(JSContext *) 489 JS_NewContext(JSRuntime *rt, size_t stackChunkSize); 490 491 extern JS_PUBLIC_API(void) 492 JS_DestroyContext(JSContext *cx); 493 494 extern JS_PUBLIC_API(void) 495 JS_DestroyContextNoGC(JSContext *cx); 496 497 extern JS_PUBLIC_API(void) 498 JS_DestroyContextMaybeGC(JSContext *cx); 499 500 extern JS_PUBLIC_API(void *) 501 JS_GetContextPrivate(JSContext *cx); 502 503 extern JS_PUBLIC_API(void) 504 JS_SetContextPrivate(JSContext *cx, void *data); 505 506 extern JS_PUBLIC_API(JSRuntime *) 507 JS_GetRuntime(JSContext *cx); 508 509 extern JS_PUBLIC_API(JSContext *) 510 JS_ContextIterator(JSRuntime *rt, JSContext **iterp); 511 512 extern JS_PUBLIC_API(JSVersion) 513 JS_GetVersion(JSContext *cx); 514 515 extern JS_PUBLIC_API(JSVersion) 516 JS_SetVersion(JSContext *cx, JSVersion version); 517 518 extern JS_PUBLIC_API(const char *) 519 JS_VersionToString(JSVersion version); 520 521 extern JS_PUBLIC_API(JSVersion) 522 JS_StringToVersion(const char *string); 523 524 /* 525 * JS options are orthogonal to version, and may be freely composed with one 526 * another as well as with version. 527 * 528 * JSOPTION_VAROBJFIX is recommended -- see the comments associated with the 529 * prototypes for JS_ExecuteScript, JS_EvaluateScript, etc. 530 */ 531 #define JSOPTION_STRICT JS_BIT(0) /* warn on dubious practice */ 532 #define JSOPTION_WERROR JS_BIT(1) /* convert warning to error */ 533 #define JSOPTION_VAROBJFIX JS_BIT(2) /* make JS_EvaluateScript use 534 the last object on its 'obj' 535 param's scope chain as the 536 ECMA 'variables object' */ 537 #define JSOPTION_PRIVATE_IS_NSISUPPORTS \ 538 JS_BIT(3) /* context private data points 539 to an nsISupports subclass */ 540 #define JSOPTION_COMPILE_N_GO JS_BIT(4) /* caller of JS_Compile*Script 541 promises to execute compiled 542 script once only; enables 543 compile-time scope chain 544 resolution of consts. */ 545 #define JSOPTION_ATLINE JS_BIT(5) /* //@line number ["filename"] 546 option supported for the 547 XUL preprocessor and kindred 548 beasts. */ 549 #define JSOPTION_XML JS_BIT(6) /* EMCAScript for XML support: 550 parse <!-- --> as a token, 551 not backward compatible with 552 the comment-hiding hack used 553 in HTML script tags. */ 554 #define JSOPTION_NATIVE_BRANCH_CALLBACK \ 555 JS_BIT(7) /* the branch callback set by 556 JS_SetBranchCallback may be 557 called with a null script 558 parameter, by native code 559 that loops intensively */ 560 #define JSOPTION_DONT_REPORT_UNCAUGHT \ 561 JS_BIT(8) /* When returning from the 562 outermost API call, prevent 563 uncaught exceptions from 564 being converted to error 565 reports */ 566 567 extern JS_PUBLIC_API(uint32) 568 JS_GetOptions(JSContext *cx); 569 570 extern JS_PUBLIC_API(uint32) 571 JS_SetOptions(JSContext *cx, uint32 options); 572 573 extern JS_PUBLIC_API(uint32) 574 JS_ToggleOptions(JSContext *cx, uint32 options); 575 576 extern JS_PUBLIC_API(const char *) 577 JS_GetImplementationVersion(void); 578 579 extern JS_PUBLIC_API(JSObject *) 580 JS_GetGlobalObject(JSContext *cx); 581 582 extern JS_PUBLIC_API(void) 583 JS_SetGlobalObject(JSContext *cx, JSObject *obj); 584 585 /* 586 * Initialize standard JS class constructors, prototypes, and any top-level 587 * functions and constants associated with the standard classes (e.g. isNaN 588 * for Number). 589 * 590 * NB: This sets cx's global object to obj if it was null. 591 */ 592 extern JS_PUBLIC_API(JSBool) 593 JS_InitStandardClasses(JSContext *cx, JSObject *obj); 594 595 /* 596 * Resolve id, which must contain either a string or an int, to a standard 597 * class name in obj if possible, defining the class's constructor and/or 598 * prototype and storing true in *resolved. If id does not name a standard 599 * class or a top-level property induced by initializing a standard class, 600 * store false in *resolved and just return true. Return false on error, 601 * as usual for JSBool result-typed API entry points. 602 * 603 * This API can be called directly from a global object class's resolve op, 604 * to define standard classes lazily. The class's enumerate op should call 605 * JS_EnumerateStandardClasses(cx, obj), to define eagerly during for..in 606 * loops any classes not yet resolved lazily. 607 */ 608 extern JS_PUBLIC_API(JSBool) 609 JS_ResolveStandardClass(JSContext *cx, JSObject *obj, jsval id, 610 JSBool *resolved); 611 612 extern JS_PUBLIC_API(JSBool) 613 JS_EnumerateStandardClasses(JSContext *cx, JSObject *obj); 614 615 /* 616 * Enumerate any already-resolved standard class ids into ida, or into a new 617 * JSIdArray if ida is null. Return the augmented array on success, null on 618 * failure with ida (if it was non-null on entry) destroyed. 619 */ 620 extern JS_PUBLIC_API(JSIdArray *) 621 JS_EnumerateResolvedStandardClasses(JSContext *cx, JSObject *obj, 622 JSIdArray *ida); 623 624 extern JS_PUBLIC_API(JSBool) 625 JS_GetClassObject(JSContext *cx, JSObject *obj, JSProtoKey key, 626 JSObject **objp); 627 628 extern JS_PUBLIC_API(JSObject *) 629 JS_GetScopeChain(JSContext *cx); 630 631 extern JS_PUBLIC_API(void *) 632 JS_malloc(JSContext *cx, size_t nbytes); 633 634 extern JS_PUBLIC_API(void *) 635 JS_realloc(JSContext *cx, void *p, size_t nbytes); 636 637 extern JS_PUBLIC_API(void) 638 JS_free(JSContext *cx, void *p); 639 640 extern JS_PUBLIC_API(char *) 641 JS_strdup(JSContext *cx, const char *s); 642 643 extern JS_PUBLIC_API(jsdouble *) 644 JS_NewDouble(JSContext *cx, jsdouble d); 645 646 extern JS_PUBLIC_API(JSBool) 647 JS_NewDoubleValue(JSContext *cx, jsdouble d, jsval *rval); 648 649 extern JS_PUBLIC_API(JSBool) 650 JS_NewNumberValue(JSContext *cx, jsdouble d, jsval *rval); 651 652 /* 653 * A JS GC root is a pointer to a JSObject *, JSString *, or jsdouble * that 654 * itself points into the GC heap (more recently, we support this extension: 655 * a root may be a pointer to a jsval v for which JSVAL_IS_GCTHING(v) is true). 656 * 657 * Therefore, you never pass JSObject *obj to JS_AddRoot(cx, obj). You always 658 * call JS_AddRoot(cx, &obj), passing obj by reference. And later, before obj 659 * or the structure it is embedded within goes out of scope or is freed, you 660 * must call JS_RemoveRoot(cx, &obj). 661 * 662 * Also, use JS_AddNamedRoot(cx, &structPtr->memberObj, "structPtr->memberObj") 663 * in preference to JS_AddRoot(cx, &structPtr->memberObj), in order to identify 664 * roots by their source callsites. This way, you can find the callsite while 665 * debugging if you should fail to do JS_RemoveRoot(cx, &structPtr->memberObj) 666 * before freeing structPtr's memory. 667 */ 668 extern JS_PUBLIC_API(JSBool) 669 JS_AddRoot(JSContext *cx, void *rp); 670 671 #ifdef NAME_ALL_GC_ROOTS 672 #define JS_DEFINE_TO_TOKEN(def) #def 673 #define JS_DEFINE_TO_STRING(def) JS_DEFINE_TO_TOKEN(def) 674 #define JS_AddRoot(cx,rp) JS_AddNamedRoot((cx), (rp), (__FILE__ ":" JS_TOKEN_TO_STRING(__LINE__)) 675 #endif 676 677 extern JS_PUBLIC_API(JSBool) 678 JS_AddNamedRoot(JSContext *cx, void *rp, const char *name); 679 680 extern JS_PUBLIC_API(JSBool) 681 JS_AddNamedRootRT(JSRuntime *rt, void *rp, const char *name); 682 683 extern JS_PUBLIC_API(JSBool) 684 JS_RemoveRoot(JSContext *cx, void *rp); 685 686 extern JS_PUBLIC_API(JSBool) 687 JS_RemoveRootRT(JSRuntime *rt, void *rp); 688 689 /* 690 * The last GC thing of each type (object, string, double, external string 691 * types) created on a given context is kept alive until another thing of the 692 * same type is created, using a newborn root in the context. These newborn 693 * roots help native code protect newly-created GC-things from GC invocations 694 * activated before those things can be rooted using local or global roots. 695 * 696 * However, the newborn roots can also entrain great gobs of garbage, so the 697 * JS_GC entry point clears them for the context on which GC is being forced. 698 * Embeddings may need to do likewise for all contexts. 699 * 700 * See the scoped local root API immediately below for a better way to manage 701 * newborns in cases where native hooks (functions, getters, setters, etc.) 702 * create many GC-things, potentially without connecting them to predefined 703 * local roots such as *rval or argv[i] in an active native function. Using 704 * JS_EnterLocalRootScope disables updating of the context's per-gc-thing-type 705 * newborn roots, until control flow unwinds and leaves the outermost nesting 706 * local root scope. 707 */ 708 extern JS_PUBLIC_API(void) 709 JS_ClearNewbornRoots(JSContext *cx); 710 711 /* 712 * Scoped local root management allows native functions, getter/setters, etc. 713 * to avoid worrying about the newborn root pigeon-holes, overloading local 714 * roots allocated in argv and *rval, or ending up having to call JS_Add*Root 715 * and JS_RemoveRoot to manage global roots temporarily. 716 * 717 * Instead, calling JS_EnterLocalRootScope and JS_LeaveLocalRootScope around 718 * the body of the native hook causes the engine to allocate a local root for 719 * each newborn created in between the two API calls, using a local root stack 720 * associated with cx. For example: 721 * 722 * JSBool 723 * my_GetProperty(JSContext *cx, JSObject *obj, jsval id, jsval *vp) 724 * { 725 * JSBool ok; 726 * 727 * if (!JS_EnterLocalRootScope(cx)) 728 * return JS_FALSE; 729 * ok = my_GetPropertyBody(cx, obj, id, vp); 730 * JS_LeaveLocalRootScope(cx); 731 * return ok; 732 * } 733 * 734 * NB: JS_LeaveLocalRootScope must be called once for every prior successful 735 * call to JS_EnterLocalRootScope. If JS_EnterLocalRootScope fails, you must 736 * not make the matching JS_LeaveLocalRootScope call. 737 * 738 * JS_LeaveLocalRootScopeWithResult(cx, rval) is an alternative way to leave 739 * a local root scope that protects a result or return value, by effectively 740 * pushing it in the caller's local root scope. 741 * 742 * In case a native hook allocates many objects or other GC-things, but the 743 * native protects some of those GC-things by storing them as property values 744 * in an object that is itself protected, the hook can call JS_ForgetLocalRoot 745 * to free the local root automatically pushed for the now-protected GC-thing. 746 * 747 * JS_ForgetLocalRoot works on any GC-thing allocated in the current local 748 * root scope, but it's more time-efficient when called on references to more 749 * recently created GC-things. Calling it successively on other than the most 750 * recently allocated GC-thing will tend to average the time inefficiency, and 751 * may risk O(n^2) growth rate, but in any event, you shouldn't allocate too 752 * many local roots if you can root as you go (build a tree of objects from 753 * the top down, forgetting each latest-allocated GC-thing immediately upon 754 * linking it to its parent). 755 */ 756 extern JS_PUBLIC_API(JSBool) 757 JS_EnterLocalRootScope(JSContext *cx); 758 759 extern JS_PUBLIC_API(void) 760 JS_LeaveLocalRootScope(JSContext *cx); 761 762 extern JS_PUBLIC_API(void) 763 JS_LeaveLocalRootScopeWithResult(JSContext *cx, jsval rval); 764 765 extern JS_PUBLIC_API(void) 766 JS_ForgetLocalRoot(JSContext *cx, void *thing); 767 768 #ifdef __cplusplus 769 JS_END_EXTERN_C 770 771 class JSAutoLocalRootScope { 772 public: JSAutoLocalRootScope(JSContext * cx)773 JSAutoLocalRootScope(JSContext *cx) : mContext(cx) { 774 JS_EnterLocalRootScope(mContext); 775 } ~JSAutoLocalRootScope()776 ~JSAutoLocalRootScope() { 777 JS_LeaveLocalRootScope(mContext); 778 } 779 forget(void * thing)780 void forget(void *thing) { 781 JS_ForgetLocalRoot(mContext, thing); 782 } 783 784 protected: 785 JSContext *mContext; 786 787 #if 0 788 private: 789 static void *operator new(size_t) CPP_THROW_NEW { return 0; }; 790 static void operator delete(void *, size_t) { }; 791 #endif 792 }; 793 794 JS_BEGIN_EXTERN_C 795 #endif 796 797 #ifdef DEBUG 798 extern JS_PUBLIC_API(void) 799 JS_DumpNamedRoots(JSRuntime *rt, 800 void (*dump)(const char *name, void *rp, void *data), 801 void *data); 802 #endif 803 804 /* 805 * Call JS_MapGCRoots to map the GC's roots table using map(rp, name, data). 806 * The root is pointed at by rp; if the root is unnamed, name is null; data is 807 * supplied from the third parameter to JS_MapGCRoots. 808 * 809 * The map function should return JS_MAP_GCROOT_REMOVE to cause the currently 810 * enumerated root to be removed. To stop enumeration, set JS_MAP_GCROOT_STOP 811 * in the return value. To keep on mapping, return JS_MAP_GCROOT_NEXT. These 812 * constants are flags; you can OR them together. 813 * 814 * This function acquires and releases rt's GC lock around the mapping of the 815 * roots table, so the map function should run to completion in as few cycles 816 * as possible. Of course, map cannot call JS_GC, JS_MaybeGC, JS_BeginRequest, 817 * or any JS API entry point that acquires locks, without double-tripping or 818 * deadlocking on the GC lock. 819 * 820 * JS_MapGCRoots returns the count of roots that were successfully mapped. 821 */ 822 #define JS_MAP_GCROOT_NEXT 0 /* continue mapping entries */ 823 #define JS_MAP_GCROOT_STOP 1 /* stop mapping entries */ 824 #define JS_MAP_GCROOT_REMOVE 2 /* remove and free the current entry */ 825 826 typedef intN 827 (* JS_DLL_CALLBACK JSGCRootMapFun)(void *rp, const char *name, void *data); 828 829 extern JS_PUBLIC_API(uint32) 830 JS_MapGCRoots(JSRuntime *rt, JSGCRootMapFun map, void *data); 831 832 extern JS_PUBLIC_API(JSBool) 833 JS_LockGCThing(JSContext *cx, void *thing); 834 835 extern JS_PUBLIC_API(JSBool) 836 JS_LockGCThingRT(JSRuntime *rt, void *thing); 837 838 extern JS_PUBLIC_API(JSBool) 839 JS_UnlockGCThing(JSContext *cx, void *thing); 840 841 extern JS_PUBLIC_API(JSBool) 842 JS_UnlockGCThingRT(JSRuntime *rt, void *thing); 843 844 /* 845 * For implementors of JSObjectOps.mark, to mark a GC-thing reachable via a 846 * property or other strong ref identified for debugging purposes by name. 847 * The name argument's storage needs to live only as long as the call to 848 * this routine. 849 * 850 * The final arg is used by GC_MARK_DEBUG code to build a ref path through 851 * the GC's live thing graph. Implementors of JSObjectOps.mark should pass 852 * its final arg through to this function when marking all GC-things that are 853 * directly reachable from the object being marked. 854 * 855 * See the JSMarkOp typedef in jspubtd.h, and the JSObjectOps struct below. 856 */ 857 extern JS_PUBLIC_API(void) 858 JS_MarkGCThing(JSContext *cx, void *thing, const char *name, void *arg); 859 860 extern JS_PUBLIC_API(void) 861 JS_GC(JSContext *cx); 862 863 extern JS_PUBLIC_API(void) 864 JS_MaybeGC(JSContext *cx); 865 866 extern JS_PUBLIC_API(JSGCCallback) 867 JS_SetGCCallback(JSContext *cx, JSGCCallback cb); 868 869 extern JS_PUBLIC_API(JSGCCallback) 870 JS_SetGCCallbackRT(JSRuntime *rt, JSGCCallback cb); 871 872 extern JS_PUBLIC_API(JSBool) 873 JS_IsAboutToBeFinalized(JSContext *cx, void *thing); 874 875 typedef enum JSGCParamKey { 876 JSGC_MAX_BYTES = 0, /* maximum nominal heap before last ditch GC */ 877 JSGC_MAX_MALLOC_BYTES = 1 /* # of JS_malloc bytes before last ditch GC */ 878 } JSGCParamKey; 879 880 extern JS_PUBLIC_API(void) 881 JS_SetGCParameter(JSRuntime *rt, JSGCParamKey key, uint32 value); 882 883 /* 884 * Add a finalizer for external strings created by JS_NewExternalString (see 885 * below) using a type-code returned from this function, and that understands 886 * how to free or release the memory pointed at by JS_GetStringChars(str). 887 * 888 * Return a nonnegative type index if there is room for finalizer in the 889 * global GC finalizers table, else return -1. If the engine is compiled 890 * JS_THREADSAFE and used in a multi-threaded environment, this function must 891 * be invoked on the primordial thread only, at startup -- or else the entire 892 * program must single-thread itself while loading a module that calls this 893 * function. 894 */ 895 extern JS_PUBLIC_API(intN) 896 JS_AddExternalStringFinalizer(JSStringFinalizeOp finalizer); 897 898 /* 899 * Remove finalizer from the global GC finalizers table, returning its type 900 * code if found, -1 if not found. 901 * 902 * As with JS_AddExternalStringFinalizer, there is a threading restriction 903 * if you compile the engine JS_THREADSAFE: this function may be called for a 904 * given finalizer pointer on only one thread; different threads may call to 905 * remove distinct finalizers safely. 906 * 907 * You must ensure that all strings with finalizer's type have been collected 908 * before calling this function. Otherwise, string data will be leaked by the 909 * GC, for want of a finalizer to call. 910 */ 911 extern JS_PUBLIC_API(intN) 912 JS_RemoveExternalStringFinalizer(JSStringFinalizeOp finalizer); 913 914 /* 915 * Create a new JSString whose chars member refers to external memory, i.e., 916 * memory requiring special, type-specific finalization. The type code must 917 * be a nonnegative return value from JS_AddExternalStringFinalizer. 918 */ 919 extern JS_PUBLIC_API(JSString *) 920 JS_NewExternalString(JSContext *cx, jschar *chars, size_t length, intN type); 921 922 /* 923 * Returns the external-string finalizer index for this string, or -1 if it is 924 * an "internal" (native to JS engine) string. 925 */ 926 extern JS_PUBLIC_API(intN) 927 JS_GetExternalStringGCType(JSRuntime *rt, JSString *str); 928 929 /* 930 * Sets maximum (if stack grows upward) or minimum (downward) legal stack byte 931 * address in limitAddr for the thread or process stack used by cx. To disable 932 * stack size checking, pass 0 for limitAddr. 933 */ 934 extern JS_PUBLIC_API(void) 935 JS_SetThreadStackLimit(JSContext *cx, jsuword limitAddr); 936 937 /************************************************************************/ 938 939 /* 940 * Classes, objects, and properties. 941 */ 942 943 /* For detailed comments on the function pointer types, see jspubtd.h. */ 944 struct JSClass { 945 const char *name; 946 uint32 flags; 947 948 /* Mandatory non-null function pointer members. */ 949 JSPropertyOp addProperty; 950 JSPropertyOp delProperty; 951 JSPropertyOp getProperty; 952 JSPropertyOp setProperty; 953 JSEnumerateOp enumerate; 954 JSResolveOp resolve; 955 JSConvertOp convert; 956 JSFinalizeOp finalize; 957 958 /* Optionally non-null members start here. */ 959 JSGetObjectOps getObjectOps; 960 JSCheckAccessOp checkAccess; 961 JSNative call; 962 JSNative construct; 963 JSXDRObjectOp xdrObject; 964 JSHasInstanceOp hasInstance; 965 JSMarkOp mark; 966 JSReserveSlotsOp reserveSlots; 967 }; 968 969 struct JSExtendedClass { 970 JSClass base; 971 JSEqualityOp equality; 972 JSObjectOp outerObject; 973 JSObjectOp innerObject; 974 void (*reserved0)(); 975 void (*reserved1)(); 976 void (*reserved2)(); 977 void (*reserved3)(); 978 void (*reserved4)(); 979 }; 980 981 #define JSCLASS_HAS_PRIVATE (1<<0) /* objects have private slot */ 982 #define JSCLASS_NEW_ENUMERATE (1<<1) /* has JSNewEnumerateOp hook */ 983 #define JSCLASS_NEW_RESOLVE (1<<2) /* has JSNewResolveOp hook */ 984 #define JSCLASS_PRIVATE_IS_NSISUPPORTS (1<<3) /* private is (nsISupports *) */ 985 #define JSCLASS_SHARE_ALL_PROPERTIES (1<<4) /* all properties are SHARED */ 986 #define JSCLASS_NEW_RESOLVE_GETS_START (1<<5) /* JSNewResolveOp gets starting 987 object in prototype chain 988 passed in via *objp in/out 989 parameter */ 990 #define JSCLASS_CONSTRUCT_PROTOTYPE (1<<6) /* call constructor on class 991 prototype */ 992 #define JSCLASS_DOCUMENT_OBSERVER (1<<7) /* DOM document observer */ 993 994 /* 995 * To reserve slots fetched and stored via JS_Get/SetReservedSlot, bitwise-or 996 * JSCLASS_HAS_RESERVED_SLOTS(n) into the initializer for JSClass.flags, where 997 * n is a constant in [1, 255]. Reserved slots are indexed from 0 to n-1. 998 */ 999 #define JSCLASS_RESERVED_SLOTS_SHIFT 8 /* room for 8 flags below */ 1000 #define JSCLASS_RESERVED_SLOTS_WIDTH 8 /* and 16 above this field */ 1001 #define JSCLASS_RESERVED_SLOTS_MASK JS_BITMASK(JSCLASS_RESERVED_SLOTS_WIDTH) 1002 #define JSCLASS_HAS_RESERVED_SLOTS(n) (((n) & JSCLASS_RESERVED_SLOTS_MASK) \ 1003 << JSCLASS_RESERVED_SLOTS_SHIFT) 1004 #define JSCLASS_RESERVED_SLOTS(clasp) (((clasp)->flags \ 1005 >> JSCLASS_RESERVED_SLOTS_SHIFT) \ 1006 & JSCLASS_RESERVED_SLOTS_MASK) 1007 1008 #define JSCLASS_HIGH_FLAGS_SHIFT (JSCLASS_RESERVED_SLOTS_SHIFT + \ 1009 JSCLASS_RESERVED_SLOTS_WIDTH) 1010 1011 /* True if JSClass is really a JSExtendedClass. */ 1012 #define JSCLASS_IS_EXTENDED (1<<(JSCLASS_HIGH_FLAGS_SHIFT+0)) 1013 #define JSCLASS_IS_ANONYMOUS (1<<(JSCLASS_HIGH_FLAGS_SHIFT+1)) 1014 #define JSCLASS_IS_GLOBAL (1<<(JSCLASS_HIGH_FLAGS_SHIFT+2)) 1015 1016 /* 1017 * ECMA-262 requires that most constructors used internally create objects 1018 * with "the original Foo.prototype value" as their [[Prototype]] (__proto__) 1019 * member initial value. The "original ... value" verbiage is there because 1020 * in ECMA-262, global properties naming class objects are read/write and 1021 * deleteable, for the most part. 1022 * 1023 * Implementing this efficiently requires that global objects have classes 1024 * with the following flags. Failure to use JSCLASS_GLOBAL_FLAGS won't break 1025 * anything except the ECMA-262 "original prototype value" behavior, which was 1026 * broken for years in SpiderMonkey. In other words, without these flags you 1027 * get backward compatibility. 1028 */ 1029 #define JSCLASS_GLOBAL_FLAGS \ 1030 (JSCLASS_IS_GLOBAL | JSCLASS_HAS_RESERVED_SLOTS(JSProto_LIMIT)) 1031 1032 /* Fast access to the original value of each standard class's prototype. */ 1033 #define JSCLASS_CACHED_PROTO_SHIFT (JSCLASS_HIGH_FLAGS_SHIFT + 8) 1034 #define JSCLASS_CACHED_PROTO_WIDTH 8 1035 #define JSCLASS_CACHED_PROTO_MASK JS_BITMASK(JSCLASS_CACHED_PROTO_WIDTH) 1036 #define JSCLASS_HAS_CACHED_PROTO(key) ((key) << JSCLASS_CACHED_PROTO_SHIFT) 1037 #define JSCLASS_CACHED_PROTO_KEY(clasp) (((clasp)->flags \ 1038 >> JSCLASS_CACHED_PROTO_SHIFT) \ 1039 & JSCLASS_CACHED_PROTO_MASK) 1040 1041 /* Initializer for unused members of statically initialized JSClass structs. */ 1042 #define JSCLASS_NO_OPTIONAL_MEMBERS 0,0,0,0,0,0,0,0 1043 #define JSCLASS_NO_RESERVED_MEMBERS 0,0,0,0,0 1044 1045 /* For detailed comments on these function pointer types, see jspubtd.h. */ 1046 struct JSObjectOps { 1047 /* Mandatory non-null function pointer members. */ 1048 JSNewObjectMapOp newObjectMap; 1049 JSObjectMapOp destroyObjectMap; 1050 JSLookupPropOp lookupProperty; 1051 JSDefinePropOp defineProperty; 1052 JSPropertyIdOp getProperty; 1053 JSPropertyIdOp setProperty; 1054 JSAttributesOp getAttributes; 1055 JSAttributesOp setAttributes; 1056 JSPropertyIdOp deleteProperty; 1057 JSConvertOp defaultValue; 1058 JSNewEnumerateOp enumerate; 1059 JSCheckAccessIdOp checkAccess; 1060 1061 /* Optionally non-null members start here. */ 1062 JSObjectOp thisObject; 1063 JSPropertyRefOp dropProperty; 1064 JSNative call; 1065 JSNative construct; 1066 JSXDRObjectOp xdrObject; 1067 JSHasInstanceOp hasInstance; 1068 JSSetObjectSlotOp setProto; 1069 JSSetObjectSlotOp setParent; 1070 JSMarkOp mark; 1071 JSFinalizeOp clear; 1072 JSGetRequiredSlotOp getRequiredSlot; 1073 JSSetRequiredSlotOp setRequiredSlot; 1074 }; 1075 1076 struct JSXMLObjectOps { 1077 JSObjectOps base; 1078 JSGetMethodOp getMethod; 1079 JSSetMethodOp setMethod; 1080 JSEnumerateValuesOp enumerateValues; 1081 JSEqualityOp equality; 1082 JSConcatenateOp concatenate; 1083 }; 1084 1085 /* 1086 * Classes that expose JSObjectOps via a non-null getObjectOps class hook may 1087 * derive a property structure from this struct, return a pointer to it from 1088 * lookupProperty and defineProperty, and use the pointer to avoid rehashing 1089 * in getAttributes and setAttributes. 1090 * 1091 * The jsid type contains either an int jsval (see JSVAL_IS_INT above), or an 1092 * internal pointer that is opaque to users of this API, but which users may 1093 * convert from and to a jsval using JS_ValueToId and JS_IdToValue. 1094 */ 1095 struct JSProperty { 1096 jsid id; 1097 }; 1098 1099 struct JSIdArray { 1100 jsint length; 1101 jsid vector[1]; /* actually, length jsid words */ 1102 }; 1103 1104 extern JS_PUBLIC_API(void) 1105 JS_DestroyIdArray(JSContext *cx, JSIdArray *ida); 1106 1107 extern JS_PUBLIC_API(JSBool) 1108 JS_ValueToId(JSContext *cx, jsval v, jsid *idp); 1109 1110 extern JS_PUBLIC_API(JSBool) 1111 JS_IdToValue(JSContext *cx, jsid id, jsval *vp); 1112 1113 /* 1114 * The magic XML namespace id is int-tagged, but not a valid integer jsval. 1115 * Global object classes in embeddings that enable JS_HAS_XML_SUPPORT (E4X) 1116 * should handle this id specially before converting id via JSVAL_TO_INT. 1117 */ 1118 #define JS_DEFAULT_XML_NAMESPACE_ID ((jsid) JSVAL_VOID) 1119 1120 /* 1121 * JSNewResolveOp flag bits. 1122 */ 1123 #define JSRESOLVE_QUALIFIED 0x01 /* resolve a qualified property id */ 1124 #define JSRESOLVE_ASSIGNING 0x02 /* resolve on the left of assignment */ 1125 #define JSRESOLVE_DETECTING 0x04 /* 'if (o.p)...' or '(o.p) ?...:...' */ 1126 #define JSRESOLVE_DECLARING 0x08 /* var, const, or function prolog op */ 1127 #define JSRESOLVE_CLASSNAME 0x10 /* class name used when constructing */ 1128 1129 extern JS_PUBLIC_API(JSBool) 1130 JS_PropertyStub(JSContext *cx, JSObject *obj, jsval id, jsval *vp); 1131 1132 extern JS_PUBLIC_API(JSBool) 1133 JS_EnumerateStub(JSContext *cx, JSObject *obj); 1134 1135 extern JS_PUBLIC_API(JSBool) 1136 JS_ResolveStub(JSContext *cx, JSObject *obj, jsval id); 1137 1138 extern JS_PUBLIC_API(JSBool) 1139 JS_ConvertStub(JSContext *cx, JSObject *obj, JSType type, jsval *vp); 1140 1141 extern JS_PUBLIC_API(void) 1142 JS_FinalizeStub(JSContext *cx, JSObject *obj); 1143 1144 struct JSConstDoubleSpec { 1145 jsdouble dval; 1146 const char *name; 1147 uint8 flags; 1148 uint8 spare[3]; 1149 }; 1150 1151 /* 1152 * To define an array element rather than a named property member, cast the 1153 * element's index to (const char *) and initialize name with it, and set the 1154 * JSPROP_INDEX bit in flags. 1155 */ 1156 struct JSPropertySpec { 1157 const char *name; 1158 int8 tinyid; 1159 uint8 flags; 1160 JSPropertyOp getter; 1161 JSPropertyOp setter; 1162 }; 1163 1164 struct JSFunctionSpec { 1165 const char *name; 1166 JSNative call; 1167 #ifdef MOZILLA_1_8_BRANCH 1168 uint8 nargs; 1169 uint8 flags; 1170 uint16 extra; 1171 #else 1172 uint16 nargs; 1173 uint16 flags; 1174 uint32 extra; /* extra & 0xFFFF: 1175 number of arg slots for local GC roots 1176 extra >> 16: 1177 reserved, must be zero */ 1178 #endif 1179 }; 1180 1181 extern JS_PUBLIC_API(JSObject *) 1182 JS_InitClass(JSContext *cx, JSObject *obj, JSObject *parent_proto, 1183 JSClass *clasp, JSNative constructor, uintN nargs, 1184 JSPropertySpec *ps, JSFunctionSpec *fs, 1185 JSPropertySpec *static_ps, JSFunctionSpec *static_fs); 1186 1187 #ifdef JS_THREADSAFE 1188 extern JS_PUBLIC_API(JSClass *) 1189 JS_GetClass(JSContext *cx, JSObject *obj); 1190 1191 #define JS_GET_CLASS(cx,obj) JS_GetClass(cx, obj) 1192 #else 1193 extern JS_PUBLIC_API(JSClass *) 1194 JS_GetClass(JSObject *obj); 1195 1196 #define JS_GET_CLASS(cx,obj) JS_GetClass(obj) 1197 #endif 1198 1199 extern JS_PUBLIC_API(JSBool) 1200 JS_InstanceOf(JSContext *cx, JSObject *obj, JSClass *clasp, jsval *argv); 1201 1202 extern JS_PUBLIC_API(JSBool) 1203 JS_HasInstance(JSContext *cx, JSObject *obj, jsval v, JSBool *bp); 1204 1205 extern JS_PUBLIC_API(void *) 1206 JS_GetPrivate(JSContext *cx, JSObject *obj); 1207 1208 extern JS_PUBLIC_API(JSBool) 1209 JS_SetPrivate(JSContext *cx, JSObject *obj, void *data); 1210 1211 extern JS_PUBLIC_API(void *) 1212 JS_GetInstancePrivate(JSContext *cx, JSObject *obj, JSClass *clasp, 1213 jsval *argv); 1214 1215 extern JS_PUBLIC_API(JSObject *) 1216 JS_GetPrototype(JSContext *cx, JSObject *obj); 1217 1218 extern JS_PUBLIC_API(JSBool) 1219 JS_SetPrototype(JSContext *cx, JSObject *obj, JSObject *proto); 1220 1221 extern JS_PUBLIC_API(JSObject *) 1222 JS_GetParent(JSContext *cx, JSObject *obj); 1223 1224 extern JS_PUBLIC_API(JSBool) 1225 JS_SetParent(JSContext *cx, JSObject *obj, JSObject *parent); 1226 1227 extern JS_PUBLIC_API(JSObject *) 1228 JS_GetConstructor(JSContext *cx, JSObject *proto); 1229 1230 /* 1231 * Get a unique identifier for obj, good for the lifetime of obj (even if it 1232 * is moved by a copying GC). Return false on failure (likely out of memory), 1233 * and true with *idp containing the unique id on success. 1234 */ 1235 extern JS_PUBLIC_API(JSBool) 1236 JS_GetObjectId(JSContext *cx, JSObject *obj, jsid *idp); 1237 1238 extern JS_PUBLIC_API(JSObject *) 1239 JS_NewObject(JSContext *cx, JSClass *clasp, JSObject *proto, JSObject *parent); 1240 1241 extern JS_PUBLIC_API(JSBool) 1242 JS_SealObject(JSContext *cx, JSObject *obj, JSBool deep); 1243 1244 extern JS_PUBLIC_API(JSObject *) 1245 JS_ConstructObject(JSContext *cx, JSClass *clasp, JSObject *proto, 1246 JSObject *parent); 1247 1248 extern JS_PUBLIC_API(JSObject *) 1249 JS_ConstructObjectWithArguments(JSContext *cx, JSClass *clasp, JSObject *proto, 1250 JSObject *parent, uintN argc, jsval *argv); 1251 1252 extern JS_PUBLIC_API(JSObject *) 1253 JS_DefineObject(JSContext *cx, JSObject *obj, const char *name, JSClass *clasp, 1254 JSObject *proto, uintN attrs); 1255 1256 extern JS_PUBLIC_API(JSBool) 1257 JS_DefineConstDoubles(JSContext *cx, JSObject *obj, JSConstDoubleSpec *cds); 1258 1259 extern JS_PUBLIC_API(JSBool) 1260 JS_DefineProperties(JSContext *cx, JSObject *obj, JSPropertySpec *ps); 1261 1262 extern JS_PUBLIC_API(JSBool) 1263 JS_DefineProperty(JSContext *cx, JSObject *obj, const char *name, jsval value, 1264 JSPropertyOp getter, JSPropertyOp setter, uintN attrs); 1265 1266 /* 1267 * Determine the attributes (JSPROP_* flags) of a property on a given object. 1268 * 1269 * If the object does not have a property by that name, *foundp will be 1270 * JS_FALSE and the value of *attrsp is undefined. 1271 */ 1272 extern JS_PUBLIC_API(JSBool) 1273 JS_GetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name, 1274 uintN *attrsp, JSBool *foundp); 1275 1276 /* 1277 * The same, but if the property is native, return its getter and setter via 1278 * *getterp and *setterp, respectively (and only if the out parameter pointer 1279 * is not null). 1280 */ 1281 extern JS_PUBLIC_API(JSBool) 1282 JS_GetPropertyAttrsGetterAndSetter(JSContext *cx, JSObject *obj, 1283 const char *name, 1284 uintN *attrsp, JSBool *foundp, 1285 JSPropertyOp *getterp, 1286 JSPropertyOp *setterp); 1287 1288 /* 1289 * Set the attributes of a property on a given object. 1290 * 1291 * If the object does not have a property by that name, *foundp will be 1292 * JS_FALSE and nothing will be altered. 1293 */ 1294 extern JS_PUBLIC_API(JSBool) 1295 JS_SetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name, 1296 uintN attrs, JSBool *foundp); 1297 1298 extern JS_PUBLIC_API(JSBool) 1299 JS_DefinePropertyWithTinyId(JSContext *cx, JSObject *obj, const char *name, 1300 int8 tinyid, jsval value, 1301 JSPropertyOp getter, JSPropertyOp setter, 1302 uintN attrs); 1303 1304 extern JS_PUBLIC_API(JSBool) 1305 JS_AliasProperty(JSContext *cx, JSObject *obj, const char *name, 1306 const char *alias); 1307 1308 extern JS_PUBLIC_API(JSBool) 1309 JS_HasProperty(JSContext *cx, JSObject *obj, const char *name, JSBool *foundp); 1310 1311 extern JS_PUBLIC_API(JSBool) 1312 JS_LookupProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp); 1313 1314 extern JS_PUBLIC_API(JSBool) 1315 JS_LookupPropertyWithFlags(JSContext *cx, JSObject *obj, const char *name, 1316 uintN flags, jsval *vp); 1317 1318 extern JS_PUBLIC_API(JSBool) 1319 JS_GetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp); 1320 1321 extern JS_PUBLIC_API(JSBool) 1322 JS_GetMethodById(JSContext *cx, JSObject *obj, jsid id, JSObject **objp, 1323 jsval *vp); 1324 1325 extern JS_PUBLIC_API(JSBool) 1326 JS_GetMethod(JSContext *cx, JSObject *obj, const char *name, JSObject **objp, 1327 jsval *vp); 1328 1329 extern JS_PUBLIC_API(JSBool) 1330 JS_SetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp); 1331 1332 extern JS_PUBLIC_API(JSBool) 1333 JS_DeleteProperty(JSContext *cx, JSObject *obj, const char *name); 1334 1335 extern JS_PUBLIC_API(JSBool) 1336 JS_DeleteProperty2(JSContext *cx, JSObject *obj, const char *name, 1337 jsval *rval); 1338 1339 extern JS_PUBLIC_API(JSBool) 1340 JS_DefineUCProperty(JSContext *cx, JSObject *obj, 1341 const jschar *name, size_t namelen, jsval value, 1342 JSPropertyOp getter, JSPropertyOp setter, 1343 uintN attrs); 1344 1345 /* 1346 * Determine the attributes (JSPROP_* flags) of a property on a given object. 1347 * 1348 * If the object does not have a property by that name, *foundp will be 1349 * JS_FALSE and the value of *attrsp is undefined. 1350 */ 1351 extern JS_PUBLIC_API(JSBool) 1352 JS_GetUCPropertyAttributes(JSContext *cx, JSObject *obj, 1353 const jschar *name, size_t namelen, 1354 uintN *attrsp, JSBool *foundp); 1355 1356 /* 1357 * The same, but if the property is native, return its getter and setter via 1358 * *getterp and *setterp, respectively (and only if the out parameter pointer 1359 * is not null). 1360 */ 1361 extern JS_PUBLIC_API(JSBool) 1362 JS_GetUCPropertyAttrsGetterAndSetter(JSContext *cx, JSObject *obj, 1363 const jschar *name, size_t namelen, 1364 uintN *attrsp, JSBool *foundp, 1365 JSPropertyOp *getterp, 1366 JSPropertyOp *setterp); 1367 1368 /* 1369 * Set the attributes of a property on a given object. 1370 * 1371 * If the object does not have a property by that name, *foundp will be 1372 * JS_FALSE and nothing will be altered. 1373 */ 1374 extern JS_PUBLIC_API(JSBool) 1375 JS_SetUCPropertyAttributes(JSContext *cx, JSObject *obj, 1376 const jschar *name, size_t namelen, 1377 uintN attrs, JSBool *foundp); 1378 1379 1380 extern JS_PUBLIC_API(JSBool) 1381 JS_DefineUCPropertyWithTinyId(JSContext *cx, JSObject *obj, 1382 const jschar *name, size_t namelen, 1383 int8 tinyid, jsval value, 1384 JSPropertyOp getter, JSPropertyOp setter, 1385 uintN attrs); 1386 1387 extern JS_PUBLIC_API(JSBool) 1388 JS_HasUCProperty(JSContext *cx, JSObject *obj, 1389 const jschar *name, size_t namelen, 1390 JSBool *vp); 1391 1392 extern JS_PUBLIC_API(JSBool) 1393 JS_LookupUCProperty(JSContext *cx, JSObject *obj, 1394 const jschar *name, size_t namelen, 1395 jsval *vp); 1396 1397 extern JS_PUBLIC_API(JSBool) 1398 JS_GetUCProperty(JSContext *cx, JSObject *obj, 1399 const jschar *name, size_t namelen, 1400 jsval *vp); 1401 1402 extern JS_PUBLIC_API(JSBool) 1403 JS_SetUCProperty(JSContext *cx, JSObject *obj, 1404 const jschar *name, size_t namelen, 1405 jsval *vp); 1406 1407 extern JS_PUBLIC_API(JSBool) 1408 JS_DeleteUCProperty2(JSContext *cx, JSObject *obj, 1409 const jschar *name, size_t namelen, 1410 jsval *rval); 1411 1412 extern JS_PUBLIC_API(JSObject *) 1413 JS_NewArrayObject(JSContext *cx, jsint length, jsval *vector); 1414 1415 extern JS_PUBLIC_API(JSBool) 1416 JS_IsArrayObject(JSContext *cx, JSObject *obj); 1417 1418 extern JS_PUBLIC_API(JSBool) 1419 JS_GetArrayLength(JSContext *cx, JSObject *obj, jsuint *lengthp); 1420 1421 extern JS_PUBLIC_API(JSBool) 1422 JS_SetArrayLength(JSContext *cx, JSObject *obj, jsuint length); 1423 1424 extern JS_PUBLIC_API(JSBool) 1425 JS_HasArrayLength(JSContext *cx, JSObject *obj, jsuint *lengthp); 1426 1427 extern JS_PUBLIC_API(JSBool) 1428 JS_DefineElement(JSContext *cx, JSObject *obj, jsint index, jsval value, 1429 JSPropertyOp getter, JSPropertyOp setter, uintN attrs); 1430 1431 extern JS_PUBLIC_API(JSBool) 1432 JS_AliasElement(JSContext *cx, JSObject *obj, const char *name, jsint alias); 1433 1434 extern JS_PUBLIC_API(JSBool) 1435 JS_HasElement(JSContext *cx, JSObject *obj, jsint index, JSBool *foundp); 1436 1437 extern JS_PUBLIC_API(JSBool) 1438 JS_LookupElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp); 1439 1440 extern JS_PUBLIC_API(JSBool) 1441 JS_GetElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp); 1442 1443 extern JS_PUBLIC_API(JSBool) 1444 JS_SetElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp); 1445 1446 extern JS_PUBLIC_API(JSBool) 1447 JS_DeleteElement(JSContext *cx, JSObject *obj, jsint index); 1448 1449 extern JS_PUBLIC_API(JSBool) 1450 JS_DeleteElement2(JSContext *cx, JSObject *obj, jsint index, jsval *rval); 1451 1452 extern JS_PUBLIC_API(void) 1453 JS_ClearScope(JSContext *cx, JSObject *obj); 1454 1455 extern JS_PUBLIC_API(JSIdArray *) 1456 JS_Enumerate(JSContext *cx, JSObject *obj); 1457 1458 /* 1459 * Create an object to iterate over enumerable properties of obj, in arbitrary 1460 * property definition order. NB: This differs from longstanding for..in loop 1461 * order, which uses order of property definition in obj. 1462 */ 1463 extern JS_PUBLIC_API(JSObject *) 1464 JS_NewPropertyIterator(JSContext *cx, JSObject *obj); 1465 1466 /* 1467 * Return true on success with *idp containing the id of the next enumerable 1468 * property to visit using iterobj, or JSVAL_VOID if there is no such property 1469 * left to visit. Return false on error. 1470 */ 1471 extern JS_PUBLIC_API(JSBool) 1472 JS_NextProperty(JSContext *cx, JSObject *iterobj, jsid *idp); 1473 1474 extern JS_PUBLIC_API(JSBool) 1475 JS_CheckAccess(JSContext *cx, JSObject *obj, jsid id, JSAccessMode mode, 1476 jsval *vp, uintN *attrsp); 1477 1478 extern JS_PUBLIC_API(JSCheckAccessOp) 1479 JS_SetCheckObjectAccessCallback(JSRuntime *rt, JSCheckAccessOp acb); 1480 1481 extern JS_PUBLIC_API(JSBool) 1482 JS_GetReservedSlot(JSContext *cx, JSObject *obj, uint32 index, jsval *vp); 1483 1484 extern JS_PUBLIC_API(JSBool) 1485 JS_SetReservedSlot(JSContext *cx, JSObject *obj, uint32 index, jsval v); 1486 1487 /************************************************************************/ 1488 1489 /* 1490 * Security protocol. 1491 */ 1492 struct JSPrincipals { 1493 char *codebase; 1494 1495 /* XXX unspecified and unused by Mozilla code -- can we remove these? */ 1496 void * (* JS_DLL_CALLBACK getPrincipalArray)(JSContext *cx, JSPrincipals *); 1497 JSBool (* JS_DLL_CALLBACK globalPrivilegesEnabled)(JSContext *cx, JSPrincipals *); 1498 1499 /* Don't call "destroy"; use reference counting macros below. */ 1500 jsrefcount refcount; 1501 1502 void (* JS_DLL_CALLBACK destroy)(JSContext *cx, JSPrincipals *); 1503 JSBool (* JS_DLL_CALLBACK subsume)(JSPrincipals *, JSPrincipals *); 1504 }; 1505 1506 #ifdef JS_THREADSAFE 1507 #define JSPRINCIPALS_HOLD(cx, principals) JS_HoldPrincipals(cx,principals) 1508 #define JSPRINCIPALS_DROP(cx, principals) JS_DropPrincipals(cx,principals) 1509 1510 extern JS_PUBLIC_API(jsrefcount) 1511 JS_HoldPrincipals(JSContext *cx, JSPrincipals *principals); 1512 1513 extern JS_PUBLIC_API(jsrefcount) 1514 JS_DropPrincipals(JSContext *cx, JSPrincipals *principals); 1515 1516 #else 1517 #define JSPRINCIPALS_HOLD(cx, principals) (++(principals)->refcount) 1518 #define JSPRINCIPALS_DROP(cx, principals) \ 1519 ((--(principals)->refcount == 0) \ 1520 ? ((*(principals)->destroy)((cx), (principals)), 0) \ 1521 : (principals)->refcount) 1522 #endif 1523 1524 extern JS_PUBLIC_API(JSPrincipalsTranscoder) 1525 JS_SetPrincipalsTranscoder(JSRuntime *rt, JSPrincipalsTranscoder px); 1526 1527 extern JS_PUBLIC_API(JSObjectPrincipalsFinder) 1528 JS_SetObjectPrincipalsFinder(JSRuntime *rt, JSObjectPrincipalsFinder fop); 1529 1530 /************************************************************************/ 1531 1532 /* 1533 * Functions and scripts. 1534 */ 1535 extern JS_PUBLIC_API(JSFunction *) 1536 JS_NewFunction(JSContext *cx, JSNative call, uintN nargs, uintN flags, 1537 JSObject *parent, const char *name); 1538 1539 extern JS_PUBLIC_API(JSObject *) 1540 JS_GetFunctionObject(JSFunction *fun); 1541 1542 /* 1543 * Deprecated, useful only for diagnostics. Use JS_GetFunctionId instead for 1544 * anonymous vs. "anonymous" disambiguation and Unicode fidelity. 1545 */ 1546 extern JS_PUBLIC_API(const char *) 1547 JS_GetFunctionName(JSFunction *fun); 1548 1549 /* 1550 * Return the function's identifier as a JSString, or null if fun is unnamed. 1551 * The returned string lives as long as fun, so you don't need to root a saved 1552 * reference to it if fun is well-connected or rooted, and provided you bound 1553 * the use of the saved reference by fun's lifetime. 1554 * 1555 * Prefer JS_GetFunctionId over JS_GetFunctionName because it returns null for 1556 * truly anonymous functions, and because it doesn't chop to ISO-Latin-1 chars 1557 * from UTF-16-ish jschars. 1558 */ 1559 extern JS_PUBLIC_API(JSString *) 1560 JS_GetFunctionId(JSFunction *fun); 1561 1562 /* 1563 * Return JSFUN_* flags for fun. 1564 */ 1565 extern JS_PUBLIC_API(uintN) 1566 JS_GetFunctionFlags(JSFunction *fun); 1567 1568 /* 1569 * Return the arity (length) of fun. 1570 */ 1571 extern JS_PUBLIC_API(uint16) 1572 JS_GetFunctionArity(JSFunction *fun); 1573 1574 /* 1575 * Infallible predicate to test whether obj is a function object (faster than 1576 * comparing obj's class name to "Function", but equivalent unless someone has 1577 * overwritten the "Function" identifier with a different constructor and then 1578 * created instances using that constructor that might be passed in as obj). 1579 */ 1580 extern JS_PUBLIC_API(JSBool) 1581 JS_ObjectIsFunction(JSContext *cx, JSObject *obj); 1582 1583 extern JS_PUBLIC_API(JSBool) 1584 JS_DefineFunctions(JSContext *cx, JSObject *obj, JSFunctionSpec *fs); 1585 1586 extern JS_PUBLIC_API(JSFunction *) 1587 JS_DefineFunction(JSContext *cx, JSObject *obj, const char *name, JSNative call, 1588 uintN nargs, uintN attrs); 1589 1590 extern JS_PUBLIC_API(JSFunction *) 1591 JS_DefineUCFunction(JSContext *cx, JSObject *obj, 1592 const jschar *name, size_t namelen, JSNative call, 1593 uintN nargs, uintN attrs); 1594 1595 extern JS_PUBLIC_API(JSObject *) 1596 JS_CloneFunctionObject(JSContext *cx, JSObject *funobj, JSObject *parent); 1597 1598 /* 1599 * Given a buffer, return JS_FALSE if the buffer might become a valid 1600 * javascript statement with the addition of more lines. Otherwise return 1601 * JS_TRUE. The intent is to support interactive compilation - accumulate 1602 * lines in a buffer until JS_BufferIsCompilableUnit is true, then pass it to 1603 * the compiler. 1604 */ 1605 extern JS_PUBLIC_API(JSBool) 1606 JS_BufferIsCompilableUnit(JSContext *cx, JSObject *obj, 1607 const char *bytes, size_t length); 1608 1609 /* 1610 * The JSScript objects returned by the following functions refer to string and 1611 * other kinds of literals, including doubles and RegExp objects. These 1612 * literals are vulnerable to garbage collection; to root script objects and 1613 * prevent literals from being collected, create a rootable object using 1614 * JS_NewScriptObject, and root the resulting object using JS_Add[Named]Root. 1615 */ 1616 extern JS_PUBLIC_API(JSScript *) 1617 JS_CompileScript(JSContext *cx, JSObject *obj, 1618 const char *bytes, size_t length, 1619 const char *filename, uintN lineno); 1620 1621 extern JS_PUBLIC_API(JSScript *) 1622 JS_CompileScriptForPrincipals(JSContext *cx, JSObject *obj, 1623 JSPrincipals *principals, 1624 const char *bytes, size_t length, 1625 const char *filename, uintN lineno); 1626 1627 extern JS_PUBLIC_API(JSScript *) 1628 JS_CompileUCScript(JSContext *cx, JSObject *obj, 1629 const jschar *chars, size_t length, 1630 const char *filename, uintN lineno); 1631 1632 extern JS_PUBLIC_API(JSScript *) 1633 JS_CompileUCScriptForPrincipals(JSContext *cx, JSObject *obj, 1634 JSPrincipals *principals, 1635 const jschar *chars, size_t length, 1636 const char *filename, uintN lineno); 1637 1638 extern JS_PUBLIC_API(JSScript *) 1639 JS_CompileFile(JSContext *cx, JSObject *obj, const char *filename); 1640 1641 extern JS_PUBLIC_API(JSScript *) 1642 JS_CompileFileHandle(JSContext *cx, JSObject *obj, const char *filename, 1643 FILE *fh); 1644 1645 extern JS_PUBLIC_API(JSScript *) 1646 JS_CompileFileHandleForPrincipals(JSContext *cx, JSObject *obj, 1647 const char *filename, FILE *fh, 1648 JSPrincipals *principals); 1649 1650 /* 1651 * NB: you must use JS_NewScriptObject and root a pointer to its return value 1652 * in order to keep a JSScript and its atoms safe from garbage collection after 1653 * creating the script via JS_Compile* and before a JS_ExecuteScript* call. 1654 * E.g., and without error checks: 1655 * 1656 * JSScript *script = JS_CompileFile(cx, global, filename); 1657 * JSObject *scrobj = JS_NewScriptObject(cx, script); 1658 * JS_AddNamedRoot(cx, &scrobj, "scrobj"); 1659 * do { 1660 * jsval result; 1661 * JS_ExecuteScript(cx, global, script, &result); 1662 * JS_GC(); 1663 * } while (!JSVAL_IS_BOOLEAN(result) || JSVAL_TO_BOOLEAN(result)); 1664 * JS_RemoveRoot(cx, &scrobj); 1665 */ 1666 extern JS_PUBLIC_API(JSObject *) 1667 JS_NewScriptObject(JSContext *cx, JSScript *script); 1668 1669 /* 1670 * Infallible getter for a script's object. If JS_NewScriptObject has not been 1671 * called on script yet, the return value will be null. 1672 */ 1673 extern JS_PUBLIC_API(JSObject *) 1674 JS_GetScriptObject(JSScript *script); 1675 1676 extern JS_PUBLIC_API(void) 1677 JS_DestroyScript(JSContext *cx, JSScript *script); 1678 1679 extern JS_PUBLIC_API(JSFunction *) 1680 JS_CompileFunction(JSContext *cx, JSObject *obj, const char *name, 1681 uintN nargs, const char **argnames, 1682 const char *bytes, size_t length, 1683 const char *filename, uintN lineno); 1684 1685 extern JS_PUBLIC_API(JSFunction *) 1686 JS_CompileFunctionForPrincipals(JSContext *cx, JSObject *obj, 1687 JSPrincipals *principals, const char *name, 1688 uintN nargs, const char **argnames, 1689 const char *bytes, size_t length, 1690 const char *filename, uintN lineno); 1691 1692 extern JS_PUBLIC_API(JSFunction *) 1693 JS_CompileUCFunction(JSContext *cx, JSObject *obj, const char *name, 1694 uintN nargs, const char **argnames, 1695 const jschar *chars, size_t length, 1696 const char *filename, uintN lineno); 1697 1698 extern JS_PUBLIC_API(JSFunction *) 1699 JS_CompileUCFunctionForPrincipals(JSContext *cx, JSObject *obj, 1700 JSPrincipals *principals, const char *name, 1701 uintN nargs, const char **argnames, 1702 const jschar *chars, size_t length, 1703 const char *filename, uintN lineno); 1704 1705 extern JS_PUBLIC_API(JSString *) 1706 JS_DecompileScript(JSContext *cx, JSScript *script, const char *name, 1707 uintN indent); 1708 1709 /* 1710 * API extension: OR this into indent to avoid pretty-printing the decompiled 1711 * source resulting from JS_DecompileFunction{,Body}. 1712 */ 1713 #define JS_DONT_PRETTY_PRINT ((uintN)0x8000) 1714 1715 extern JS_PUBLIC_API(JSString *) 1716 JS_DecompileFunction(JSContext *cx, JSFunction *fun, uintN indent); 1717 1718 extern JS_PUBLIC_API(JSString *) 1719 JS_DecompileFunctionBody(JSContext *cx, JSFunction *fun, uintN indent); 1720 1721 /* 1722 * NB: JS_ExecuteScript, JS_ExecuteScriptPart, and the JS_Evaluate*Script* 1723 * quadruplets all use the obj parameter as the initial scope chain header, 1724 * the 'this' keyword value, and the variables object (ECMA parlance for where 1725 * 'var' and 'function' bind names) of the execution context for script. 1726 * 1727 * Using obj as the variables object is problematic if obj's parent (which is 1728 * the scope chain link; see JS_SetParent and JS_NewObject) is not null: in 1729 * this case, variables created by 'var x = 0', e.g., go in obj, but variables 1730 * created by assignment to an unbound id, 'x = 0', go in the last object on 1731 * the scope chain linked by parent. 1732 * 1733 * ECMA calls that last scoping object the "global object", but note that many 1734 * embeddings have several such objects. ECMA requires that "global code" be 1735 * executed with the variables object equal to this global object. But these 1736 * JS API entry points provide freedom to execute code against a "sub-global", 1737 * i.e., a parented or scoped object, in which case the variables object will 1738 * differ from the last object on the scope chain, resulting in confusing and 1739 * non-ECMA explicit vs. implicit variable creation. 1740 * 1741 * Caveat embedders: unless you already depend on this buggy variables object 1742 * binding behavior, you should call JS_SetOptions(cx, JSOPTION_VAROBJFIX) or 1743 * JS_SetOptions(cx, JS_GetOptions(cx) | JSOPTION_VAROBJFIX) -- the latter if 1744 * someone may have set other options on cx already -- for each context in the 1745 * application, if you pass parented objects as the obj parameter, or may ever 1746 * pass such objects in the future. 1747 * 1748 * Why a runtime option? The alternative is to add six or so new API entry 1749 * points with signatures matching the following six, and that doesn't seem 1750 * worth the code bloat cost. Such new entry points would probably have less 1751 * obvious names, too, so would not tend to be used. The JS_SetOption call, 1752 * OTOH, can be more easily hacked into existing code that does not depend on 1753 * the bug; such code can continue to use the familiar JS_EvaluateScript, 1754 * etc., entry points. 1755 */ 1756 extern JS_PUBLIC_API(JSBool) 1757 JS_ExecuteScript(JSContext *cx, JSObject *obj, JSScript *script, jsval *rval); 1758 1759 /* 1760 * Execute either the function-defining prolog of a script, or the script's 1761 * main body, but not both. 1762 */ 1763 typedef enum JSExecPart { JSEXEC_PROLOG, JSEXEC_MAIN } JSExecPart; 1764 1765 extern JS_PUBLIC_API(JSBool) 1766 JS_ExecuteScriptPart(JSContext *cx, JSObject *obj, JSScript *script, 1767 JSExecPart part, jsval *rval); 1768 1769 extern JS_PUBLIC_API(JSBool) 1770 JS_EvaluateScript(JSContext *cx, JSObject *obj, 1771 const char *bytes, uintN length, 1772 const char *filename, uintN lineno, 1773 jsval *rval); 1774 1775 extern JS_PUBLIC_API(JSBool) 1776 JS_EvaluateScriptForPrincipals(JSContext *cx, JSObject *obj, 1777 JSPrincipals *principals, 1778 const char *bytes, uintN length, 1779 const char *filename, uintN lineno, 1780 jsval *rval); 1781 1782 extern JS_PUBLIC_API(JSBool) 1783 JS_EvaluateUCScript(JSContext *cx, JSObject *obj, 1784 const jschar *chars, uintN length, 1785 const char *filename, uintN lineno, 1786 jsval *rval); 1787 1788 extern JS_PUBLIC_API(JSBool) 1789 JS_EvaluateUCScriptForPrincipals(JSContext *cx, JSObject *obj, 1790 JSPrincipals *principals, 1791 const jschar *chars, uintN length, 1792 const char *filename, uintN lineno, 1793 jsval *rval); 1794 1795 extern JS_PUBLIC_API(JSBool) 1796 JS_CallFunction(JSContext *cx, JSObject *obj, JSFunction *fun, uintN argc, 1797 jsval *argv, jsval *rval); 1798 1799 extern JS_PUBLIC_API(JSBool) 1800 JS_CallFunctionName(JSContext *cx, JSObject *obj, const char *name, uintN argc, 1801 jsval *argv, jsval *rval); 1802 1803 extern JS_PUBLIC_API(JSBool) 1804 JS_CallFunctionValue(JSContext *cx, JSObject *obj, jsval fval, uintN argc, 1805 jsval *argv, jsval *rval); 1806 1807 extern JS_PUBLIC_API(JSBranchCallback) 1808 JS_SetBranchCallback(JSContext *cx, JSBranchCallback cb); 1809 1810 extern JS_PUBLIC_API(JSBool) 1811 JS_IsRunning(JSContext *cx); 1812 1813 extern JS_PUBLIC_API(JSBool) 1814 JS_IsConstructing(JSContext *cx); 1815 1816 /* 1817 * Returns true if a script is executing and its current bytecode is a set 1818 * (assignment) operation, even if there are native (no script) stack frames 1819 * between the script and the caller to JS_IsAssigning. 1820 */ 1821 extern JS_FRIEND_API(JSBool) 1822 JS_IsAssigning(JSContext *cx); 1823 1824 /* 1825 * Set the second return value, which should be a string or int jsval that 1826 * identifies a property in the returned object, to form an ECMA reference 1827 * type value (obj, id). Only native methods can return reference types, 1828 * and if the returned value is used on the left-hand side of an assignment 1829 * op, the identified property will be set. If the return value is in an 1830 * r-value, the interpreter just gets obj[id]'s value. 1831 */ 1832 extern JS_PUBLIC_API(void) 1833 JS_SetCallReturnValue2(JSContext *cx, jsval v); 1834 1835 /* 1836 * Saving and restoring frame chains. 1837 * 1838 * These two functions are used to set aside cx->fp while that frame is 1839 * inactive. After a call to JS_SaveFrameChain, it looks as if there is no 1840 * code running on cx. Before calling JS_RestoreFrameChain, cx's call stack 1841 * must be balanced and all nested calls to JS_SaveFrameChain must have had 1842 * matching JS_RestoreFrameChain calls. 1843 * 1844 * JS_SaveFrameChain deals with cx not having any code running on it. A null 1845 * return does not signify an error and JS_RestoreFrameChain handles null 1846 * frames. 1847 */ 1848 extern JS_PUBLIC_API(JSStackFrame *) 1849 JS_SaveFrameChain(JSContext *cx); 1850 1851 extern JS_PUBLIC_API(void) 1852 JS_RestoreFrameChain(JSContext *cx, JSStackFrame *fp); 1853 1854 /************************************************************************/ 1855 1856 /* 1857 * Strings. 1858 * 1859 * NB: JS_NewString takes ownership of bytes on success, avoiding a copy; but 1860 * on error (signified by null return), it leaves bytes owned by the caller. 1861 * So the caller must free bytes in the error case, if it has no use for them. 1862 * In contrast, all the JS_New*StringCopy* functions do not take ownership of 1863 * the character memory passed to them -- they copy it. 1864 */ 1865 extern JS_PUBLIC_API(JSString *) 1866 JS_NewString(JSContext *cx, char *bytes, size_t length); 1867 1868 extern JS_PUBLIC_API(JSString *) 1869 JS_NewStringCopyN(JSContext *cx, const char *s, size_t n); 1870 1871 extern JS_PUBLIC_API(JSString *) 1872 JS_NewStringCopyZ(JSContext *cx, const char *s); 1873 1874 extern JS_PUBLIC_API(JSString *) 1875 JS_InternString(JSContext *cx, const char *s); 1876 1877 extern JS_PUBLIC_API(JSString *) 1878 JS_NewUCString(JSContext *cx, jschar *chars, size_t length); 1879 1880 extern JS_PUBLIC_API(JSString *) 1881 JS_NewUCStringCopyN(JSContext *cx, const jschar *s, size_t n); 1882 1883 extern JS_PUBLIC_API(JSString *) 1884 JS_NewUCStringCopyZ(JSContext *cx, const jschar *s); 1885 1886 extern JS_PUBLIC_API(JSString *) 1887 JS_InternUCStringN(JSContext *cx, const jschar *s, size_t length); 1888 1889 extern JS_PUBLIC_API(JSString *) 1890 JS_InternUCString(JSContext *cx, const jschar *s); 1891 1892 extern JS_PUBLIC_API(char *) 1893 JS_GetStringBytes(JSString *str); 1894 1895 extern JS_PUBLIC_API(jschar *) 1896 JS_GetStringChars(JSString *str); 1897 1898 extern JS_PUBLIC_API(size_t) 1899 JS_GetStringLength(JSString *str); 1900 1901 extern JS_PUBLIC_API(intN) 1902 JS_CompareStrings(JSString *str1, JSString *str2); 1903 1904 /* 1905 * Mutable string support. A string's characters are never mutable in this JS 1906 * implementation, but a growable string has a buffer that can be reallocated, 1907 * and a dependent string is a substring of another (growable, dependent, or 1908 * immutable) string. The direct data members of the (opaque to API clients) 1909 * JSString struct may be changed in a single-threaded way for growable and 1910 * dependent strings. 1911 * 1912 * Therefore mutable strings cannot be used by more than one thread at a time. 1913 * You may call JS_MakeStringImmutable to convert the string from a mutable 1914 * (growable or dependent) string to an immutable (and therefore thread-safe) 1915 * string. The engine takes care of converting growable and dependent strings 1916 * to immutable for you if you store strings in multi-threaded objects using 1917 * JS_SetProperty or kindred API entry points. 1918 * 1919 * If you store a JSString pointer in a native data structure that is (safely) 1920 * accessible to multiple threads, you must call JS_MakeStringImmutable before 1921 * retiring the store. 1922 */ 1923 extern JS_PUBLIC_API(JSString *) 1924 JS_NewGrowableString(JSContext *cx, jschar *chars, size_t length); 1925 1926 /* 1927 * Create a dependent string, i.e., a string that owns no character storage, 1928 * but that refers to a slice of another string's chars. Dependent strings 1929 * are mutable by definition, so the thread safety comments above apply. 1930 */ 1931 extern JS_PUBLIC_API(JSString *) 1932 JS_NewDependentString(JSContext *cx, JSString *str, size_t start, 1933 size_t length); 1934 1935 /* 1936 * Concatenate two strings, resulting in a new growable string. If you create 1937 * the left string and pass it to JS_ConcatStrings on a single thread, try to 1938 * use JS_NewGrowableString to create the left string -- doing so helps Concat 1939 * avoid allocating a new buffer for the result and copying left's chars into 1940 * the new buffer. See above for thread safety comments. 1941 */ 1942 extern JS_PUBLIC_API(JSString *) 1943 JS_ConcatStrings(JSContext *cx, JSString *left, JSString *right); 1944 1945 /* 1946 * Convert a dependent string into an independent one. This function does not 1947 * change the string's mutability, so the thread safety comments above apply. 1948 */ 1949 extern JS_PUBLIC_API(const jschar *) 1950 JS_UndependString(JSContext *cx, JSString *str); 1951 1952 /* 1953 * Convert a mutable string (either growable or dependent) into an immutable, 1954 * thread-safe one. 1955 */ 1956 extern JS_PUBLIC_API(JSBool) 1957 JS_MakeStringImmutable(JSContext *cx, JSString *str); 1958 1959 /* 1960 * Return JS_TRUE if C (char []) strings passed via the API and internally 1961 * are UTF-8. The source must be compiled with JS_C_STRINGS_ARE_UTF8 defined 1962 * to get UTF-8 support. 1963 */ 1964 JS_PUBLIC_API(JSBool) 1965 JS_CStringsAreUTF8(); 1966 1967 /* 1968 * Character encoding support. 1969 * 1970 * For both JS_EncodeCharacters and JS_DecodeBytes, set *dstlenp to the size 1971 * of the destination buffer before the call; on return, *dstlenp contains the 1972 * number of bytes (JS_EncodeCharacters) or jschars (JS_DecodeBytes) actually 1973 * stored. To determine the necessary destination buffer size, make a sizing 1974 * call that passes NULL for dst. 1975 * 1976 * On errors, the functions report the error. In that case, *dstlenp contains 1977 * the number of characters or bytes transferred so far. If cx is NULL, no 1978 * error is reported on failure, and the functions simply return JS_FALSE. 1979 * 1980 * NB: Neither function stores an additional zero byte or jschar after the 1981 * transcoded string. 1982 * 1983 * If the source has been compiled with the #define JS_C_STRINGS_ARE_UTF8 to 1984 * enable UTF-8 interpretation of C char[] strings, then JS_EncodeCharacters 1985 * encodes to UTF-8, and JS_DecodeBytes decodes from UTF-8, which may create 1986 * addititional errors if the character sequence is malformed. If UTF-8 1987 * support is disabled, the functions deflate and inflate, respectively. 1988 */ 1989 JS_PUBLIC_API(JSBool) 1990 JS_EncodeCharacters(JSContext *cx, const jschar *src, size_t srclen, char *dst, 1991 size_t *dstlenp); 1992 1993 JS_PUBLIC_API(JSBool) 1994 JS_DecodeBytes(JSContext *cx, const char *src, size_t srclen, jschar *dst, 1995 size_t *dstlenp); 1996 1997 /************************************************************************/ 1998 1999 /* 2000 * Locale specific string conversion and error message callbacks. 2001 */ 2002 struct JSLocaleCallbacks { 2003 JSLocaleToUpperCase localeToUpperCase; 2004 JSLocaleToLowerCase localeToLowerCase; 2005 JSLocaleCompare localeCompare; 2006 JSLocaleToUnicode localeToUnicode; 2007 JSErrorCallback localeGetErrorMessage; 2008 }; 2009 2010 /* 2011 * Establish locale callbacks. The pointer must persist as long as the 2012 * JSContext. Passing NULL restores the default behaviour. 2013 */ 2014 extern JS_PUBLIC_API(void) 2015 JS_SetLocaleCallbacks(JSContext *cx, JSLocaleCallbacks *callbacks); 2016 2017 /* 2018 * Return the address of the current locale callbacks struct, which may 2019 * be NULL. 2020 */ 2021 extern JS_PUBLIC_API(JSLocaleCallbacks *) 2022 JS_GetLocaleCallbacks(JSContext *cx); 2023 2024 /************************************************************************/ 2025 2026 /* 2027 * Error reporting. 2028 */ 2029 2030 /* 2031 * Report an exception represented by the sprintf-like conversion of format 2032 * and its arguments. This exception message string is passed to a pre-set 2033 * JSErrorReporter function (set by JS_SetErrorReporter; see jspubtd.h for 2034 * the JSErrorReporter typedef). 2035 */ 2036 extern JS_PUBLIC_API(void) 2037 JS_ReportError(JSContext *cx, const char *format, ...); 2038 2039 /* 2040 * Use an errorNumber to retrieve the format string, args are char * 2041 */ 2042 extern JS_PUBLIC_API(void) 2043 JS_ReportErrorNumber(JSContext *cx, JSErrorCallback errorCallback, 2044 void *userRef, const uintN errorNumber, ...); 2045 2046 /* 2047 * Use an errorNumber to retrieve the format string, args are jschar * 2048 */ 2049 extern JS_PUBLIC_API(void) 2050 JS_ReportErrorNumberUC(JSContext *cx, JSErrorCallback errorCallback, 2051 void *userRef, const uintN errorNumber, ...); 2052 2053 /* 2054 * As above, but report a warning instead (JSREPORT_IS_WARNING(report.flags)). 2055 * Return true if there was no error trying to issue the warning, and if the 2056 * warning was not converted into an error due to the JSOPTION_WERROR option 2057 * being set, false otherwise. 2058 */ 2059 extern JS_PUBLIC_API(JSBool) 2060 JS_ReportWarning(JSContext *cx, const char *format, ...); 2061 2062 extern JS_PUBLIC_API(JSBool) 2063 JS_ReportErrorFlagsAndNumber(JSContext *cx, uintN flags, 2064 JSErrorCallback errorCallback, void *userRef, 2065 const uintN errorNumber, ...); 2066 2067 extern JS_PUBLIC_API(JSBool) 2068 JS_ReportErrorFlagsAndNumberUC(JSContext *cx, uintN flags, 2069 JSErrorCallback errorCallback, void *userRef, 2070 const uintN errorNumber, ...); 2071 2072 /* 2073 * Complain when out of memory. 2074 */ 2075 extern JS_PUBLIC_API(void) 2076 JS_ReportOutOfMemory(JSContext *cx); 2077 2078 struct JSErrorReport { 2079 const char *filename; /* source file name, URL, etc., or null */ 2080 uintN lineno; /* source line number */ 2081 const char *linebuf; /* offending source line without final \n */ 2082 const char *tokenptr; /* pointer to error token in linebuf */ 2083 const jschar *uclinebuf; /* unicode (original) line buffer */ 2084 const jschar *uctokenptr; /* unicode (original) token pointer */ 2085 uintN flags; /* error/warning, etc. */ 2086 uintN errorNumber; /* the error number, e.g. see js.msg */ 2087 const jschar *ucmessage; /* the (default) error message */ 2088 const jschar **messageArgs; /* arguments for the error message */ 2089 }; 2090 2091 /* 2092 * JSErrorReport flag values. These may be freely composed. 2093 */ 2094 #define JSREPORT_ERROR 0x0 /* pseudo-flag for default case */ 2095 #define JSREPORT_WARNING 0x1 /* reported via JS_ReportWarning */ 2096 #define JSREPORT_EXCEPTION 0x2 /* exception was thrown */ 2097 #define JSREPORT_STRICT 0x4 /* error or warning due to strict option */ 2098 2099 /* 2100 * If JSREPORT_EXCEPTION is set, then a JavaScript-catchable exception 2101 * has been thrown for this runtime error, and the host should ignore it. 2102 * Exception-aware hosts should also check for JS_IsExceptionPending if 2103 * JS_ExecuteScript returns failure, and signal or propagate the exception, as 2104 * appropriate. 2105 */ 2106 #define JSREPORT_IS_WARNING(flags) (((flags) & JSREPORT_WARNING) != 0) 2107 #define JSREPORT_IS_EXCEPTION(flags) (((flags) & JSREPORT_EXCEPTION) != 0) 2108 #define JSREPORT_IS_STRICT(flags) (((flags) & JSREPORT_STRICT) != 0) 2109 2110 extern JS_PUBLIC_API(JSErrorReporter) 2111 JS_SetErrorReporter(JSContext *cx, JSErrorReporter er); 2112 2113 /************************************************************************/ 2114 2115 /* 2116 * Regular Expressions. 2117 */ 2118 #define JSREG_FOLD 0x01 /* fold uppercase to lowercase */ 2119 #define JSREG_GLOB 0x02 /* global exec, creates array of matches */ 2120 #define JSREG_MULTILINE 0x04 /* treat ^ and $ as begin and end of line */ 2121 2122 extern JS_PUBLIC_API(JSObject *) 2123 JS_NewRegExpObject(JSContext *cx, char *bytes, size_t length, uintN flags); 2124 2125 extern JS_PUBLIC_API(JSObject *) 2126 JS_NewUCRegExpObject(JSContext *cx, jschar *chars, size_t length, uintN flags); 2127 2128 extern JS_PUBLIC_API(void) 2129 JS_SetRegExpInput(JSContext *cx, JSString *input, JSBool multiline); 2130 2131 extern JS_PUBLIC_API(void) 2132 JS_ClearRegExpStatics(JSContext *cx); 2133 2134 extern JS_PUBLIC_API(void) 2135 JS_ClearRegExpRoots(JSContext *cx); 2136 2137 /* TODO: compile, exec, get/set other statics... */ 2138 2139 /************************************************************************/ 2140 2141 extern JS_PUBLIC_API(JSBool) 2142 JS_IsExceptionPending(JSContext *cx); 2143 2144 extern JS_PUBLIC_API(JSBool) 2145 JS_GetPendingException(JSContext *cx, jsval *vp); 2146 2147 extern JS_PUBLIC_API(void) 2148 JS_SetPendingException(JSContext *cx, jsval v); 2149 2150 extern JS_PUBLIC_API(void) 2151 JS_ClearPendingException(JSContext *cx); 2152 2153 extern JS_PUBLIC_API(JSBool) 2154 JS_ReportPendingException(JSContext *cx); 2155 2156 /* 2157 * Save the current exception state. This takes a snapshot of cx's current 2158 * exception state without making any change to that state. 2159 * 2160 * The returned state pointer MUST be passed later to JS_RestoreExceptionState 2161 * (to restore that saved state, overriding any more recent state) or else to 2162 * JS_DropExceptionState (to free the state struct in case it is not correct 2163 * or desirable to restore it). Both Restore and Drop free the state struct, 2164 * so callers must stop using the pointer returned from Save after calling the 2165 * Release or Drop API. 2166 */ 2167 extern JS_PUBLIC_API(JSExceptionState *) 2168 JS_SaveExceptionState(JSContext *cx); 2169 2170 extern JS_PUBLIC_API(void) 2171 JS_RestoreExceptionState(JSContext *cx, JSExceptionState *state); 2172 2173 extern JS_PUBLIC_API(void) 2174 JS_DropExceptionState(JSContext *cx, JSExceptionState *state); 2175 2176 /* 2177 * If the given value is an exception object that originated from an error, 2178 * the exception will contain an error report struct, and this API will return 2179 * the address of that struct. Otherwise, it returns NULL. The lifetime of 2180 * the error report struct that might be returned is the same as the lifetime 2181 * of the exception object. 2182 */ 2183 extern JS_PUBLIC_API(JSErrorReport *) 2184 JS_ErrorFromException(JSContext *cx, jsval v); 2185 2186 /* 2187 * Given a reported error's message and JSErrorReport struct pointer, throw 2188 * the corresponding exception on cx. 2189 */ 2190 extern JS_PUBLIC_API(JSBool) 2191 JS_ThrowReportedError(JSContext *cx, const char *message, 2192 JSErrorReport *reportp); 2193 2194 #ifdef JS_THREADSAFE 2195 2196 /* 2197 * Associate the current thread with the given context. This is done 2198 * implicitly by JS_NewContext. 2199 * 2200 * Returns the old thread id for this context, which should be treated as 2201 * an opaque value. This value is provided for comparison to 0, which 2202 * indicates that ClearContextThread has been called on this context 2203 * since the last SetContextThread, or non-0, which indicates the opposite. 2204 */ 2205 extern JS_PUBLIC_API(jsword) 2206 JS_GetContextThread(JSContext *cx); 2207 2208 extern JS_PUBLIC_API(jsword) 2209 JS_SetContextThread(JSContext *cx); 2210 2211 extern JS_PUBLIC_API(jsword) 2212 JS_ClearContextThread(JSContext *cx); 2213 2214 #endif /* JS_THREADSAFE */ 2215 2216 /************************************************************************/ 2217 2218 JS_END_EXTERN_C 2219 2220 #endif /* jsapi_h___ */ 2221