Back to index

lightning-sunbird  0.9+nobinonly
jsapi.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
00002  *
00003  * ***** BEGIN LICENSE BLOCK *****
00004  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00005  *
00006  * The contents of this file are subject to the Mozilla Public License Version
00007  * 1.1 (the "License"); you may not use this file except in compliance with
00008  * the License. You may obtain a copy of the License at
00009  * http://www.mozilla.org/MPL/
00010  *
00011  * Software distributed under the License is distributed on an "AS IS" basis,
00012  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00013  * for the specific language governing rights and limitations under the
00014  * License.
00015  *
00016  * The Original Code is Mozilla Communicator client code, released
00017  * March 31, 1998.
00018  *
00019  * The Initial Developer of the Original Code is
00020  * Netscape Communications Corporation.
00021  * Portions created by the Initial Developer are Copyright (C) 1998
00022  * the Initial Developer. All Rights Reserved.
00023  *
00024  * Contributor(s):
00025  *
00026  * Alternatively, the contents of this file may be used under the terms of
00027  * either of the GNU General Public License Version 2 or later (the "GPL"),
00028  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00029  * in which case the provisions of the GPL or the LGPL are applicable instead
00030  * of those above. If you wish to allow use of your version of this file only
00031  * under the terms of either the GPL or the LGPL, and not to allow others to
00032  * use your version of this file under the terms of the MPL, indicate your
00033  * decision by deleting the provisions above and replace them with the notice
00034  * and other provisions required by the GPL or the LGPL. If you do not delete
00035  * the provisions above, a recipient may use your version of this file under
00036  * the terms of any one of the MPL, the GPL or the LGPL.
00037  *
00038  * ***** END LICENSE BLOCK ***** */
00039 
00040 #ifndef jsapi_h___
00041 #define jsapi_h___
00042 /*
00043  * JavaScript API.
00044  */
00045 #include <stddef.h>
00046 #include <stdio.h>
00047 #include "jspubtd.h"
00048 
00049 JS_BEGIN_EXTERN_C
00050 
00051 /*
00052  * Type tags stored in the low bits of a jsval.
00053  */
00054 #define JSVAL_OBJECT            0x0     /* untagged reference to object */
00055 #define JSVAL_INT               0x1     /* tagged 31-bit integer value */
00056 #define JSVAL_DOUBLE            0x2     /* tagged reference to double */
00057 #define JSVAL_STRING            0x4     /* tagged reference to string */
00058 #define JSVAL_BOOLEAN           0x6     /* tagged boolean value */
00059 
00060 /* Type tag bitfield length and derived macros. */
00061 #define JSVAL_TAGBITS           3
00062 #define JSVAL_TAGMASK           JS_BITMASK(JSVAL_TAGBITS)
00063 #define JSVAL_TAG(v)            ((v) & JSVAL_TAGMASK)
00064 #define JSVAL_SETTAG(v,t)       ((v) | (t))
00065 #define JSVAL_CLRTAG(v)         ((v) & ~(jsval)JSVAL_TAGMASK)
00066 #define JSVAL_ALIGN             JS_BIT(JSVAL_TAGBITS)
00067 
00068 /* Predicates for type testing. */
00069 #define JSVAL_IS_OBJECT(v)      (JSVAL_TAG(v) == JSVAL_OBJECT)
00070 #define JSVAL_IS_NUMBER(v)      (JSVAL_IS_INT(v) || JSVAL_IS_DOUBLE(v))
00071 #define JSVAL_IS_INT(v)         (((v) & JSVAL_INT) && (v) != JSVAL_VOID)
00072 #define JSVAL_IS_DOUBLE(v)      (JSVAL_TAG(v) == JSVAL_DOUBLE)
00073 #define JSVAL_IS_STRING(v)      (JSVAL_TAG(v) == JSVAL_STRING)
00074 #define JSVAL_IS_BOOLEAN(v)     (JSVAL_TAG(v) == JSVAL_BOOLEAN)
00075 #define JSVAL_IS_NULL(v)        ((v) == JSVAL_NULL)
00076 #define JSVAL_IS_VOID(v)        ((v) == JSVAL_VOID)
00077 #define JSVAL_IS_PRIMITIVE(v)   (!JSVAL_IS_OBJECT(v) || JSVAL_IS_NULL(v))
00078 
00079 /* Objects, strings, and doubles are GC'ed. */
00080 #define JSVAL_IS_GCTHING(v)     (!((v) & JSVAL_INT) && !JSVAL_IS_BOOLEAN(v))
00081 #define JSVAL_TO_GCTHING(v)     ((void *)JSVAL_CLRTAG(v))
00082 #define JSVAL_TO_OBJECT(v)      ((JSObject *)JSVAL_TO_GCTHING(v))
00083 #define JSVAL_TO_DOUBLE(v)      ((jsdouble *)JSVAL_TO_GCTHING(v))
00084 #define JSVAL_TO_STRING(v)      ((JSString *)JSVAL_TO_GCTHING(v))
00085 #define OBJECT_TO_JSVAL(obj)    ((jsval)(obj))
00086 #define DOUBLE_TO_JSVAL(dp)     JSVAL_SETTAG((jsval)(dp), JSVAL_DOUBLE)
00087 #define STRING_TO_JSVAL(str)    JSVAL_SETTAG((jsval)(str), JSVAL_STRING)
00088 
00089 /* Lock and unlock the GC thing held by a jsval. */
00090 #define JSVAL_LOCK(cx,v)        (JSVAL_IS_GCTHING(v)                          \
00091                                  ? JS_LockGCThing(cx, JSVAL_TO_GCTHING(v))    \
00092                                  : JS_TRUE)
00093 #define JSVAL_UNLOCK(cx,v)      (JSVAL_IS_GCTHING(v)                          \
00094                                  ? JS_UnlockGCThing(cx, JSVAL_TO_GCTHING(v))  \
00095                                  : JS_TRUE)
00096 
00097 /* Domain limits for the jsval int type. */
00098 #define JSVAL_INT_BITS          31
00099 #define JSVAL_INT_POW2(n)       ((jsval)1 << (n))
00100 #define JSVAL_INT_MIN           ((jsval)1 - JSVAL_INT_POW2(30))
00101 #define JSVAL_INT_MAX           (JSVAL_INT_POW2(30) - 1)
00102 #define INT_FITS_IN_JSVAL(i)    ((jsuint)((i)+JSVAL_INT_MAX) <= 2*JSVAL_INT_MAX)
00103 #define JSVAL_TO_INT(v)         ((jsint)(v) >> 1)
00104 #define INT_TO_JSVAL(i)         (((jsval)(i) << 1) | JSVAL_INT)
00105 
00106 /* Convert between boolean and jsval. */
00107 #define JSVAL_TO_BOOLEAN(v)     ((JSBool)((v) >> JSVAL_TAGBITS))
00108 #define BOOLEAN_TO_JSVAL(b)     JSVAL_SETTAG((jsval)(b) << JSVAL_TAGBITS,     \
00109                                              JSVAL_BOOLEAN)
00110 
00111 /* A private data pointer (2-byte-aligned) can be stored as an int jsval. */
00112 #define JSVAL_TO_PRIVATE(v)     ((void *)((v) & ~JSVAL_INT))
00113 #define PRIVATE_TO_JSVAL(p)     ((jsval)(p) | JSVAL_INT)
00114 
00115 /* Property attributes, set in JSPropertySpec and passed to API functions. */
00116 #define JSPROP_ENUMERATE        0x01    /* property is visible to for/in loop */
00117 #define JSPROP_READONLY         0x02    /* not settable: assignment is no-op */
00118 #define JSPROP_PERMANENT        0x04    /* property cannot be deleted */
00119 #define JSPROP_EXPORTED         0x08    /* property is exported from object */
00120 #define JSPROP_GETTER           0x10    /* property holds getter function */
00121 #define JSPROP_SETTER           0x20    /* property holds setter function */
00122 #define JSPROP_SHARED           0x40    /* don't allocate a value slot for this
00123                                            property; don't copy the property on
00124                                            set of the same-named property in an
00125                                            object that delegates to a prototype
00126                                            containing this property */
00127 #define JSPROP_INDEX            0x80    /* name is actually (jsint) index */
00128 
00129 /* Function flags, set in JSFunctionSpec and passed to JS_NewFunction etc. */
00130 #define JSFUN_LAMBDA            0x08    /* expressed, not declared, function */
00131 #define JSFUN_GETTER            JSPROP_GETTER
00132 #define JSFUN_SETTER            JSPROP_SETTER
00133 #define JSFUN_BOUND_METHOD      0x40    /* bind this to fun->object's parent */
00134 #define JSFUN_HEAVYWEIGHT       0x80    /* activation requires a Call object */
00135 
00136 #define JSFUN_DISJOINT_FLAGS(f) ((f) & 0x0f)
00137 #define JSFUN_GSFLAGS(f)        ((f) & (JSFUN_GETTER | JSFUN_SETTER))
00138 
00139 #ifdef MOZILLA_1_8_BRANCH
00140 
00141 /*
00142  * Squeeze three more bits into existing 8-bit flags by taking advantage of
00143  * the invalid combination (JSFUN_GETTER | JSFUN_SETTER).
00144  */
00145 #define JSFUN_GETTER_TEST(f)       (JSFUN_GSFLAGS(f) == JSFUN_GETTER)
00146 #define JSFUN_SETTER_TEST(f)       (JSFUN_GSFLAGS(f) == JSFUN_SETTER)
00147 #define JSFUN_FLAGS_TEST(f,t)      (JSFUN_GSFLAGS(~(f)) ? (f) & (t) : 0)
00148 #define JSFUN_BOUND_METHOD_TEST(f) JSFUN_FLAGS_TEST(f, JSFUN_BOUND_METHOD)
00149 #define JSFUN_HEAVYWEIGHT_TEST(f)  JSFUN_FLAGS_TEST(f, JSFUN_HEAVYWEIGHT)
00150 
00151 #define JSFUN_GSFLAG2ATTR(f)       (JSFUN_GETTER_TEST(f) ? JSPROP_GETTER :    \
00152                                     JSFUN_SETTER_TEST(f) ? JSPROP_SETTER : 0)
00153 
00154 #define JSFUN_THISP_FLAGS(f)    (JSFUN_GSFLAGS(~(f)) ? 0 :                    \
00155                                  (f) & JSFUN_THISP_PRIMITIVE)
00156 #define JSFUN_THISP_TEST(f,t)   ((f) == (t) || (f) == JSFUN_THISP_PRIMITIVE)
00157 
00158 #define JSFUN_THISP_STRING      0x30    /* |this| may be a primitive string */
00159 #define JSFUN_THISP_NUMBER      0x70    /* |this| may be a primitive number */
00160 #define JSFUN_THISP_BOOLEAN     0xb0    /* |this| may be a primitive boolean */
00161 #define JSFUN_THISP_PRIMITIVE   0xf0    /* |this| may be any primitive value */
00162 
00163 #define JSFUN_FLAGS_MASK        0xf8    /* overlay JSFUN_* attributes */
00164 
00165 #else
00166 
00167 #define JSFUN_GETTER_TEST(f)       ((f) & JSFUN_GETTER)
00168 #define JSFUN_SETTER_TEST(f)       ((f) & JSFUN_SETTER)
00169 #define JSFUN_BOUND_METHOD_TEST(f) ((f) & JSFUN_BOUND_METHOD)
00170 #define JSFUN_HEAVYWEIGHT_TEST(f)  ((f) & JSFUN_HEAVYWEIGHT)
00171 
00172 #define JSFUN_GSFLAG2ATTR(f)       JSFUN_GSFLAGS(f)
00173 
00174 #define JSFUN_THISP_FLAGS(f)  (f)
00175 #define JSFUN_THISP_TEST(f,t) ((f) & t)
00176 
00177 #define JSFUN_THISP_STRING    0x0100    /* |this| may be a primitive string */
00178 #define JSFUN_THISP_NUMBER    0x0200    /* |this| may be a primitive number */
00179 #define JSFUN_THISP_BOOLEAN   0x0400    /* |this| may be a primitive boolean */
00180 #define JSFUN_THISP_PRIMITIVE 0x0700    /* |this| may be any primitive value */
00181 
00182 #define JSFUN_FLAGS_MASK      0x07f8    /* overlay JSFUN_* attributes --
00183                                            note that bit #15 is used internally
00184                                            to flag interpreted functions */
00185 
00186 #endif
00187 
00188 /*
00189  * Re-use JSFUN_LAMBDA, which applies only to scripted functions, for use in
00190  * JSFunctionSpec arrays that specify generic native prototype methods, i.e.,
00191  * methods of a class prototype that are exposed as static methods taking an
00192  * extra leading argument: the generic |this| parameter.
00193  *
00194  * If you set this flag in a JSFunctionSpec struct's flags initializer, then
00195  * that struct must live at least as long as the native static method object
00196  * created due to this flag by JS_DefineFunctions or JS_InitClass.  Typically
00197  * JSFunctionSpec structs are allocated in static arrays.
00198  */
00199 #define JSFUN_GENERIC_NATIVE    JSFUN_LAMBDA
00200 
00201 /*
00202  * Well-known JS values.  The extern'd variables are initialized when the
00203  * first JSContext is created by JS_NewContext (see below).
00204  */
00205 #define JSVAL_VOID              INT_TO_JSVAL(0 - JSVAL_INT_POW2(30))
00206 #define JSVAL_NULL              OBJECT_TO_JSVAL(0)
00207 #define JSVAL_ZERO              INT_TO_JSVAL(0)
00208 #define JSVAL_ONE               INT_TO_JSVAL(1)
00209 #define JSVAL_FALSE             BOOLEAN_TO_JSVAL(JS_FALSE)
00210 #define JSVAL_TRUE              BOOLEAN_TO_JSVAL(JS_TRUE)
00211 
00212 /*
00213  * Microseconds since the epoch, midnight, January 1, 1970 UTC.  See the
00214  * comment in jstypes.h regarding safe int64 usage.
00215  */
00216 extern JS_PUBLIC_API(int64)
00217 JS_Now();
00218 
00219 /* Don't want to export data, so provide accessors for non-inline jsvals. */
00220 extern JS_PUBLIC_API(jsval)
00221 JS_GetNaNValue(JSContext *cx);
00222 
00223 extern JS_PUBLIC_API(jsval)
00224 JS_GetNegativeInfinityValue(JSContext *cx);
00225 
00226 extern JS_PUBLIC_API(jsval)
00227 JS_GetPositiveInfinityValue(JSContext *cx);
00228 
00229 extern JS_PUBLIC_API(jsval)
00230 JS_GetEmptyStringValue(JSContext *cx);
00231 
00232 /*
00233  * Format is a string of the following characters (spaces are insignificant),
00234  * specifying the tabulated type conversions:
00235  *
00236  *   b      JSBool          Boolean
00237  *   c      uint16/jschar   ECMA uint16, Unicode char
00238  *   i      int32           ECMA int32
00239  *   u      uint32          ECMA uint32
00240  *   j      int32           Rounded int32 (coordinate)
00241  *   d      jsdouble        IEEE double
00242  *   I      jsdouble        Integral IEEE double
00243  *   s      char *          C string
00244  *   S      JSString *      Unicode string, accessed by a JSString pointer
00245  *   W      jschar *        Unicode character vector, 0-terminated (W for wide)
00246  *   o      JSObject *      Object reference
00247  *   f      JSFunction *    Function private
00248  *   v      jsval           Argument value (no conversion)
00249  *   *      N/A             Skip this argument (no vararg)
00250  *   /      N/A             End of required arguments
00251  *
00252  * The variable argument list after format must consist of &b, &c, &s, e.g.,
00253  * where those variables have the types given above.  For the pointer types
00254  * char *, JSString *, and JSObject *, the pointed-at memory returned belongs
00255  * to the JS runtime, not to the calling native code.  The runtime promises
00256  * to keep this memory valid so long as argv refers to allocated stack space
00257  * (so long as the native function is active).
00258  *
00259  * Fewer arguments than format specifies may be passed only if there is a /
00260  * in format after the last required argument specifier and argc is at least
00261  * the number of required arguments.  More arguments than format specifies
00262  * may be passed without error; it is up to the caller to deal with trailing
00263  * unconverted arguments.
00264  */
00265 extern JS_PUBLIC_API(JSBool)
00266 JS_ConvertArguments(JSContext *cx, uintN argc, jsval *argv, const char *format,
00267                     ...);
00268 
00269 #ifdef va_start
00270 extern JS_PUBLIC_API(JSBool)
00271 JS_ConvertArgumentsVA(JSContext *cx, uintN argc, jsval *argv,
00272                       const char *format, va_list ap);
00273 #endif
00274 
00275 /*
00276  * Inverse of JS_ConvertArguments: scan format and convert trailing arguments
00277  * into jsvals, GC-rooted if necessary by the JS stack.  Return null on error,
00278  * and a pointer to the new argument vector on success.  Also return a stack
00279  * mark on success via *markp, in which case the caller must eventually clean
00280  * up by calling JS_PopArguments.
00281  *
00282  * Note that the number of actual arguments supplied is specified exclusively
00283  * by format, so there is no argc parameter.
00284  */
00285 extern JS_PUBLIC_API(jsval *)
00286 JS_PushArguments(JSContext *cx, void **markp, const char *format, ...);
00287 
00288 #ifdef va_start
00289 extern JS_PUBLIC_API(jsval *)
00290 JS_PushArgumentsVA(JSContext *cx, void **markp, const char *format, va_list ap);
00291 #endif
00292 
00293 extern JS_PUBLIC_API(void)
00294 JS_PopArguments(JSContext *cx, void *mark);
00295 
00296 #ifdef JS_ARGUMENT_FORMATTER_DEFINED
00297 
00298 /*
00299  * Add and remove a format string handler for JS_{Convert,Push}Arguments{,VA}.
00300  * The handler function has this signature (see jspubtd.h):
00301  *
00302  *   JSBool MyArgumentFormatter(JSContext *cx, const char *format,
00303  *                              JSBool fromJS, jsval **vpp, va_list *app);
00304  *
00305  * It should return true on success, and return false after reporting an error
00306  * or detecting an already-reported error.
00307  *
00308  * For a given format string, for example "AA", the formatter is called from
00309  * JS_ConvertArgumentsVA like so:
00310  *
00311  *   formatter(cx, "AA...", JS_TRUE, &sp, &ap);
00312  *
00313  * sp points into the arguments array on the JS stack, while ap points into
00314  * the stdarg.h va_list on the C stack.  The JS_TRUE passed for fromJS tells
00315  * the formatter to convert zero or more jsvals at sp to zero or more C values
00316  * accessed via pointers-to-values at ap, updating both sp (via *vpp) and ap
00317  * (via *app) to point past the converted arguments and their result pointers
00318  * on the C stack.
00319  *
00320  * When called from JS_PushArgumentsVA, the formatter is invoked thus:
00321  *
00322  *   formatter(cx, "AA...", JS_FALSE, &sp, &ap);
00323  *
00324  * where JS_FALSE for fromJS means to wrap the C values at ap according to the
00325  * format specifier and store them at sp, updating ap and sp appropriately.
00326  *
00327  * The "..." after "AA" is the rest of the format string that was passed into
00328  * JS_{Convert,Push}Arguments{,VA}.  The actual format trailing substring used
00329  * in each Convert or PushArguments call is passed to the formatter, so that
00330  * one such function may implement several formats, in order to share code.
00331  *
00332  * Remove just forgets about any handler associated with format.  Add does not
00333  * copy format, it points at the string storage allocated by the caller, which
00334  * is typically a string constant.  If format is in dynamic storage, it is up
00335  * to the caller to keep the string alive until Remove is called.
00336  */
00337 extern JS_PUBLIC_API(JSBool)
00338 JS_AddArgumentFormatter(JSContext *cx, const char *format,
00339                         JSArgumentFormatter formatter);
00340 
00341 extern JS_PUBLIC_API(void)
00342 JS_RemoveArgumentFormatter(JSContext *cx, const char *format);
00343 
00344 #endif /* JS_ARGUMENT_FORMATTER_DEFINED */
00345 
00346 extern JS_PUBLIC_API(JSBool)
00347 JS_ConvertValue(JSContext *cx, jsval v, JSType type, jsval *vp);
00348 
00349 extern JS_PUBLIC_API(JSBool)
00350 JS_ValueToObject(JSContext *cx, jsval v, JSObject **objp);
00351 
00352 extern JS_PUBLIC_API(JSFunction *)
00353 JS_ValueToFunction(JSContext *cx, jsval v);
00354 
00355 extern JS_PUBLIC_API(JSFunction *)
00356 JS_ValueToConstructor(JSContext *cx, jsval v);
00357 
00358 extern JS_PUBLIC_API(JSString *)
00359 JS_ValueToString(JSContext *cx, jsval v);
00360 
00361 extern JS_PUBLIC_API(JSBool)
00362 JS_ValueToNumber(JSContext *cx, jsval v, jsdouble *dp);
00363 
00364 /*
00365  * Convert a value to a number, then to an int32, according to the ECMA rules
00366  * for ToInt32.
00367  */
00368 extern JS_PUBLIC_API(JSBool)
00369 JS_ValueToECMAInt32(JSContext *cx, jsval v, int32 *ip);
00370 
00371 /*
00372  * Convert a value to a number, then to a uint32, according to the ECMA rules
00373  * for ToUint32.
00374  */
00375 extern JS_PUBLIC_API(JSBool)
00376 JS_ValueToECMAUint32(JSContext *cx, jsval v, uint32 *ip);
00377 
00378 /*
00379  * Convert a value to a number, then to an int32 if it fits by rounding to
00380  * nearest; but failing with an error report if the double is out of range
00381  * or unordered.
00382  */
00383 extern JS_PUBLIC_API(JSBool)
00384 JS_ValueToInt32(JSContext *cx, jsval v, int32 *ip);
00385 
00386 /*
00387  * ECMA ToUint16, for mapping a jsval to a Unicode point.
00388  */
00389 extern JS_PUBLIC_API(JSBool)
00390 JS_ValueToUint16(JSContext *cx, jsval v, uint16 *ip);
00391 
00392 extern JS_PUBLIC_API(JSBool)
00393 JS_ValueToBoolean(JSContext *cx, jsval v, JSBool *bp);
00394 
00395 extern JS_PUBLIC_API(JSType)
00396 JS_TypeOfValue(JSContext *cx, jsval v);
00397 
00398 extern JS_PUBLIC_API(const char *)
00399 JS_GetTypeName(JSContext *cx, JSType type);
00400 
00401 /************************************************************************/
00402 
00403 /*
00404  * Initialization, locking, contexts, and memory allocation.
00405  */
00406 #define JS_NewRuntime       JS_Init
00407 #define JS_DestroyRuntime   JS_Finish
00408 #define JS_LockRuntime      JS_Lock
00409 #define JS_UnlockRuntime    JS_Unlock
00410 
00411 extern JS_PUBLIC_API(JSRuntime *)
00412 JS_NewRuntime(uint32 maxbytes);
00413 
00414 extern JS_PUBLIC_API(void)
00415 JS_DestroyRuntime(JSRuntime *rt);
00416 
00417 extern JS_PUBLIC_API(void)
00418 JS_ShutDown(void);
00419 
00420 JS_PUBLIC_API(void *)
00421 JS_GetRuntimePrivate(JSRuntime *rt);
00422 
00423 JS_PUBLIC_API(void)
00424 JS_SetRuntimePrivate(JSRuntime *rt, void *data);
00425 
00426 #ifdef JS_THREADSAFE
00427 
00428 extern JS_PUBLIC_API(void)
00429 JS_BeginRequest(JSContext *cx);
00430 
00431 extern JS_PUBLIC_API(void)
00432 JS_EndRequest(JSContext *cx);
00433 
00434 /* Yield to pending GC operations, regardless of request depth */
00435 extern JS_PUBLIC_API(void)
00436 JS_YieldRequest(JSContext *cx);
00437 
00438 extern JS_PUBLIC_API(jsrefcount)
00439 JS_SuspendRequest(JSContext *cx);
00440 
00441 extern JS_PUBLIC_API(void)
00442 JS_ResumeRequest(JSContext *cx, jsrefcount saveDepth);
00443 
00444 #ifdef __cplusplus
00445 JS_END_EXTERN_C
00446 
00447 class JSAutoRequest {
00448   public:
00449     JSAutoRequest(JSContext *cx) : mContext(cx), mSaveDepth(0) {
00450         JS_BeginRequest(mContext);
00451     }
00452     ~JSAutoRequest() {
00453         JS_EndRequest(mContext);
00454     }
00455 
00456     void suspend() {
00457         mSaveDepth = JS_SuspendRequest(mContext);
00458     }
00459     void resume() {
00460         JS_ResumeRequest(mContext, mSaveDepth);
00461     }
00462 
00463   protected:
00464     JSContext *mContext;
00465     jsrefcount mSaveDepth;
00466 
00467 #if 0
00468   private:
00469     static void *operator new(size_t) CPP_THROW_NEW { return 0; };
00470     static void operator delete(void *, size_t) { };
00471 #endif
00472 };
00473 
00474 JS_BEGIN_EXTERN_C
00475 #endif
00476 
00477 #endif /* JS_THREADSAFE */
00478 
00479 extern JS_PUBLIC_API(void)
00480 JS_Lock(JSRuntime *rt);
00481 
00482 extern JS_PUBLIC_API(void)
00483 JS_Unlock(JSRuntime *rt);
00484 
00485 extern JS_PUBLIC_API(JSContextCallback)
00486 JS_SetContextCallback(JSRuntime *rt, JSContextCallback cxCallback);
00487 
00488 extern JS_PUBLIC_API(JSContext *)
00489 JS_NewContext(JSRuntime *rt, size_t stackChunkSize);
00490 
00491 extern JS_PUBLIC_API(void)
00492 JS_DestroyContext(JSContext *cx);
00493 
00494 extern JS_PUBLIC_API(void)
00495 JS_DestroyContextNoGC(JSContext *cx);
00496 
00497 extern JS_PUBLIC_API(void)
00498 JS_DestroyContextMaybeGC(JSContext *cx);
00499 
00500 extern JS_PUBLIC_API(void *)
00501 JS_GetContextPrivate(JSContext *cx);
00502 
00503 extern JS_PUBLIC_API(void)
00504 JS_SetContextPrivate(JSContext *cx, void *data);
00505 
00506 extern JS_PUBLIC_API(JSRuntime *)
00507 JS_GetRuntime(JSContext *cx);
00508 
00509 extern JS_PUBLIC_API(JSContext *)
00510 JS_ContextIterator(JSRuntime *rt, JSContext **iterp);
00511 
00512 extern JS_PUBLIC_API(JSVersion)
00513 JS_GetVersion(JSContext *cx);
00514 
00515 extern JS_PUBLIC_API(JSVersion)
00516 JS_SetVersion(JSContext *cx, JSVersion version);
00517 
00518 extern JS_PUBLIC_API(const char *)
00519 JS_VersionToString(JSVersion version);
00520 
00521 extern JS_PUBLIC_API(JSVersion)
00522 JS_StringToVersion(const char *string);
00523 
00524 /*
00525  * JS options are orthogonal to version, and may be freely composed with one
00526  * another as well as with version.
00527  *
00528  * JSOPTION_VAROBJFIX is recommended -- see the comments associated with the
00529  * prototypes for JS_ExecuteScript, JS_EvaluateScript, etc.
00530  */
00531 #define JSOPTION_STRICT         JS_BIT(0)       /* warn on dubious practice */
00532 #define JSOPTION_WERROR         JS_BIT(1)       /* convert warning to error */
00533 #define JSOPTION_VAROBJFIX      JS_BIT(2)       /* make JS_EvaluateScript use
00534                                                    the last object on its 'obj'
00535                                                    param's scope chain as the
00536                                                    ECMA 'variables object' */
00537 #define JSOPTION_PRIVATE_IS_NSISUPPORTS \
00538                                 JS_BIT(3)       /* context private data points
00539                                                    to an nsISupports subclass */
00540 #define JSOPTION_COMPILE_N_GO   JS_BIT(4)       /* caller of JS_Compile*Script
00541                                                    promises to execute compiled
00542                                                    script once only; enables
00543                                                    compile-time scope chain
00544                                                    resolution of consts. */
00545 #define JSOPTION_ATLINE         JS_BIT(5)       /* //@line number ["filename"]
00546                                                    option supported for the
00547                                                    XUL preprocessor and kindred
00548                                                    beasts. */
00549 #define JSOPTION_XML            JS_BIT(6)       /* EMCAScript for XML support:
00550                                                    parse <!-- --> as a token,
00551                                                    not backward compatible with
00552                                                    the comment-hiding hack used
00553                                                    in HTML script tags. */
00554 #define JSOPTION_NATIVE_BRANCH_CALLBACK \
00555                                 JS_BIT(7)       /* the branch callback set by
00556                                                    JS_SetBranchCallback may be
00557                                                    called with a null script
00558                                                    parameter, by native code
00559                                                    that loops intensively */
00560 #define JSOPTION_DONT_REPORT_UNCAUGHT \
00561                                 JS_BIT(8)       /* When returning from the
00562                                                    outermost API call, prevent
00563                                                    uncaught exceptions from
00564                                                    being converted to error
00565                                                    reports */
00566 
00567 extern JS_PUBLIC_API(uint32)
00568 JS_GetOptions(JSContext *cx);
00569 
00570 extern JS_PUBLIC_API(uint32)
00571 JS_SetOptions(JSContext *cx, uint32 options);
00572 
00573 extern JS_PUBLIC_API(uint32)
00574 JS_ToggleOptions(JSContext *cx, uint32 options);
00575 
00576 extern JS_PUBLIC_API(const char *)
00577 JS_GetImplementationVersion(void);
00578 
00579 extern JS_PUBLIC_API(JSObject *)
00580 JS_GetGlobalObject(JSContext *cx);
00581 
00582 extern JS_PUBLIC_API(void)
00583 JS_SetGlobalObject(JSContext *cx, JSObject *obj);
00584 
00585 /*
00586  * Initialize standard JS class constructors, prototypes, and any top-level
00587  * functions and constants associated with the standard classes (e.g. isNaN
00588  * for Number).
00589  *
00590  * NB: This sets cx's global object to obj if it was null.
00591  */
00592 extern JS_PUBLIC_API(JSBool)
00593 JS_InitStandardClasses(JSContext *cx, JSObject *obj);
00594 
00595 /*
00596  * Resolve id, which must contain either a string or an int, to a standard
00597  * class name in obj if possible, defining the class's constructor and/or
00598  * prototype and storing true in *resolved.  If id does not name a standard
00599  * class or a top-level property induced by initializing a standard class,
00600  * store false in *resolved and just return true.  Return false on error,
00601  * as usual for JSBool result-typed API entry points.
00602  *
00603  * This API can be called directly from a global object class's resolve op,
00604  * to define standard classes lazily.  The class's enumerate op should call
00605  * JS_EnumerateStandardClasses(cx, obj), to define eagerly during for..in
00606  * loops any classes not yet resolved lazily.
00607  */
00608 extern JS_PUBLIC_API(JSBool)
00609 JS_ResolveStandardClass(JSContext *cx, JSObject *obj, jsval id,
00610                         JSBool *resolved);
00611 
00612 extern JS_PUBLIC_API(JSBool)
00613 JS_EnumerateStandardClasses(JSContext *cx, JSObject *obj);
00614 
00615 /*
00616  * Enumerate any already-resolved standard class ids into ida, or into a new
00617  * JSIdArray if ida is null.  Return the augmented array on success, null on
00618  * failure with ida (if it was non-null on entry) destroyed.
00619  */
00620 extern JS_PUBLIC_API(JSIdArray *)
00621 JS_EnumerateResolvedStandardClasses(JSContext *cx, JSObject *obj,
00622                                     JSIdArray *ida);
00623 
00624 extern JS_PUBLIC_API(JSBool)
00625 JS_GetClassObject(JSContext *cx, JSObject *obj, JSProtoKey key,
00626                   JSObject **objp);
00627 
00628 extern JS_PUBLIC_API(JSObject *)
00629 JS_GetScopeChain(JSContext *cx);
00630 
00631 extern JS_PUBLIC_API(void *)
00632 JS_malloc(JSContext *cx, size_t nbytes);
00633 
00634 extern JS_PUBLIC_API(void *)
00635 JS_realloc(JSContext *cx, void *p, size_t nbytes);
00636 
00637 extern JS_PUBLIC_API(void)
00638 JS_free(JSContext *cx, void *p);
00639 
00640 extern JS_PUBLIC_API(char *)
00641 JS_strdup(JSContext *cx, const char *s);
00642 
00643 extern JS_PUBLIC_API(jsdouble *)
00644 JS_NewDouble(JSContext *cx, jsdouble d);
00645 
00646 extern JS_PUBLIC_API(JSBool)
00647 JS_NewDoubleValue(JSContext *cx, jsdouble d, jsval *rval);
00648 
00649 extern JS_PUBLIC_API(JSBool)
00650 JS_NewNumberValue(JSContext *cx, jsdouble d, jsval *rval);
00651 
00652 /*
00653  * A JS GC root is a pointer to a JSObject *, JSString *, or jsdouble * that
00654  * itself points into the GC heap (more recently, we support this extension:
00655  * a root may be a pointer to a jsval v for which JSVAL_IS_GCTHING(v) is true).
00656  *
00657  * Therefore, you never pass JSObject *obj to JS_AddRoot(cx, obj).  You always
00658  * call JS_AddRoot(cx, &obj), passing obj by reference.  And later, before obj
00659  * or the structure it is embedded within goes out of scope or is freed, you
00660  * must call JS_RemoveRoot(cx, &obj).
00661  *
00662  * Also, use JS_AddNamedRoot(cx, &structPtr->memberObj, "structPtr->memberObj")
00663  * in preference to JS_AddRoot(cx, &structPtr->memberObj), in order to identify
00664  * roots by their source callsites.  This way, you can find the callsite while
00665  * debugging if you should fail to do JS_RemoveRoot(cx, &structPtr->memberObj)
00666  * before freeing structPtr's memory.
00667  */
00668 extern JS_PUBLIC_API(JSBool)
00669 JS_AddRoot(JSContext *cx, void *rp);
00670 
00671 #ifdef NAME_ALL_GC_ROOTS
00672 #define JS_DEFINE_TO_TOKEN(def) #def
00673 #define JS_DEFINE_TO_STRING(def) JS_DEFINE_TO_TOKEN(def)
00674 #define JS_AddRoot(cx,rp) JS_AddNamedRoot((cx), (rp), (__FILE__ ":" JS_TOKEN_TO_STRING(__LINE__))
00675 #endif
00676 
00677 extern JS_PUBLIC_API(JSBool)
00678 JS_AddNamedRoot(JSContext *cx, void *rp, const char *name);
00679 
00680 extern JS_PUBLIC_API(JSBool)
00681 JS_AddNamedRootRT(JSRuntime *rt, void *rp, const char *name);
00682 
00683 extern JS_PUBLIC_API(JSBool)
00684 JS_RemoveRoot(JSContext *cx, void *rp);
00685 
00686 extern JS_PUBLIC_API(JSBool)
00687 JS_RemoveRootRT(JSRuntime *rt, void *rp);
00688 
00689 /*
00690  * The last GC thing of each type (object, string, double, external string
00691  * types) created on a given context is kept alive until another thing of the
00692  * same type is created, using a newborn root in the context.  These newborn
00693  * roots help native code protect newly-created GC-things from GC invocations
00694  * activated before those things can be rooted using local or global roots.
00695  *
00696  * However, the newborn roots can also entrain great gobs of garbage, so the
00697  * JS_GC entry point clears them for the context on which GC is being forced.
00698  * Embeddings may need to do likewise for all contexts.
00699  *
00700  * See the scoped local root API immediately below for a better way to manage
00701  * newborns in cases where native hooks (functions, getters, setters, etc.)
00702  * create many GC-things, potentially without connecting them to predefined
00703  * local roots such as *rval or argv[i] in an active native function.  Using
00704  * JS_EnterLocalRootScope disables updating of the context's per-gc-thing-type
00705  * newborn roots, until control flow unwinds and leaves the outermost nesting
00706  * local root scope.
00707  */
00708 extern JS_PUBLIC_API(void)
00709 JS_ClearNewbornRoots(JSContext *cx);
00710 
00711 /*
00712  * Scoped local root management allows native functions, getter/setters, etc.
00713  * to avoid worrying about the newborn root pigeon-holes, overloading local
00714  * roots allocated in argv and *rval, or ending up having to call JS_Add*Root
00715  * and JS_RemoveRoot to manage global roots temporarily.
00716  *
00717  * Instead, calling JS_EnterLocalRootScope and JS_LeaveLocalRootScope around
00718  * the body of the native hook causes the engine to allocate a local root for
00719  * each newborn created in between the two API calls, using a local root stack
00720  * associated with cx.  For example:
00721  *
00722  *    JSBool
00723  *    my_GetProperty(JSContext *cx, JSObject *obj, jsval id, jsval *vp)
00724  *    {
00725  *        JSBool ok;
00726  *
00727  *        if (!JS_EnterLocalRootScope(cx))
00728  *            return JS_FALSE;
00729  *        ok = my_GetPropertyBody(cx, obj, id, vp);
00730  *        JS_LeaveLocalRootScope(cx);
00731  *        return ok;
00732  *    }
00733  *
00734  * NB: JS_LeaveLocalRootScope must be called once for every prior successful
00735  * call to JS_EnterLocalRootScope.  If JS_EnterLocalRootScope fails, you must
00736  * not make the matching JS_LeaveLocalRootScope call.
00737  *
00738  * JS_LeaveLocalRootScopeWithResult(cx, rval) is an alternative way to leave
00739  * a local root scope that protects a result or return value, by effectively
00740  * pushing it in the caller's local root scope.
00741  *
00742  * In case a native hook allocates many objects or other GC-things, but the
00743  * native protects some of those GC-things by storing them as property values
00744  * in an object that is itself protected, the hook can call JS_ForgetLocalRoot
00745  * to free the local root automatically pushed for the now-protected GC-thing.
00746  *
00747  * JS_ForgetLocalRoot works on any GC-thing allocated in the current local
00748  * root scope, but it's more time-efficient when called on references to more
00749  * recently created GC-things.  Calling it successively on other than the most
00750  * recently allocated GC-thing will tend to average the time inefficiency, and
00751  * may risk O(n^2) growth rate, but in any event, you shouldn't allocate too
00752  * many local roots if you can root as you go (build a tree of objects from
00753  * the top down, forgetting each latest-allocated GC-thing immediately upon
00754  * linking it to its parent).
00755  */
00756 extern JS_PUBLIC_API(JSBool)
00757 JS_EnterLocalRootScope(JSContext *cx);
00758 
00759 extern JS_PUBLIC_API(void)
00760 JS_LeaveLocalRootScope(JSContext *cx);
00761 
00762 extern JS_PUBLIC_API(void)
00763 JS_LeaveLocalRootScopeWithResult(JSContext *cx, jsval rval);
00764 
00765 extern JS_PUBLIC_API(void)
00766 JS_ForgetLocalRoot(JSContext *cx, void *thing);
00767 
00768 #ifdef __cplusplus
00769 JS_END_EXTERN_C
00770 
00771 class JSAutoLocalRootScope {
00772   public:
00773     JSAutoLocalRootScope(JSContext *cx) : mContext(cx) {
00774         JS_EnterLocalRootScope(mContext);
00775     }
00776     ~JSAutoLocalRootScope() {
00777         JS_LeaveLocalRootScope(mContext);
00778     }
00779 
00780     void forget(void *thing) {
00781         JS_ForgetLocalRoot(mContext, thing);
00782     }
00783 
00784   protected:
00785     JSContext *mContext;
00786 
00787 #if 0
00788   private:
00789     static void *operator new(size_t) CPP_THROW_NEW { return 0; };
00790     static void operator delete(void *, size_t) { };
00791 #endif
00792 };
00793 
00794 JS_BEGIN_EXTERN_C
00795 #endif
00796 
00797 #ifdef DEBUG
00798 extern JS_PUBLIC_API(void)
00799 JS_DumpNamedRoots(JSRuntime *rt,
00800                   void (*dump)(const char *name, void *rp, void *data),
00801                   void *data);
00802 #endif
00803 
00804 /*
00805  * Call JS_MapGCRoots to map the GC's roots table using map(rp, name, data).
00806  * The root is pointed at by rp; if the root is unnamed, name is null; data is
00807  * supplied from the third parameter to JS_MapGCRoots.
00808  *
00809  * The map function should return JS_MAP_GCROOT_REMOVE to cause the currently
00810  * enumerated root to be removed.  To stop enumeration, set JS_MAP_GCROOT_STOP
00811  * in the return value.  To keep on mapping, return JS_MAP_GCROOT_NEXT.  These
00812  * constants are flags; you can OR them together.
00813  *
00814  * This function acquires and releases rt's GC lock around the mapping of the
00815  * roots table, so the map function should run to completion in as few cycles
00816  * as possible.  Of course, map cannot call JS_GC, JS_MaybeGC, JS_BeginRequest,
00817  * or any JS API entry point that acquires locks, without double-tripping or
00818  * deadlocking on the GC lock.
00819  *
00820  * JS_MapGCRoots returns the count of roots that were successfully mapped.
00821  */
00822 #define JS_MAP_GCROOT_NEXT      0       /* continue mapping entries */
00823 #define JS_MAP_GCROOT_STOP      1       /* stop mapping entries */
00824 #define JS_MAP_GCROOT_REMOVE    2       /* remove and free the current entry */
00825 
00826 typedef intN
00827 (* JS_DLL_CALLBACK JSGCRootMapFun)(void *rp, const char *name, void *data);
00828 
00829 extern JS_PUBLIC_API(uint32)
00830 JS_MapGCRoots(JSRuntime *rt, JSGCRootMapFun map, void *data);
00831 
00832 extern JS_PUBLIC_API(JSBool)
00833 JS_LockGCThing(JSContext *cx, void *thing);
00834 
00835 extern JS_PUBLIC_API(JSBool)
00836 JS_LockGCThingRT(JSRuntime *rt, void *thing);
00837 
00838 extern JS_PUBLIC_API(JSBool)
00839 JS_UnlockGCThing(JSContext *cx, void *thing);
00840 
00841 extern JS_PUBLIC_API(JSBool)
00842 JS_UnlockGCThingRT(JSRuntime *rt, void *thing);
00843 
00844 /*
00845  * For implementors of JSObjectOps.mark, to mark a GC-thing reachable via a
00846  * property or other strong ref identified for debugging purposes by name.
00847  * The name argument's storage needs to live only as long as the call to
00848  * this routine.
00849  *
00850  * The final arg is used by GC_MARK_DEBUG code to build a ref path through
00851  * the GC's live thing graph.  Implementors of JSObjectOps.mark should pass
00852  * its final arg through to this function when marking all GC-things that are
00853  * directly reachable from the object being marked.
00854  *
00855  * See the JSMarkOp typedef in jspubtd.h, and the JSObjectOps struct below.
00856  */
00857 extern JS_PUBLIC_API(void)
00858 JS_MarkGCThing(JSContext *cx, void *thing, const char *name, void *arg);
00859 
00860 extern JS_PUBLIC_API(void)
00861 JS_GC(JSContext *cx);
00862 
00863 extern JS_PUBLIC_API(void)
00864 JS_MaybeGC(JSContext *cx);
00865 
00866 extern JS_PUBLIC_API(JSGCCallback)
00867 JS_SetGCCallback(JSContext *cx, JSGCCallback cb);
00868 
00869 extern JS_PUBLIC_API(JSGCCallback)
00870 JS_SetGCCallbackRT(JSRuntime *rt, JSGCCallback cb);
00871 
00872 extern JS_PUBLIC_API(JSBool)
00873 JS_IsAboutToBeFinalized(JSContext *cx, void *thing);
00874 
00875 typedef enum JSGCParamKey {
00876     JSGC_MAX_BYTES        = 0,  /* maximum nominal heap before last ditch GC */
00877     JSGC_MAX_MALLOC_BYTES = 1   /* # of JS_malloc bytes before last ditch GC */
00878 } JSGCParamKey;
00879 
00880 extern JS_PUBLIC_API(void)
00881 JS_SetGCParameter(JSRuntime *rt, JSGCParamKey key, uint32 value);
00882 
00883 /*
00884  * Add a finalizer for external strings created by JS_NewExternalString (see
00885  * below) using a type-code returned from this function, and that understands
00886  * how to free or release the memory pointed at by JS_GetStringChars(str).
00887  *
00888  * Return a nonnegative type index if there is room for finalizer in the
00889  * global GC finalizers table, else return -1.  If the engine is compiled
00890  * JS_THREADSAFE and used in a multi-threaded environment, this function must
00891  * be invoked on the primordial thread only, at startup -- or else the entire
00892  * program must single-thread itself while loading a module that calls this
00893  * function.
00894  */
00895 extern JS_PUBLIC_API(intN)
00896 JS_AddExternalStringFinalizer(JSStringFinalizeOp finalizer);
00897 
00898 /*
00899  * Remove finalizer from the global GC finalizers table, returning its type
00900  * code if found, -1 if not found.
00901  *
00902  * As with JS_AddExternalStringFinalizer, there is a threading restriction
00903  * if you compile the engine JS_THREADSAFE: this function may be called for a
00904  * given finalizer pointer on only one thread; different threads may call to
00905  * remove distinct finalizers safely.
00906  *
00907  * You must ensure that all strings with finalizer's type have been collected
00908  * before calling this function.  Otherwise, string data will be leaked by the
00909  * GC, for want of a finalizer to call.
00910  */
00911 extern JS_PUBLIC_API(intN)
00912 JS_RemoveExternalStringFinalizer(JSStringFinalizeOp finalizer);
00913 
00914 /*
00915  * Create a new JSString whose chars member refers to external memory, i.e.,
00916  * memory requiring special, type-specific finalization.  The type code must
00917  * be a nonnegative return value from JS_AddExternalStringFinalizer.
00918  */
00919 extern JS_PUBLIC_API(JSString *)
00920 JS_NewExternalString(JSContext *cx, jschar *chars, size_t length, intN type);
00921 
00922 /*
00923  * Returns the external-string finalizer index for this string, or -1 if it is
00924  * an "internal" (native to JS engine) string.
00925  */
00926 extern JS_PUBLIC_API(intN)
00927 JS_GetExternalStringGCType(JSRuntime *rt, JSString *str);
00928 
00929 /*
00930  * Sets maximum (if stack grows upward) or minimum (downward) legal stack byte
00931  * address in limitAddr for the thread or process stack used by cx.  To disable
00932  * stack size checking, pass 0 for limitAddr.
00933  */
00934 extern JS_PUBLIC_API(void)
00935 JS_SetThreadStackLimit(JSContext *cx, jsuword limitAddr);
00936 
00937 /************************************************************************/
00938 
00939 /*
00940  * Classes, objects, and properties.
00941  */
00942 
00943 /* For detailed comments on the function pointer types, see jspubtd.h. */
00944 struct JSClass {
00945     const char          *name;
00946     uint32              flags;
00947 
00948     /* Mandatory non-null function pointer members. */
00949     JSPropertyOp        addProperty;
00950     JSPropertyOp        delProperty;
00951     JSPropertyOp        getProperty;
00952     JSPropertyOp        setProperty;
00953     JSEnumerateOp       enumerate;
00954     JSResolveOp         resolve;
00955     JSConvertOp         convert;
00956     JSFinalizeOp        finalize;
00957 
00958     /* Optionally non-null members start here. */
00959     JSGetObjectOps      getObjectOps;
00960     JSCheckAccessOp     checkAccess;
00961     JSNative            call;
00962     JSNative            construct;
00963     JSXDRObjectOp       xdrObject;
00964     JSHasInstanceOp     hasInstance;
00965     JSMarkOp            mark;
00966     JSReserveSlotsOp    reserveSlots;
00967 };
00968 
00969 struct JSExtendedClass {
00970     JSClass             base;
00971     JSEqualityOp        equality;
00972     JSObjectOp          outerObject;
00973     JSObjectOp          innerObject;
00974     void                (*reserved0)();
00975     void                (*reserved1)();
00976     void                (*reserved2)();
00977     void                (*reserved3)();
00978     void                (*reserved4)();
00979 };
00980 
00981 #define JSCLASS_HAS_PRIVATE             (1<<0)  /* objects have private slot */
00982 #define JSCLASS_NEW_ENUMERATE           (1<<1)  /* has JSNewEnumerateOp hook */
00983 #define JSCLASS_NEW_RESOLVE             (1<<2)  /* has JSNewResolveOp hook */
00984 #define JSCLASS_PRIVATE_IS_NSISUPPORTS  (1<<3)  /* private is (nsISupports *) */
00985 #define JSCLASS_SHARE_ALL_PROPERTIES    (1<<4)  /* all properties are SHARED */
00986 #define JSCLASS_NEW_RESOLVE_GETS_START  (1<<5)  /* JSNewResolveOp gets starting
00987                                                    object in prototype chain
00988                                                    passed in via *objp in/out
00989                                                    parameter */
00990 #define JSCLASS_CONSTRUCT_PROTOTYPE     (1<<6)  /* call constructor on class
00991                                                    prototype */
00992 #define JSCLASS_DOCUMENT_OBSERVER       (1<<7)  /* DOM document observer */
00993 
00994 /*
00995  * To reserve slots fetched and stored via JS_Get/SetReservedSlot, bitwise-or
00996  * JSCLASS_HAS_RESERVED_SLOTS(n) into the initializer for JSClass.flags, where
00997  * n is a constant in [1, 255].  Reserved slots are indexed from 0 to n-1.
00998  */
00999 #define JSCLASS_RESERVED_SLOTS_SHIFT    8       /* room for 8 flags below */
01000 #define JSCLASS_RESERVED_SLOTS_WIDTH    8       /* and 16 above this field */
01001 #define JSCLASS_RESERVED_SLOTS_MASK     JS_BITMASK(JSCLASS_RESERVED_SLOTS_WIDTH)
01002 #define JSCLASS_HAS_RESERVED_SLOTS(n)   (((n) & JSCLASS_RESERVED_SLOTS_MASK)  \
01003                                          << JSCLASS_RESERVED_SLOTS_SHIFT)
01004 #define JSCLASS_RESERVED_SLOTS(clasp)   (((clasp)->flags                      \
01005                                           >> JSCLASS_RESERVED_SLOTS_SHIFT)    \
01006                                          & JSCLASS_RESERVED_SLOTS_MASK)
01007 
01008 #define JSCLASS_HIGH_FLAGS_SHIFT        (JSCLASS_RESERVED_SLOTS_SHIFT +       \
01009                                          JSCLASS_RESERVED_SLOTS_WIDTH)
01010 
01011 /* True if JSClass is really a JSExtendedClass. */
01012 #define JSCLASS_IS_EXTENDED             (1<<(JSCLASS_HIGH_FLAGS_SHIFT+0))
01013 #define JSCLASS_IS_ANONYMOUS            (1<<(JSCLASS_HIGH_FLAGS_SHIFT+1))
01014 #define JSCLASS_IS_GLOBAL               (1<<(JSCLASS_HIGH_FLAGS_SHIFT+2))
01015 
01016 /*
01017  * ECMA-262 requires that most constructors used internally create objects
01018  * with "the original Foo.prototype value" as their [[Prototype]] (__proto__)
01019  * member initial value.  The "original ... value" verbiage is there because
01020  * in ECMA-262, global properties naming class objects are read/write and
01021  * deleteable, for the most part.
01022  *
01023  * Implementing this efficiently requires that global objects have classes
01024  * with the following flags.  Failure to use JSCLASS_GLOBAL_FLAGS won't break
01025  * anything except the ECMA-262 "original prototype value" behavior, which was
01026  * broken for years in SpiderMonkey.  In other words, without these flags you
01027  * get backward compatibility.
01028  */
01029 #define JSCLASS_GLOBAL_FLAGS \
01030     (JSCLASS_IS_GLOBAL | JSCLASS_HAS_RESERVED_SLOTS(JSProto_LIMIT))
01031 
01032 /* Fast access to the original value of each standard class's prototype. */
01033 #define JSCLASS_CACHED_PROTO_SHIFT      (JSCLASS_HIGH_FLAGS_SHIFT + 8)
01034 #define JSCLASS_CACHED_PROTO_WIDTH      8
01035 #define JSCLASS_CACHED_PROTO_MASK       JS_BITMASK(JSCLASS_CACHED_PROTO_WIDTH)
01036 #define JSCLASS_HAS_CACHED_PROTO(key)   ((key) << JSCLASS_CACHED_PROTO_SHIFT)
01037 #define JSCLASS_CACHED_PROTO_KEY(clasp) (((clasp)->flags                      \
01038                                           >> JSCLASS_CACHED_PROTO_SHIFT)      \
01039                                          & JSCLASS_CACHED_PROTO_MASK)
01040 
01041 /* Initializer for unused members of statically initialized JSClass structs. */
01042 #define JSCLASS_NO_OPTIONAL_MEMBERS     0,0,0,0,0,0,0,0
01043 #define JSCLASS_NO_RESERVED_MEMBERS     0,0,0,0,0
01044 
01045 /* For detailed comments on these function pointer types, see jspubtd.h. */
01046 struct JSObjectOps {
01047     /* Mandatory non-null function pointer members. */
01048     JSNewObjectMapOp    newObjectMap;
01049     JSObjectMapOp       destroyObjectMap;
01050     JSLookupPropOp      lookupProperty;
01051     JSDefinePropOp      defineProperty;
01052     JSPropertyIdOp      getProperty;
01053     JSPropertyIdOp      setProperty;
01054     JSAttributesOp      getAttributes;
01055     JSAttributesOp      setAttributes;
01056     JSPropertyIdOp      deleteProperty;
01057     JSConvertOp         defaultValue;
01058     JSNewEnumerateOp    enumerate;
01059     JSCheckAccessIdOp   checkAccess;
01060 
01061     /* Optionally non-null members start here. */
01062     JSObjectOp          thisObject;
01063     JSPropertyRefOp     dropProperty;
01064     JSNative            call;
01065     JSNative            construct;
01066     JSXDRObjectOp       xdrObject;
01067     JSHasInstanceOp     hasInstance;
01068     JSSetObjectSlotOp   setProto;
01069     JSSetObjectSlotOp   setParent;
01070     JSMarkOp            mark;
01071     JSFinalizeOp        clear;
01072     JSGetRequiredSlotOp getRequiredSlot;
01073     JSSetRequiredSlotOp setRequiredSlot;
01074 };
01075 
01076 struct JSXMLObjectOps {
01077     JSObjectOps         base;
01078     JSGetMethodOp       getMethod;
01079     JSSetMethodOp       setMethod;
01080     JSEnumerateValuesOp enumerateValues;
01081     JSEqualityOp        equality;
01082     JSConcatenateOp     concatenate;
01083 };
01084 
01085 /*
01086  * Classes that expose JSObjectOps via a non-null getObjectOps class hook may
01087  * derive a property structure from this struct, return a pointer to it from
01088  * lookupProperty and defineProperty, and use the pointer to avoid rehashing
01089  * in getAttributes and setAttributes.
01090  *
01091  * The jsid type contains either an int jsval (see JSVAL_IS_INT above), or an
01092  * internal pointer that is opaque to users of this API, but which users may
01093  * convert from and to a jsval using JS_ValueToId and JS_IdToValue.
01094  */
01095 struct JSProperty {
01096     jsid id;
01097 };
01098 
01099 struct JSIdArray {
01100     jsint length;
01101     jsid  vector[1];    /* actually, length jsid words */
01102 };
01103 
01104 extern JS_PUBLIC_API(void)
01105 JS_DestroyIdArray(JSContext *cx, JSIdArray *ida);
01106 
01107 extern JS_PUBLIC_API(JSBool)
01108 JS_ValueToId(JSContext *cx, jsval v, jsid *idp);
01109 
01110 extern JS_PUBLIC_API(JSBool)
01111 JS_IdToValue(JSContext *cx, jsid id, jsval *vp);
01112 
01113 /*
01114  * The magic XML namespace id is int-tagged, but not a valid integer jsval.
01115  * Global object classes in embeddings that enable JS_HAS_XML_SUPPORT (E4X)
01116  * should handle this id specially before converting id via JSVAL_TO_INT.
01117  */
01118 #define JS_DEFAULT_XML_NAMESPACE_ID ((jsid) JSVAL_VOID)
01119 
01120 /*
01121  * JSNewResolveOp flag bits.
01122  */
01123 #define JSRESOLVE_QUALIFIED     0x01    /* resolve a qualified property id */
01124 #define JSRESOLVE_ASSIGNING     0x02    /* resolve on the left of assignment */
01125 #define JSRESOLVE_DETECTING     0x04    /* 'if (o.p)...' or '(o.p) ?...:...' */
01126 #define JSRESOLVE_DECLARING     0x08    /* var, const, or function prolog op */
01127 #define JSRESOLVE_CLASSNAME     0x10    /* class name used when constructing */
01128 
01129 extern JS_PUBLIC_API(JSBool)
01130 JS_PropertyStub(JSContext *cx, JSObject *obj, jsval id, jsval *vp);
01131 
01132 extern JS_PUBLIC_API(JSBool)
01133 JS_EnumerateStub(JSContext *cx, JSObject *obj);
01134 
01135 extern JS_PUBLIC_API(JSBool)
01136 JS_ResolveStub(JSContext *cx, JSObject *obj, jsval id);
01137 
01138 extern JS_PUBLIC_API(JSBool)
01139 JS_ConvertStub(JSContext *cx, JSObject *obj, JSType type, jsval *vp);
01140 
01141 extern JS_PUBLIC_API(void)
01142 JS_FinalizeStub(JSContext *cx, JSObject *obj);
01143 
01144 struct JSConstDoubleSpec {
01145     jsdouble        dval;
01146     const char      *name;
01147     uint8           flags;
01148     uint8           spare[3];
01149 };
01150 
01151 /*
01152  * To define an array element rather than a named property member, cast the
01153  * element's index to (const char *) and initialize name with it, and set the
01154  * JSPROP_INDEX bit in flags.
01155  */
01156 struct JSPropertySpec {
01157     const char      *name;
01158     int8            tinyid;
01159     uint8           flags;
01160     JSPropertyOp    getter;
01161     JSPropertyOp    setter;
01162 };
01163 
01164 struct JSFunctionSpec {
01165     const char      *name;
01166     JSNative        call;
01167 #ifdef MOZILLA_1_8_BRANCH
01168     uint8           nargs;
01169     uint8           flags;
01170     uint16          extra;
01171 #else
01172     uint16          nargs;
01173     uint16          flags;
01174     uint32          extra;      /* extra & 0xFFFF:
01175                                    number of arg slots for local GC roots
01176                                    extra >> 16:
01177                                    reserved, must be zero */
01178 #endif
01179 };
01180 
01181 extern JS_PUBLIC_API(JSObject *)
01182 JS_InitClass(JSContext *cx, JSObject *obj, JSObject *parent_proto,
01183              JSClass *clasp, JSNative constructor, uintN nargs,
01184              JSPropertySpec *ps, JSFunctionSpec *fs,
01185              JSPropertySpec *static_ps, JSFunctionSpec *static_fs);
01186 
01187 #ifdef JS_THREADSAFE
01188 extern JS_PUBLIC_API(JSClass *)
01189 JS_GetClass(JSContext *cx, JSObject *obj);
01190 
01191 #define JS_GET_CLASS(cx,obj) JS_GetClass(cx, obj)
01192 #else
01193 extern JS_PUBLIC_API(JSClass *)
01194 JS_GetClass(JSObject *obj);
01195 
01196 #define JS_GET_CLASS(cx,obj) JS_GetClass(obj)
01197 #endif
01198 
01199 extern JS_PUBLIC_API(JSBool)
01200 JS_InstanceOf(JSContext *cx, JSObject *obj, JSClass *clasp, jsval *argv);
01201 
01202 extern JS_PUBLIC_API(JSBool)
01203 JS_HasInstance(JSContext *cx, JSObject *obj, jsval v, JSBool *bp);
01204 
01205 extern JS_PUBLIC_API(void *)
01206 JS_GetPrivate(JSContext *cx, JSObject *obj);
01207 
01208 extern JS_PUBLIC_API(JSBool)
01209 JS_SetPrivate(JSContext *cx, JSObject *obj, void *data);
01210 
01211 extern JS_PUBLIC_API(void *)
01212 JS_GetInstancePrivate(JSContext *cx, JSObject *obj, JSClass *clasp,
01213                       jsval *argv);
01214 
01215 extern JS_PUBLIC_API(JSObject *)
01216 JS_GetPrototype(JSContext *cx, JSObject *obj);
01217 
01218 extern JS_PUBLIC_API(JSBool)
01219 JS_SetPrototype(JSContext *cx, JSObject *obj, JSObject *proto);
01220 
01221 extern JS_PUBLIC_API(JSObject *)
01222 JS_GetParent(JSContext *cx, JSObject *obj);
01223 
01224 extern JS_PUBLIC_API(JSBool)
01225 JS_SetParent(JSContext *cx, JSObject *obj, JSObject *parent);
01226 
01227 extern JS_PUBLIC_API(JSObject *)
01228 JS_GetConstructor(JSContext *cx, JSObject *proto);
01229 
01230 /*
01231  * Get a unique identifier for obj, good for the lifetime of obj (even if it
01232  * is moved by a copying GC).  Return false on failure (likely out of memory),
01233  * and true with *idp containing the unique id on success.
01234  */
01235 extern JS_PUBLIC_API(JSBool)
01236 JS_GetObjectId(JSContext *cx, JSObject *obj, jsid *idp);
01237 
01238 extern JS_PUBLIC_API(JSObject *)
01239 JS_NewObject(JSContext *cx, JSClass *clasp, JSObject *proto, JSObject *parent);
01240 
01241 extern JS_PUBLIC_API(JSBool)
01242 JS_SealObject(JSContext *cx, JSObject *obj, JSBool deep);
01243 
01244 extern JS_PUBLIC_API(JSObject *)
01245 JS_ConstructObject(JSContext *cx, JSClass *clasp, JSObject *proto,
01246                    JSObject *parent);
01247 
01248 extern JS_PUBLIC_API(JSObject *)
01249 JS_ConstructObjectWithArguments(JSContext *cx, JSClass *clasp, JSObject *proto,
01250                                 JSObject *parent, uintN argc, jsval *argv);
01251 
01252 extern JS_PUBLIC_API(JSObject *)
01253 JS_DefineObject(JSContext *cx, JSObject *obj, const char *name, JSClass *clasp,
01254                 JSObject *proto, uintN attrs);
01255 
01256 extern JS_PUBLIC_API(JSBool)
01257 JS_DefineConstDoubles(JSContext *cx, JSObject *obj, JSConstDoubleSpec *cds);
01258 
01259 extern JS_PUBLIC_API(JSBool)
01260 JS_DefineProperties(JSContext *cx, JSObject *obj, JSPropertySpec *ps);
01261 
01262 extern JS_PUBLIC_API(JSBool)
01263 JS_DefineProperty(JSContext *cx, JSObject *obj, const char *name, jsval value,
01264                   JSPropertyOp getter, JSPropertyOp setter, uintN attrs);
01265 
01266 /*
01267  * Determine the attributes (JSPROP_* flags) of a property on a given object.
01268  *
01269  * If the object does not have a property by that name, *foundp will be
01270  * JS_FALSE and the value of *attrsp is undefined.
01271  */
01272 extern JS_PUBLIC_API(JSBool)
01273 JS_GetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name,
01274                          uintN *attrsp, JSBool *foundp);
01275 
01276 /*
01277  * The same, but if the property is native, return its getter and setter via
01278  * *getterp and *setterp, respectively (and only if the out parameter pointer
01279  * is not null).
01280  */
01281 extern JS_PUBLIC_API(JSBool)
01282 JS_GetPropertyAttrsGetterAndSetter(JSContext *cx, JSObject *obj,
01283                                    const char *name,
01284                                    uintN *attrsp, JSBool *foundp,
01285                                    JSPropertyOp *getterp,
01286                                    JSPropertyOp *setterp);
01287 
01288 /*
01289  * Set the attributes of a property on a given object.
01290  *
01291  * If the object does not have a property by that name, *foundp will be
01292  * JS_FALSE and nothing will be altered.
01293  */
01294 extern JS_PUBLIC_API(JSBool)
01295 JS_SetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name,
01296                          uintN attrs, JSBool *foundp);
01297 
01298 extern JS_PUBLIC_API(JSBool)
01299 JS_DefinePropertyWithTinyId(JSContext *cx, JSObject *obj, const char *name,
01300                             int8 tinyid, jsval value,
01301                             JSPropertyOp getter, JSPropertyOp setter,
01302                             uintN attrs);
01303 
01304 extern JS_PUBLIC_API(JSBool)
01305 JS_AliasProperty(JSContext *cx, JSObject *obj, const char *name,
01306                  const char *alias);
01307 
01308 extern JS_PUBLIC_API(JSBool)
01309 JS_HasProperty(JSContext *cx, JSObject *obj, const char *name, JSBool *foundp);
01310 
01311 extern JS_PUBLIC_API(JSBool)
01312 JS_LookupProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);
01313 
01314 extern JS_PUBLIC_API(JSBool)
01315 JS_LookupPropertyWithFlags(JSContext *cx, JSObject *obj, const char *name,
01316                            uintN flags, jsval *vp);
01317 
01318 extern JS_PUBLIC_API(JSBool)
01319 JS_GetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);
01320 
01321 extern JS_PUBLIC_API(JSBool)
01322 JS_GetMethodById(JSContext *cx, JSObject *obj, jsid id, JSObject **objp,
01323                  jsval *vp);
01324 
01325 extern JS_PUBLIC_API(JSBool)
01326 JS_GetMethod(JSContext *cx, JSObject *obj, const char *name, JSObject **objp,
01327              jsval *vp);
01328 
01329 extern JS_PUBLIC_API(JSBool)
01330 JS_SetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);
01331 
01332 extern JS_PUBLIC_API(JSBool)
01333 JS_DeleteProperty(JSContext *cx, JSObject *obj, const char *name);
01334 
01335 extern JS_PUBLIC_API(JSBool)
01336 JS_DeleteProperty2(JSContext *cx, JSObject *obj, const char *name,
01337                    jsval *rval);
01338 
01339 extern JS_PUBLIC_API(JSBool)
01340 JS_DefineUCProperty(JSContext *cx, JSObject *obj,
01341                     const jschar *name, size_t namelen, jsval value,
01342                     JSPropertyOp getter, JSPropertyOp setter,
01343                     uintN attrs);
01344 
01345 /*
01346  * Determine the attributes (JSPROP_* flags) of a property on a given object.
01347  *
01348  * If the object does not have a property by that name, *foundp will be
01349  * JS_FALSE and the value of *attrsp is undefined.
01350  */
01351 extern JS_PUBLIC_API(JSBool)
01352 JS_GetUCPropertyAttributes(JSContext *cx, JSObject *obj,
01353                            const jschar *name, size_t namelen,
01354                            uintN *attrsp, JSBool *foundp);
01355 
01356 /*
01357  * The same, but if the property is native, return its getter and setter via
01358  * *getterp and *setterp, respectively (and only if the out parameter pointer
01359  * is not null).
01360  */
01361 extern JS_PUBLIC_API(JSBool)
01362 JS_GetUCPropertyAttrsGetterAndSetter(JSContext *cx, JSObject *obj,
01363                                      const jschar *name, size_t namelen,
01364                                      uintN *attrsp, JSBool *foundp,
01365                                      JSPropertyOp *getterp,
01366                                      JSPropertyOp *setterp);
01367 
01368 /*
01369  * Set the attributes of a property on a given object.
01370  *
01371  * If the object does not have a property by that name, *foundp will be
01372  * JS_FALSE and nothing will be altered.
01373  */
01374 extern JS_PUBLIC_API(JSBool)
01375 JS_SetUCPropertyAttributes(JSContext *cx, JSObject *obj,
01376                            const jschar *name, size_t namelen,
01377                            uintN attrs, JSBool *foundp);
01378 
01379 
01380 extern JS_PUBLIC_API(JSBool)
01381 JS_DefineUCPropertyWithTinyId(JSContext *cx, JSObject *obj,
01382                               const jschar *name, size_t namelen,
01383                               int8 tinyid, jsval value,
01384                               JSPropertyOp getter, JSPropertyOp setter,
01385                               uintN attrs);
01386 
01387 extern JS_PUBLIC_API(JSBool)
01388 JS_HasUCProperty(JSContext *cx, JSObject *obj,
01389                  const jschar *name, size_t namelen,
01390                  JSBool *vp);
01391 
01392 extern JS_PUBLIC_API(JSBool)
01393 JS_LookupUCProperty(JSContext *cx, JSObject *obj,
01394                     const jschar *name, size_t namelen,
01395                     jsval *vp);
01396 
01397 extern JS_PUBLIC_API(JSBool)
01398 JS_GetUCProperty(JSContext *cx, JSObject *obj,
01399                  const jschar *name, size_t namelen,
01400                  jsval *vp);
01401 
01402 extern JS_PUBLIC_API(JSBool)
01403 JS_SetUCProperty(JSContext *cx, JSObject *obj,
01404                  const jschar *name, size_t namelen,
01405                  jsval *vp);
01406 
01407 extern JS_PUBLIC_API(JSBool)
01408 JS_DeleteUCProperty2(JSContext *cx, JSObject *obj,
01409                      const jschar *name, size_t namelen,
01410                      jsval *rval);
01411 
01412 extern JS_PUBLIC_API(JSObject *)
01413 JS_NewArrayObject(JSContext *cx, jsint length, jsval *vector);
01414 
01415 extern JS_PUBLIC_API(JSBool)
01416 JS_IsArrayObject(JSContext *cx, JSObject *obj);
01417 
01418 extern JS_PUBLIC_API(JSBool)
01419 JS_GetArrayLength(JSContext *cx, JSObject *obj, jsuint *lengthp);
01420 
01421 extern JS_PUBLIC_API(JSBool)
01422 JS_SetArrayLength(JSContext *cx, JSObject *obj, jsuint length);
01423 
01424 extern JS_PUBLIC_API(JSBool)
01425 JS_HasArrayLength(JSContext *cx, JSObject *obj, jsuint *lengthp);
01426 
01427 extern JS_PUBLIC_API(JSBool)
01428 JS_DefineElement(JSContext *cx, JSObject *obj, jsint index, jsval value,
01429                  JSPropertyOp getter, JSPropertyOp setter, uintN attrs);
01430 
01431 extern JS_PUBLIC_API(JSBool)
01432 JS_AliasElement(JSContext *cx, JSObject *obj, const char *name, jsint alias);
01433 
01434 extern JS_PUBLIC_API(JSBool)
01435 JS_HasElement(JSContext *cx, JSObject *obj, jsint index, JSBool *foundp);
01436 
01437 extern JS_PUBLIC_API(JSBool)
01438 JS_LookupElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp);
01439 
01440 extern JS_PUBLIC_API(JSBool)
01441 JS_GetElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp);
01442 
01443 extern JS_PUBLIC_API(JSBool)
01444 JS_SetElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp);
01445 
01446 extern JS_PUBLIC_API(JSBool)
01447 JS_DeleteElement(JSContext *cx, JSObject *obj, jsint index);
01448 
01449 extern JS_PUBLIC_API(JSBool)
01450 JS_DeleteElement2(JSContext *cx, JSObject *obj, jsint index, jsval *rval);
01451 
01452 extern JS_PUBLIC_API(void)
01453 JS_ClearScope(JSContext *cx, JSObject *obj);
01454 
01455 extern JS_PUBLIC_API(JSIdArray *)
01456 JS_Enumerate(JSContext *cx, JSObject *obj);
01457 
01458 /*
01459  * Create an object to iterate over enumerable properties of obj, in arbitrary
01460  * property definition order.  NB: This differs from longstanding for..in loop
01461  * order, which uses order of property definition in obj.
01462  */
01463 extern JS_PUBLIC_API(JSObject *)
01464 JS_NewPropertyIterator(JSContext *cx, JSObject *obj);
01465 
01466 /*
01467  * Return true on success with *idp containing the id of the next enumerable
01468  * property to visit using iterobj, or JSVAL_VOID if there is no such property
01469  * left to visit.  Return false on error.
01470  */
01471 extern JS_PUBLIC_API(JSBool)
01472 JS_NextProperty(JSContext *cx, JSObject *iterobj, jsid *idp);
01473 
01474 extern JS_PUBLIC_API(JSBool)
01475 JS_CheckAccess(JSContext *cx, JSObject *obj, jsid id, JSAccessMode mode,
01476                jsval *vp, uintN *attrsp);
01477 
01478 extern JS_PUBLIC_API(JSCheckAccessOp)
01479 JS_SetCheckObjectAccessCallback(JSRuntime *rt, JSCheckAccessOp acb);
01480 
01481 extern JS_PUBLIC_API(JSBool)
01482 JS_GetReservedSlot(JSContext *cx, JSObject *obj, uint32 index, jsval *vp);
01483 
01484 extern JS_PUBLIC_API(JSBool)
01485 JS_SetReservedSlot(JSContext *cx, JSObject *obj, uint32 index, jsval v);
01486 
01487 /************************************************************************/
01488 
01489 /*
01490  * Security protocol.
01491  */
01492 struct JSPrincipals {
01493     char *codebase;
01494 
01495     /* XXX unspecified and unused by Mozilla code -- can we remove these? */
01496     void * (* JS_DLL_CALLBACK getPrincipalArray)(JSContext *cx, JSPrincipals *);
01497     JSBool (* JS_DLL_CALLBACK globalPrivilegesEnabled)(JSContext *cx, JSPrincipals *);
01498 
01499     /* Don't call "destroy"; use reference counting macros below. */
01500     jsrefcount refcount;
01501 
01502     void   (* JS_DLL_CALLBACK destroy)(JSContext *cx, JSPrincipals *);
01503     JSBool (* JS_DLL_CALLBACK subsume)(JSPrincipals *, JSPrincipals *);
01504 };
01505 
01506 #ifdef JS_THREADSAFE
01507 #define JSPRINCIPALS_HOLD(cx, principals)   JS_HoldPrincipals(cx,principals)
01508 #define JSPRINCIPALS_DROP(cx, principals)   JS_DropPrincipals(cx,principals)
01509 
01510 extern JS_PUBLIC_API(jsrefcount)
01511 JS_HoldPrincipals(JSContext *cx, JSPrincipals *principals);
01512 
01513 extern JS_PUBLIC_API(jsrefcount)
01514 JS_DropPrincipals(JSContext *cx, JSPrincipals *principals);
01515 
01516 #else
01517 #define JSPRINCIPALS_HOLD(cx, principals)   (++(principals)->refcount)
01518 #define JSPRINCIPALS_DROP(cx, principals)                                     \
01519     ((--(principals)->refcount == 0)                                          \
01520      ? ((*(principals)->destroy)((cx), (principals)), 0)                      \
01521      : (principals)->refcount)
01522 #endif
01523 
01524 extern JS_PUBLIC_API(JSPrincipalsTranscoder)
01525 JS_SetPrincipalsTranscoder(JSRuntime *rt, JSPrincipalsTranscoder px);
01526 
01527 extern JS_PUBLIC_API(JSObjectPrincipalsFinder)
01528 JS_SetObjectPrincipalsFinder(JSRuntime *rt, JSObjectPrincipalsFinder fop);
01529 
01530 /************************************************************************/
01531 
01532 /*
01533  * Functions and scripts.
01534  */
01535 extern JS_PUBLIC_API(JSFunction *)
01536 JS_NewFunction(JSContext *cx, JSNative call, uintN nargs, uintN flags,
01537                JSObject *parent, const char *name);
01538 
01539 extern JS_PUBLIC_API(JSObject *)
01540 JS_GetFunctionObject(JSFunction *fun);
01541 
01542 /*
01543  * Deprecated, useful only for diagnostics.  Use JS_GetFunctionId instead for
01544  * anonymous vs. "anonymous" disambiguation and Unicode fidelity.
01545  */
01546 extern JS_PUBLIC_API(const char *)
01547 JS_GetFunctionName(JSFunction *fun);
01548 
01549 /*
01550  * Return the function's identifier as a JSString, or null if fun is unnamed.
01551  * The returned string lives as long as fun, so you don't need to root a saved
01552  * reference to it if fun is well-connected or rooted, and provided you bound
01553  * the use of the saved reference by fun's lifetime.
01554  *
01555  * Prefer JS_GetFunctionId over JS_GetFunctionName because it returns null for
01556  * truly anonymous functions, and because it doesn't chop to ISO-Latin-1 chars
01557  * from UTF-16-ish jschars.
01558  */
01559 extern JS_PUBLIC_API(JSString *)
01560 JS_GetFunctionId(JSFunction *fun);
01561 
01562 /*
01563  * Return JSFUN_* flags for fun.
01564  */
01565 extern JS_PUBLIC_API(uintN)
01566 JS_GetFunctionFlags(JSFunction *fun);
01567 
01568 /*
01569  * Return the arity (length) of fun.
01570  */
01571 extern JS_PUBLIC_API(uint16)
01572 JS_GetFunctionArity(JSFunction *fun);
01573 
01574 /*
01575  * Infallible predicate to test whether obj is a function object (faster than
01576  * comparing obj's class name to "Function", but equivalent unless someone has
01577  * overwritten the "Function" identifier with a different constructor and then
01578  * created instances using that constructor that might be passed in as obj).
01579  */
01580 extern JS_PUBLIC_API(JSBool)
01581 JS_ObjectIsFunction(JSContext *cx, JSObject *obj);
01582 
01583 extern JS_PUBLIC_API(JSBool)
01584 JS_DefineFunctions(JSContext *cx, JSObject *obj, JSFunctionSpec *fs);
01585 
01586 extern JS_PUBLIC_API(JSFunction *)
01587 JS_DefineFunction(JSContext *cx, JSObject *obj, const char *name, JSNative call,
01588                   uintN nargs, uintN attrs);
01589 
01590 extern JS_PUBLIC_API(JSFunction *)
01591 JS_DefineUCFunction(JSContext *cx, JSObject *obj,
01592                     const jschar *name, size_t namelen, JSNative call,
01593                     uintN nargs, uintN attrs);
01594 
01595 extern JS_PUBLIC_API(JSObject *)
01596 JS_CloneFunctionObject(JSContext *cx, JSObject *funobj, JSObject *parent);
01597 
01598 /*
01599  * Given a buffer, return JS_FALSE if the buffer might become a valid
01600  * javascript statement with the addition of more lines.  Otherwise return
01601  * JS_TRUE.  The intent is to support interactive compilation - accumulate
01602  * lines in a buffer until JS_BufferIsCompilableUnit is true, then pass it to
01603  * the compiler.
01604  */
01605 extern JS_PUBLIC_API(JSBool)
01606 JS_BufferIsCompilableUnit(JSContext *cx, JSObject *obj,
01607                           const char *bytes, size_t length);
01608 
01609 /*
01610  * The JSScript objects returned by the following functions refer to string and
01611  * other kinds of literals, including doubles and RegExp objects.  These
01612  * literals are vulnerable to garbage collection; to root script objects and
01613  * prevent literals from being collected, create a rootable object using
01614  * JS_NewScriptObject, and root the resulting object using JS_Add[Named]Root.
01615  */
01616 extern JS_PUBLIC_API(JSScript *)
01617 JS_CompileScript(JSContext *cx, JSObject *obj,
01618                  const char *bytes, size_t length,
01619                  const char *filename, uintN lineno);
01620 
01621 extern JS_PUBLIC_API(JSScript *)
01622 JS_CompileScriptForPrincipals(JSContext *cx, JSObject *obj,
01623                               JSPrincipals *principals,
01624                               const char *bytes, size_t length,
01625                               const char *filename, uintN lineno);
01626 
01627 extern JS_PUBLIC_API(JSScript *)
01628 JS_CompileUCScript(JSContext *cx, JSObject *obj,
01629                    const jschar *chars, size_t length,
01630                    const char *filename, uintN lineno);
01631 
01632 extern JS_PUBLIC_API(JSScript *)
01633 JS_CompileUCScriptForPrincipals(JSContext *cx, JSObject *obj,
01634                                 JSPrincipals *principals,
01635                                 const jschar *chars, size_t length,
01636                                 const char *filename, uintN lineno);
01637 
01638 extern JS_PUBLIC_API(JSScript *)
01639 JS_CompileFile(JSContext *cx, JSObject *obj, const char *filename);
01640 
01641 extern JS_PUBLIC_API(JSScript *)
01642 JS_CompileFileHandle(JSContext *cx, JSObject *obj, const char *filename,
01643                      FILE *fh);
01644 
01645 extern JS_PUBLIC_API(JSScript *)
01646 JS_CompileFileHandleForPrincipals(JSContext *cx, JSObject *obj,
01647                                   const char *filename, FILE *fh,
01648                                   JSPrincipals *principals);
01649 
01650 /*
01651  * NB: you must use JS_NewScriptObject and root a pointer to its return value
01652  * in order to keep a JSScript and its atoms safe from garbage collection after
01653  * creating the script via JS_Compile* and before a JS_ExecuteScript* call.
01654  * E.g., and without error checks:
01655  *
01656  *    JSScript *script = JS_CompileFile(cx, global, filename);
01657  *    JSObject *scrobj = JS_NewScriptObject(cx, script);
01658  *    JS_AddNamedRoot(cx, &scrobj, "scrobj");
01659  *    do {
01660  *        jsval result;
01661  *        JS_ExecuteScript(cx, global, script, &result);
01662  *        JS_GC();
01663  *    } while (!JSVAL_IS_BOOLEAN(result) || JSVAL_TO_BOOLEAN(result));
01664  *    JS_RemoveRoot(cx, &scrobj);
01665  */
01666 extern JS_PUBLIC_API(JSObject *)
01667 JS_NewScriptObject(JSContext *cx, JSScript *script);
01668 
01669 /*
01670  * Infallible getter for a script's object.  If JS_NewScriptObject has not been
01671  * called on script yet, the return value will be null.
01672  */
01673 extern JS_PUBLIC_API(JSObject *)
01674 JS_GetScriptObject(JSScript *script);
01675 
01676 extern JS_PUBLIC_API(void)
01677 JS_DestroyScript(JSContext *cx, JSScript *script);
01678 
01679 extern JS_PUBLIC_API(JSFunction *)
01680 JS_CompileFunction(JSContext *cx, JSObject *obj, const char *name,
01681                    uintN nargs, const char **argnames,
01682                    const char *bytes, size_t length,
01683                    const char *filename, uintN lineno);
01684 
01685 extern JS_PUBLIC_API(JSFunction *)
01686 JS_CompileFunctionForPrincipals(JSContext *cx, JSObject *obj,
01687                                 JSPrincipals *principals, const char *name,
01688                                 uintN nargs, const char **argnames,
01689                                 const char *bytes, size_t length,
01690                                 const char *filename, uintN lineno);
01691 
01692 extern JS_PUBLIC_API(JSFunction *)
01693 JS_CompileUCFunction(JSContext *cx, JSObject *obj, const char *name,
01694                      uintN nargs, const char **argnames,
01695                      const jschar *chars, size_t length,
01696                      const char *filename, uintN lineno);
01697 
01698 extern JS_PUBLIC_API(JSFunction *)
01699 JS_CompileUCFunctionForPrincipals(JSContext *cx, JSObject *obj,
01700                                   JSPrincipals *principals, const char *name,
01701                                   uintN nargs, const char **argnames,
01702                                   const jschar *chars, size_t length,
01703                                   const char *filename, uintN lineno);
01704 
01705 extern JS_PUBLIC_API(JSString *)
01706 JS_DecompileScript(JSContext *cx, JSScript *script, const char *name,
01707                    uintN indent);
01708 
01709 /*
01710  * API extension: OR this into indent to avoid pretty-printing the decompiled
01711  * source resulting from JS_DecompileFunction{,Body}.
01712  */
01713 #define JS_DONT_PRETTY_PRINT    ((uintN)0x8000)
01714 
01715 extern JS_PUBLIC_API(JSString *)
01716 JS_DecompileFunction(JSContext *cx, JSFunction *fun, uintN indent);
01717 
01718 extern JS_PUBLIC_API(JSString *)
01719 JS_DecompileFunctionBody(JSContext *cx, JSFunction *fun, uintN indent);
01720 
01721 /*
01722  * NB: JS_ExecuteScript, JS_ExecuteScriptPart, and the JS_Evaluate*Script*
01723  * quadruplets all use the obj parameter as the initial scope chain header,
01724  * the 'this' keyword value, and the variables object (ECMA parlance for where
01725  * 'var' and 'function' bind names) of the execution context for script.
01726  *
01727  * Using obj as the variables object is problematic if obj's parent (which is
01728  * the scope chain link; see JS_SetParent and JS_NewObject) is not null: in
01729  * this case, variables created by 'var x = 0', e.g., go in obj, but variables
01730  * created by assignment to an unbound id, 'x = 0', go in the last object on
01731  * the scope chain linked by parent.
01732  *
01733  * ECMA calls that last scoping object the "global object", but note that many
01734  * embeddings have several such objects.  ECMA requires that "global code" be
01735  * executed with the variables object equal to this global object.  But these
01736  * JS API entry points provide freedom to execute code against a "sub-global",
01737  * i.e., a parented or scoped object, in which case the variables object will
01738  * differ from the last object on the scope chain, resulting in confusing and
01739  * non-ECMA explicit vs. implicit variable creation.
01740  *
01741  * Caveat embedders: unless you already depend on this buggy variables object
01742  * binding behavior, you should call JS_SetOptions(cx, JSOPTION_VAROBJFIX) or
01743  * JS_SetOptions(cx, JS_GetOptions(cx) | JSOPTION_VAROBJFIX) -- the latter if
01744  * someone may have set other options on cx already -- for each context in the
01745  * application, if you pass parented objects as the obj parameter, or may ever
01746  * pass such objects in the future.
01747  *
01748  * Why a runtime option?  The alternative is to add six or so new API entry
01749  * points with signatures matching the following six, and that doesn't seem
01750  * worth the code bloat cost.  Such new entry points would probably have less
01751  * obvious names, too, so would not tend to be used.  The JS_SetOption call,
01752  * OTOH, can be more easily hacked into existing code that does not depend on
01753  * the bug; such code can continue to use the familiar JS_EvaluateScript,
01754  * etc., entry points.
01755  */
01756 extern JS_PUBLIC_API(JSBool)
01757 JS_ExecuteScript(JSContext *cx, JSObject *obj, JSScript *script, jsval *rval);
01758 
01759 /*
01760  * Execute either the function-defining prolog of a script, or the script's
01761  * main body, but not both.
01762  */
01763 typedef enum JSExecPart { JSEXEC_PROLOG, JSEXEC_MAIN } JSExecPart;
01764 
01765 extern JS_PUBLIC_API(JSBool)
01766 JS_ExecuteScriptPart(JSContext *cx, JSObject *obj, JSScript *script,
01767                      JSExecPart part, jsval *rval);
01768 
01769 extern JS_PUBLIC_API(JSBool)
01770 JS_EvaluateScript(JSContext *cx, JSObject *obj,
01771                   const char *bytes, uintN length,
01772                   const char *filename, uintN lineno,
01773                   jsval *rval);
01774 
01775 extern JS_PUBLIC_API(JSBool)
01776 JS_EvaluateScriptForPrincipals(JSContext *cx, JSObject *obj,
01777                                JSPrincipals *principals,
01778                                const char *bytes, uintN length,
01779                                const char *filename, uintN lineno,
01780                                jsval *rval);
01781 
01782 extern JS_PUBLIC_API(JSBool)
01783 JS_EvaluateUCScript(JSContext *cx, JSObject *obj,
01784                     const jschar *chars, uintN length,
01785                     const char *filename, uintN lineno,
01786                     jsval *rval);
01787 
01788 extern JS_PUBLIC_API(JSBool)
01789 JS_EvaluateUCScriptForPrincipals(JSContext *cx, JSObject *obj,
01790                                  JSPrincipals *principals,
01791                                  const jschar *chars, uintN length,
01792                                  const char *filename, uintN lineno,
01793                                  jsval *rval);
01794 
01795 extern JS_PUBLIC_API(JSBool)
01796 JS_CallFunction(JSContext *cx, JSObject *obj, JSFunction *fun, uintN argc,
01797                 jsval *argv, jsval *rval);
01798 
01799 extern JS_PUBLIC_API(JSBool)
01800 JS_CallFunctionName(JSContext *cx, JSObject *obj, const char *name, uintN argc,
01801                     jsval *argv, jsval *rval);
01802 
01803 extern JS_PUBLIC_API(JSBool)
01804 JS_CallFunctionValue(JSContext *cx, JSObject *obj, jsval fval, uintN argc,
01805                      jsval *argv, jsval *rval);
01806 
01807 extern JS_PUBLIC_API(JSBranchCallback)
01808 JS_SetBranchCallback(JSContext *cx, JSBranchCallback cb);
01809 
01810 extern JS_PUBLIC_API(JSBool)
01811 JS_IsRunning(JSContext *cx);
01812 
01813 extern JS_PUBLIC_API(JSBool)
01814 JS_IsConstructing(JSContext *cx);
01815 
01816 /*
01817  * Returns true if a script is executing and its current bytecode is a set
01818  * (assignment) operation, even if there are native (no script) stack frames
01819  * between the script and the caller to JS_IsAssigning.
01820  */
01821 extern JS_FRIEND_API(JSBool)
01822 JS_IsAssigning(JSContext *cx);
01823 
01824 /*
01825  * Set the second return value, which should be a string or int jsval that
01826  * identifies a property in the returned object, to form an ECMA reference
01827  * type value (obj, id).  Only native methods can return reference types,
01828  * and if the returned value is used on the left-hand side of an assignment
01829  * op, the identified property will be set.  If the return value is in an
01830  * r-value, the interpreter just gets obj[id]'s value.
01831  */
01832 extern JS_PUBLIC_API(void)
01833 JS_SetCallReturnValue2(JSContext *cx, jsval v);
01834 
01835 /*
01836  * Saving and restoring frame chains.
01837  *
01838  * These two functions are used to set aside cx->fp while that frame is
01839  * inactive. After a call to JS_SaveFrameChain, it looks as if there is no
01840  * code running on cx. Before calling JS_RestoreFrameChain, cx's call stack
01841  * must be balanced and all nested calls to JS_SaveFrameChain must have had
01842  * matching JS_RestoreFrameChain calls.
01843  *
01844  * JS_SaveFrameChain deals with cx not having any code running on it. A null
01845  * return does not signify an error and JS_RestoreFrameChain handles null
01846  * frames.
01847  */
01848 extern JS_PUBLIC_API(JSStackFrame *)
01849 JS_SaveFrameChain(JSContext *cx);
01850 
01851 extern JS_PUBLIC_API(void)
01852 JS_RestoreFrameChain(JSContext *cx, JSStackFrame *fp);
01853 
01854 /************************************************************************/
01855 
01856 /*
01857  * Strings.
01858  *
01859  * NB: JS_NewString takes ownership of bytes on success, avoiding a copy; but
01860  * on error (signified by null return), it leaves bytes owned by the caller.
01861  * So the caller must free bytes in the error case, if it has no use for them.
01862  * In contrast, all the JS_New*StringCopy* functions do not take ownership of
01863  * the character memory passed to them -- they copy it.
01864  */
01865 extern JS_PUBLIC_API(JSString *)
01866 JS_NewString(JSContext *cx, char *bytes, size_t length);
01867 
01868 extern JS_PUBLIC_API(JSString *)
01869 JS_NewStringCopyN(JSContext *cx, const char *s, size_t n);
01870 
01871 extern JS_PUBLIC_API(JSString *)
01872 JS_NewStringCopyZ(JSContext *cx, const char *s);
01873 
01874 extern JS_PUBLIC_API(JSString *)
01875 JS_InternString(JSContext *cx, const char *s);
01876 
01877 extern JS_PUBLIC_API(JSString *)
01878 JS_NewUCString(JSContext *cx, jschar *chars, size_t length);
01879 
01880 extern JS_PUBLIC_API(JSString *)
01881 JS_NewUCStringCopyN(JSContext *cx, const jschar *s, size_t n);
01882 
01883 extern JS_PUBLIC_API(JSString *)
01884 JS_NewUCStringCopyZ(JSContext *cx, const jschar *s);
01885 
01886 extern JS_PUBLIC_API(JSString *)
01887 JS_InternUCStringN(JSContext *cx, const jschar *s, size_t length);
01888 
01889 extern JS_PUBLIC_API(JSString *)
01890 JS_InternUCString(JSContext *cx, const jschar *s);
01891 
01892 extern JS_PUBLIC_API(char *)
01893 JS_GetStringBytes(JSString *str);
01894 
01895 extern JS_PUBLIC_API(jschar *)
01896 JS_GetStringChars(JSString *str);
01897 
01898 extern JS_PUBLIC_API(size_t)
01899 JS_GetStringLength(JSString *str);
01900 
01901 extern JS_PUBLIC_API(intN)
01902 JS_CompareStrings(JSString *str1, JSString *str2);
01903 
01904 /*
01905  * Mutable string support.  A string's characters are never mutable in this JS
01906  * implementation, but a growable string has a buffer that can be reallocated,
01907  * and a dependent string is a substring of another (growable, dependent, or
01908  * immutable) string.  The direct data members of the (opaque to API clients)
01909  * JSString struct may be changed in a single-threaded way for growable and
01910  * dependent strings.
01911  *
01912  * Therefore mutable strings cannot be used by more than one thread at a time.
01913  * You may call JS_MakeStringImmutable to convert the string from a mutable
01914  * (growable or dependent) string to an immutable (and therefore thread-safe)
01915  * string.  The engine takes care of converting growable and dependent strings
01916  * to immutable for you if you store strings in multi-threaded objects using
01917  * JS_SetProperty or kindred API entry points.
01918  *
01919  * If you store a JSString pointer in a native data structure that is (safely)
01920  * accessible to multiple threads, you must call JS_MakeStringImmutable before
01921  * retiring the store.
01922  */
01923 extern JS_PUBLIC_API(JSString *)
01924 JS_NewGrowableString(JSContext *cx, jschar *chars, size_t length);
01925 
01926 /*
01927  * Create a dependent string, i.e., a string that owns no character storage,
01928  * but that refers to a slice of another string's chars.  Dependent strings
01929  * are mutable by definition, so the thread safety comments above apply.
01930  */
01931 extern JS_PUBLIC_API(JSString *)
01932 JS_NewDependentString(JSContext *cx, JSString *str, size_t start,
01933                       size_t length);
01934 
01935 /*
01936  * Concatenate two strings, resulting in a new growable string.  If you create
01937  * the left string and pass it to JS_ConcatStrings on a single thread, try to
01938  * use JS_NewGrowableString to create the left string -- doing so helps Concat
01939  * avoid allocating a new buffer for the result and copying left's chars into
01940  * the new buffer.  See above for thread safety comments.
01941  */
01942 extern JS_PUBLIC_API(JSString *)
01943 JS_ConcatStrings(JSContext *cx, JSString *left, JSString *right);
01944 
01945 /*
01946  * Convert a dependent string into an independent one.  This function does not
01947  * change the string's mutability, so the thread safety comments above apply.
01948  */
01949 extern JS_PUBLIC_API(const jschar *)
01950 JS_UndependString(JSContext *cx, JSString *str);
01951 
01952 /*
01953  * Convert a mutable string (either growable or dependent) into an immutable,
01954  * thread-safe one.
01955  */
01956 extern JS_PUBLIC_API(JSBool)
01957 JS_MakeStringImmutable(JSContext *cx, JSString *str);
01958 
01959 /*
01960  * Return JS_TRUE if C (char []) strings passed via the API and internally
01961  * are UTF-8. The source must be compiled with JS_C_STRINGS_ARE_UTF8 defined
01962  * to get UTF-8 support.
01963  */
01964 JS_PUBLIC_API(JSBool)
01965 JS_CStringsAreUTF8();
01966 
01967 /*
01968  * Character encoding support.
01969  *
01970  * For both JS_EncodeCharacters and JS_DecodeBytes, set *dstlenp to the size
01971  * of the destination buffer before the call; on return, *dstlenp contains the
01972  * number of bytes (JS_EncodeCharacters) or jschars (JS_DecodeBytes) actually
01973  * stored.  To determine the necessary destination buffer size, make a sizing
01974  * call that passes NULL for dst.
01975  *
01976  * On errors, the functions report the error. In that case, *dstlenp contains
01977  * the number of characters or bytes transferred so far.  If cx is NULL, no
01978  * error is reported on failure, and the functions simply return JS_FALSE.
01979  *
01980  * NB: Neither function stores an additional zero byte or jschar after the
01981  * transcoded string.
01982  *
01983  * If the source has been compiled with the #define JS_C_STRINGS_ARE_UTF8 to
01984  * enable UTF-8 interpretation of C char[] strings, then JS_EncodeCharacters
01985  * encodes to UTF-8, and JS_DecodeBytes decodes from UTF-8, which may create
01986  * addititional errors if the character sequence is malformed.  If UTF-8
01987  * support is disabled, the functions deflate and inflate, respectively.
01988  */
01989 JS_PUBLIC_API(JSBool)
01990 JS_EncodeCharacters(JSContext *cx, const jschar *src, size_t srclen, char *dst,
01991                     size_t *dstlenp);
01992 
01993 JS_PUBLIC_API(JSBool)
01994 JS_DecodeBytes(JSContext *cx, const char *src, size_t srclen, jschar *dst,
01995                size_t *dstlenp);
01996 
01997 /************************************************************************/
01998 
01999 /*
02000  * Locale specific string conversion and error message callbacks.
02001  */
02002 struct JSLocaleCallbacks {
02003     JSLocaleToUpperCase     localeToUpperCase;
02004     JSLocaleToLowerCase     localeToLowerCase;
02005     JSLocaleCompare         localeCompare;
02006     JSLocaleToUnicode       localeToUnicode;
02007     JSErrorCallback         localeGetErrorMessage;
02008 };
02009 
02010 /*
02011  * Establish locale callbacks. The pointer must persist as long as the
02012  * JSContext.  Passing NULL restores the default behaviour.
02013  */
02014 extern JS_PUBLIC_API(void)
02015 JS_SetLocaleCallbacks(JSContext *cx, JSLocaleCallbacks *callbacks);
02016 
02017 /*
02018  * Return the address of the current locale callbacks struct, which may
02019  * be NULL.
02020  */
02021 extern JS_PUBLIC_API(JSLocaleCallbacks *)
02022 JS_GetLocaleCallbacks(JSContext *cx);
02023 
02024 /************************************************************************/
02025 
02026 /*
02027  * Error reporting.
02028  */
02029 
02030 /*
02031  * Report an exception represented by the sprintf-like conversion of format
02032  * and its arguments.  This exception message string is passed to a pre-set
02033  * JSErrorReporter function (set by JS_SetErrorReporter; see jspubtd.h for
02034  * the JSErrorReporter typedef).
02035  */
02036 extern JS_PUBLIC_API(void)
02037 JS_ReportError(JSContext *cx, const char *format, ...);
02038 
02039 /*
02040  * Use an errorNumber to retrieve the format string, args are char *
02041  */
02042 extern JS_PUBLIC_API(void)
02043 JS_ReportErrorNumber(JSContext *cx, JSErrorCallback errorCallback,
02044                      void *userRef, const uintN errorNumber, ...);
02045 
02046 /*
02047  * Use an errorNumber to retrieve the format string, args are jschar *
02048  */
02049 extern JS_PUBLIC_API(void)
02050 JS_ReportErrorNumberUC(JSContext *cx, JSErrorCallback errorCallback,
02051                      void *userRef, const uintN errorNumber, ...);
02052 
02053 /*
02054  * As above, but report a warning instead (JSREPORT_IS_WARNING(report.flags)).
02055  * Return true if there was no error trying to issue the warning, and if the
02056  * warning was not converted into an error due to the JSOPTION_WERROR option
02057  * being set, false otherwise.
02058  */
02059 extern JS_PUBLIC_API(JSBool)
02060 JS_ReportWarning(JSContext *cx, const char *format, ...);
02061 
02062 extern JS_PUBLIC_API(JSBool)
02063 JS_ReportErrorFlagsAndNumber(JSContext *cx, uintN flags,
02064                              JSErrorCallback errorCallback, void *userRef,
02065                              const uintN errorNumber, ...);
02066 
02067 extern JS_PUBLIC_API(JSBool)
02068 JS_ReportErrorFlagsAndNumberUC(JSContext *cx, uintN flags,
02069                                JSErrorCallback errorCallback, void *userRef,
02070                                const uintN errorNumber, ...);
02071 
02072 /*
02073  * Complain when out of memory.
02074  */
02075 extern JS_PUBLIC_API(void)
02076 JS_ReportOutOfMemory(JSContext *cx);
02077 
02078 struct JSErrorReport {
02079     const char      *filename;      /* source file name, URL, etc., or null */
02080     uintN           lineno;         /* source line number */
02081     const char      *linebuf;       /* offending source line without final \n */
02082     const char      *tokenptr;      /* pointer to error token in linebuf */
02083     const jschar    *uclinebuf;     /* unicode (original) line buffer */
02084     const jschar    *uctokenptr;    /* unicode (original) token pointer */
02085     uintN           flags;          /* error/warning, etc. */
02086     uintN           errorNumber;    /* the error number, e.g. see js.msg */
02087     const jschar    *ucmessage;     /* the (default) error message */
02088     const jschar    **messageArgs;  /* arguments for the error message */
02089 };
02090 
02091 /*
02092  * JSErrorReport flag values.  These may be freely composed.
02093  */
02094 #define JSREPORT_ERROR      0x0     /* pseudo-flag for default case */
02095 #define JSREPORT_WARNING    0x1     /* reported via JS_ReportWarning */
02096 #define JSREPORT_EXCEPTION  0x2     /* exception was thrown */
02097 #define JSREPORT_STRICT     0x4     /* error or warning due to strict option */
02098 
02099 /*
02100  * If JSREPORT_EXCEPTION is set, then a JavaScript-catchable exception
02101  * has been thrown for this runtime error, and the host should ignore it.
02102  * Exception-aware hosts should also check for JS_IsExceptionPending if
02103  * JS_ExecuteScript returns failure, and signal or propagate the exception, as
02104  * appropriate.
02105  */
02106 #define JSREPORT_IS_WARNING(flags)      (((flags) & JSREPORT_WARNING) != 0)
02107 #define JSREPORT_IS_EXCEPTION(flags)    (((flags) & JSREPORT_EXCEPTION) != 0)
02108 #define JSREPORT_IS_STRICT(flags)       (((flags) & JSREPORT_STRICT) != 0)
02109 
02110 extern JS_PUBLIC_API(JSErrorReporter)
02111 JS_SetErrorReporter(JSContext *cx, JSErrorReporter er);
02112 
02113 /************************************************************************/
02114 
02115 /*
02116  * Regular Expressions.
02117  */
02118 #define JSREG_FOLD      0x01    /* fold uppercase to lowercase */
02119 #define JSREG_GLOB      0x02    /* global exec, creates array of matches */
02120 #define JSREG_MULTILINE 0x04    /* treat ^ and $ as begin and end of line */
02121 
02122 extern JS_PUBLIC_API(JSObject *)
02123 JS_NewRegExpObject(JSContext *cx, char *bytes, size_t length, uintN flags);
02124 
02125 extern JS_PUBLIC_API(JSObject *)
02126 JS_NewUCRegExpObject(JSContext *cx, jschar *chars, size_t length, uintN flags);
02127 
02128 extern JS_PUBLIC_API(void)
02129 JS_SetRegExpInput(JSContext *cx, JSString *input, JSBool multiline);
02130 
02131 extern JS_PUBLIC_API(void)
02132 JS_ClearRegExpStatics(JSContext *cx);
02133 
02134 extern JS_PUBLIC_API(void)
02135 JS_ClearRegExpRoots(JSContext *cx);
02136 
02137 /* TODO: compile, exec, get/set other statics... */
02138 
02139 /************************************************************************/
02140 
02141 extern JS_PUBLIC_API(JSBool)
02142 JS_IsExceptionPending(JSContext *cx);
02143 
02144 extern JS_PUBLIC_API(JSBool)
02145 JS_GetPendingException(JSContext *cx, jsval *vp);
02146 
02147 extern JS_PUBLIC_API(void)
02148 JS_SetPendingException(JSContext *cx, jsval v);
02149 
02150 extern JS_PUBLIC_API(void)
02151 JS_ClearPendingException(JSContext *cx);
02152 
02153 extern JS_PUBLIC_API(JSBool)
02154 JS_ReportPendingException(JSContext *cx);
02155 
02156 /*
02157  * Save the current exception state.  This takes a snapshot of cx's current
02158  * exception state without making any change to that state.
02159  *
02160  * The returned state pointer MUST be passed later to JS_RestoreExceptionState
02161  * (to restore that saved state, overriding any more recent state) or else to
02162  * JS_DropExceptionState (to free the state struct in case it is not correct
02163  * or desirable to restore it).  Both Restore and Drop free the state struct,
02164  * so callers must stop using the pointer returned from Save after calling the
02165  * Release or Drop API.
02166  */
02167 extern JS_PUBLIC_API(JSExceptionState *)
02168 JS_SaveExceptionState(JSContext *cx);
02169 
02170 extern JS_PUBLIC_API(void)
02171 JS_RestoreExceptionState(JSContext *cx, JSExceptionState *state);
02172 
02173 extern JS_PUBLIC_API(void)
02174 JS_DropExceptionState(JSContext *cx, JSExceptionState *state);
02175 
02176 /*
02177  * If the given value is an exception object that originated from an error,
02178  * the exception will contain an error report struct, and this API will return
02179  * the address of that struct.  Otherwise, it returns NULL.  The lifetime of
02180  * the error report struct that might be returned is the same as the lifetime
02181  * of the exception object.
02182  */
02183 extern JS_PUBLIC_API(JSErrorReport *)
02184 JS_ErrorFromException(JSContext *cx, jsval v);
02185 
02186 /*
02187  * Given a reported error's message and JSErrorReport struct pointer, throw
02188  * the corresponding exception on cx.
02189  */
02190 extern JS_PUBLIC_API(JSBool)
02191 JS_ThrowReportedError(JSContext *cx, const char *message,
02192                       JSErrorReport *reportp);
02193 
02194 #ifdef JS_THREADSAFE
02195 
02196 /*
02197  * Associate the current thread with the given context.  This is done
02198  * implicitly by JS_NewContext.
02199  *
02200  * Returns the old thread id for this context, which should be treated as
02201  * an opaque value.  This value is provided for comparison to 0, which
02202  * indicates that ClearContextThread has been called on this context
02203  * since the last SetContextThread, or non-0, which indicates the opposite.
02204  */
02205 extern JS_PUBLIC_API(jsword)
02206 JS_GetContextThread(JSContext *cx);
02207 
02208 extern JS_PUBLIC_API(jsword)
02209 JS_SetContextThread(JSContext *cx);
02210 
02211 extern JS_PUBLIC_API(jsword)
02212 JS_ClearContextThread(JSContext *cx);
02213 
02214 #endif /* JS_THREADSAFE */
02215 
02216 /************************************************************************/
02217 
02218 #ifdef DEBUG
02219 #define JS_GC_ZEAL 1
02220 #endif
02221 
02222 #ifdef JS_GC_ZEAL
02223 extern JS_PUBLIC_API(void)
02224 JS_SetGCZeal(JSContext *cx, uint8 zeal);
02225 #endif
02226 
02227 JS_END_EXTERN_C
02228 
02229 #endif /* jsapi_h___ */