![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to jsapi.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Synchronet] / sbbs / javascript / include / mozilla / js|
Return to jsapi.h CVS log | Up to [Synchronet] / sbbs / javascript / include / mozilla / js |
1.1 root 1: /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
2: *
3: * The contents of this file are subject to the Netscape Public
4: * License Version 1.1 (the "License"); you may not use this file
5: * except in compliance with the License. You may obtain a copy of
6: * the License at http://www.mozilla.org/NPL/
7: *
8: * Software distributed under the License is distributed on an "AS
9: * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
10: * implied. See the License for the specific language governing
11: * rights and limitations under the License.
12: *
13: * The Original Code is Mozilla Communicator client code, released
14: * March 31, 1998.
15: *
16: * The Initial Developer of the Original Code is Netscape
17: * Communications Corporation. Portions created by Netscape are
18: * Copyright (C) 1998 Netscape Communications Corporation. All
19: * Rights Reserved.
20: *
21: * Contributor(s):
22: *
23: * Alternatively, the contents of this file may be used under the
24: * terms of the GNU Public License (the "GPL"), in which case the
25: * provisions of the GPL are applicable instead of those above.
26: * If you wish to allow use of your version of this file only
27: * under the terms of the GPL and not to allow others to use your
28: * version of this file under the NPL, indicate your decision by
29: * deleting the provisions above and replace them with the notice
30: * and other provisions required by the GPL. If you do not delete
31: * the provisions above, a recipient may use your version of this
32: * file under either the NPL or the GPL.
33: */
34:
35: #ifndef jsapi_h___
36: #define jsapi_h___
37: /*
38: * JavaScript API.
39: */
40: #include <stddef.h>
41: #include <stdio.h>
42: #include "jspubtd.h"
43:
44: JS_BEGIN_EXTERN_C
45:
46: /*
47: * Type tags stored in the low bits of a jsval.
48: */
49: #define JSVAL_OBJECT 0x0 /* untagged reference to object */
50: #define JSVAL_INT 0x1 /* tagged 31-bit integer value */
51: #define JSVAL_DOUBLE 0x2 /* tagged reference to double */
52: #define JSVAL_STRING 0x4 /* tagged reference to string */
53: #define JSVAL_BOOLEAN 0x6 /* tagged boolean value */
54:
55: /* Type tag bitfield length and derived macros. */
56: #define JSVAL_TAGBITS 3
57: #define JSVAL_TAGMASK JS_BITMASK(JSVAL_TAGBITS)
58: #define JSVAL_TAG(v) ((v) & JSVAL_TAGMASK)
59: #define JSVAL_SETTAG(v,t) ((v) | (t))
60: #define JSVAL_CLRTAG(v) ((v) & ~(jsval)JSVAL_TAGMASK)
61: #define JSVAL_ALIGN JS_BIT(JSVAL_TAGBITS)
62:
63: /* Predicates for type testing. */
64: #define JSVAL_IS_OBJECT(v) (JSVAL_TAG(v) == JSVAL_OBJECT)
65: #define JSVAL_IS_NUMBER(v) (JSVAL_IS_INT(v) || JSVAL_IS_DOUBLE(v))
66: #define JSVAL_IS_INT(v) (((v) & JSVAL_INT) && (v) != JSVAL_VOID)
67: #define JSVAL_IS_DOUBLE(v) (JSVAL_TAG(v) == JSVAL_DOUBLE)
68: #define JSVAL_IS_STRING(v) (JSVAL_TAG(v) == JSVAL_STRING)
69: #define JSVAL_IS_BOOLEAN(v) (JSVAL_TAG(v) == JSVAL_BOOLEAN)
70: #define JSVAL_IS_NULL(v) ((v) == JSVAL_NULL)
71: #define JSVAL_IS_VOID(v) ((v) == JSVAL_VOID)
72: #define JSVAL_IS_PRIMITIVE(v) (!JSVAL_IS_OBJECT(v) || JSVAL_IS_NULL(v))
73:
74: /* Objects, strings, and doubles are GC'ed. */
75: #define JSVAL_IS_GCTHING(v) (!((v) & JSVAL_INT) && !JSVAL_IS_BOOLEAN(v))
76: #define JSVAL_TO_GCTHING(v) ((void *)JSVAL_CLRTAG(v))
77: #define JSVAL_TO_OBJECT(v) ((JSObject *)JSVAL_TO_GCTHING(v))
78: #define JSVAL_TO_DOUBLE(v) ((jsdouble *)JSVAL_TO_GCTHING(v))
79: #define JSVAL_TO_STRING(v) ((JSString *)JSVAL_TO_GCTHING(v))
80: #define OBJECT_TO_JSVAL(obj) ((jsval)(obj))
81: #define DOUBLE_TO_JSVAL(dp) JSVAL_SETTAG((jsval)(dp), JSVAL_DOUBLE)
82: #define STRING_TO_JSVAL(str) JSVAL_SETTAG((jsval)(str), JSVAL_STRING)
83:
84: /* Lock and unlock the GC thing held by a jsval. */
85: #define JSVAL_LOCK(cx,v) (JSVAL_IS_GCTHING(v) \
86: ? JS_LockGCThing(cx, JSVAL_TO_GCTHING(v)) \
87: : JS_TRUE)
88: #define JSVAL_UNLOCK(cx,v) (JSVAL_IS_GCTHING(v) \
89: ? JS_UnlockGCThing(cx, JSVAL_TO_GCTHING(v)) \
90: : JS_TRUE)
91:
92: /* Domain limits for the jsval int type. */
93: #define JSVAL_INT_BITS 31
94: #define JSVAL_INT_POW2(n) ((jsval)1 << (n))
95: #define JSVAL_INT_MIN ((jsval)1 - JSVAL_INT_POW2(30))
96: #define JSVAL_INT_MAX (JSVAL_INT_POW2(30) - 1)
97: #define INT_FITS_IN_JSVAL(i) ((jsuint)((i)+JSVAL_INT_MAX) <= 2*JSVAL_INT_MAX)
98: #define JSVAL_TO_INT(v) ((jsint)(v) >> 1)
99: #define INT_TO_JSVAL(i) (((jsval)(i) << 1) | JSVAL_INT)
100:
101: /* Convert between boolean and jsval. */
102: #define JSVAL_TO_BOOLEAN(v) ((JSBool)((v) >> JSVAL_TAGBITS))
103: #define BOOLEAN_TO_JSVAL(b) JSVAL_SETTAG((jsval)(b) << JSVAL_TAGBITS, \
104: JSVAL_BOOLEAN)
105:
106: /* A private data pointer (2-byte-aligned) can be stored as an int jsval. */
107: #define JSVAL_TO_PRIVATE(v) ((void *)((v) & ~JSVAL_INT))
108: #define PRIVATE_TO_JSVAL(p) ((jsval)(p) | JSVAL_INT)
109:
110: /* Property attributes, set in JSPropertySpec and passed to API functions. */
111: #define JSPROP_ENUMERATE 0x01 /* property is visible to for/in loop */
112: #define JSPROP_READONLY 0x02 /* not settable: assignment is no-op */
113: #define JSPROP_PERMANENT 0x04 /* property cannot be deleted */
114: #define JSPROP_EXPORTED 0x08 /* property is exported from object */
115: #define JSPROP_GETTER 0x10 /* property holds getter function */
116: #define JSPROP_SETTER 0x20 /* property holds setter function */
117: #define JSPROP_SHARED 0x40 /* don't allocate a value slot for this
118: property; don't copy the property on
119: set of the same-named property in an
120: object that delegates to a prototype
121: containing this property */
122: #define JSPROP_INDEX 0x80 /* name is actually (jsint) index */
123:
124: /* Function flags, set in JSFunctionSpec and passed to JS_NewFunction etc. */
125: #define JSFUN_LAMBDA 0x08 /* expressed, not declared, function */
126: #define JSFUN_GETTER JSPROP_GETTER
127: #define JSFUN_SETTER JSPROP_SETTER
128: #define JSFUN_BOUND_METHOD 0x40 /* bind this to fun->object's parent */
129: #define JSFUN_HEAVYWEIGHT 0x80 /* activation requires a Call object */
130: #define JSFUN_FLAGS_MASK 0xf8 /* overlay JSFUN_* attributes */
131:
132: /*
133: * Well-known JS values. The extern'd variables are initialized when the
134: * first JSContext is created by JS_NewContext (see below).
135: */
136: #define JSVAL_VOID INT_TO_JSVAL(0 - JSVAL_INT_POW2(30))
137: #define JSVAL_NULL OBJECT_TO_JSVAL(0)
138: #define JSVAL_ZERO INT_TO_JSVAL(0)
139: #define JSVAL_ONE INT_TO_JSVAL(1)
140: #define JSVAL_FALSE BOOLEAN_TO_JSVAL(JS_FALSE)
141: #define JSVAL_TRUE BOOLEAN_TO_JSVAL(JS_TRUE)
142:
143: /*
144: * Microseconds since the epoch, midnight, January 1, 1970 UTC. See the
145: * comment in jstypes.h regarding safe int64 usage.
146: */
147: extern JS_PUBLIC_API(int64)
148: JS_Now();
149:
150: /* Don't want to export data, so provide accessors for non-inline jsvals. */
151: extern JS_PUBLIC_API(jsval)
152: JS_GetNaNValue(JSContext *cx);
153:
154: extern JS_PUBLIC_API(jsval)
155: JS_GetNegativeInfinityValue(JSContext *cx);
156:
157: extern JS_PUBLIC_API(jsval)
158: JS_GetPositiveInfinityValue(JSContext *cx);
159:
160: extern JS_PUBLIC_API(jsval)
161: JS_GetEmptyStringValue(JSContext *cx);
162:
163: /*
164: * Format is a string of the following characters (spaces are insignificant),
165: * specifying the tabulated type conversions:
166: *
167: * b JSBool Boolean
168: * c uint16/jschar ECMA uint16, Unicode char
169: * i int32 ECMA int32
170: * u uint32 ECMA uint32
171: * j int32 Rounded int32 (coordinate)
172: * d jsdouble IEEE double
173: * I jsdouble Integral IEEE double
174: * s char * C string
175: * S JSString * Unicode string, accessed by a JSString pointer
176: * W jschar * Unicode character vector, 0-terminated (W for wide)
177: * o JSObject * Object reference
178: * f JSFunction * Function private
179: * v jsval Argument value (no conversion)
180: * * N/A Skip this argument (no vararg)
181: * / N/A End of required arguments
182: *
183: * The variable argument list after format must consist of &b, &c, &s, e.g.,
184: * where those variables have the types given above. For the pointer types
185: * char *, JSString *, and JSObject *, the pointed-at memory returned belongs
186: * to the JS runtime, not to the calling native code. The runtime promises
187: * to keep this memory valid so long as argv refers to allocated stack space
188: * (so long as the native function is active).
189: *
190: * Fewer arguments than format specifies may be passed only if there is a /
191: * in format after the last required argument specifier and argc is at least
192: * the number of required arguments. More arguments than format specifies
193: * may be passed without error; it is up to the caller to deal with trailing
194: * unconverted arguments.
195: */
196: extern JS_PUBLIC_API(JSBool)
197: JS_ConvertArguments(JSContext *cx, uintN argc, jsval *argv, const char *format,
198: ...);
199:
200: #ifdef va_start
201: extern JS_PUBLIC_API(JSBool)
202: JS_ConvertArgumentsVA(JSContext *cx, uintN argc, jsval *argv,
203: const char *format, va_list ap);
204: #endif
205:
206: /*
207: * Inverse of JS_ConvertArguments: scan format and convert trailing arguments
208: * into jsvals, GC-rooted if necessary by the JS stack. Return null on error,
209: * and a pointer to the new argument vector on success. Also return a stack
210: * mark on success via *markp, in which case the caller must eventually clean
211: * up by calling JS_PopArguments.
212: *
213: * Note that the number of actual arguments supplied is specified exclusively
214: * by format, so there is no argc parameter.
215: */
216: extern JS_PUBLIC_API(jsval *)
217: JS_PushArguments(JSContext *cx, void **markp, const char *format, ...);
218:
219: #ifdef va_start
220: extern JS_PUBLIC_API(jsval *)
221: JS_PushArgumentsVA(JSContext *cx, void **markp, const char *format, va_list ap);
222: #endif
223:
224: extern JS_PUBLIC_API(void)
225: JS_PopArguments(JSContext *cx, void *mark);
226:
227: #ifdef JS_ARGUMENT_FORMATTER_DEFINED
228:
229: /*
230: * Add and remove a format string handler for JS_{Convert,Push}Arguments{,VA}.
231: * The handler function has this signature (see jspubtd.h):
232: *
233: * JSBool MyArgumentFormatter(JSContext *cx, const char *format,
234: * JSBool fromJS, jsval **vpp, va_list *app);
235: *
236: * It should return true on success, and return false after reporting an error
237: * or detecting an already-reported error.
238: *
239: * For a given format string, for example "AA", the formatter is called from
240: * JS_ConvertArgumentsVA like so:
241: *
242: * formatter(cx, "AA...", JS_TRUE, &sp, &ap);
243: *
244: * sp points into the arguments array on the JS stack, while ap points into
245: * the stdarg.h va_list on the C stack. The JS_TRUE passed for fromJS tells
246: * the formatter to convert zero or more jsvals at sp to zero or more C values
247: * accessed via pointers-to-values at ap, updating both sp (via *vpp) and ap
248: * (via *app) to point past the converted arguments and their result pointers
249: * on the C stack.
250: *
251: * When called from JS_PushArgumentsVA, the formatter is invoked thus:
252: *
253: * formatter(cx, "AA...", JS_FALSE, &sp, &ap);
254: *
255: * where JS_FALSE for fromJS means to wrap the C values at ap according to the
256: * format specifier and store them at sp, updating ap and sp appropriately.
257: *
258: * The "..." after "AA" is the rest of the format string that was passed into
259: * JS_{Convert,Push}Arguments{,VA}. The actual format trailing substring used
260: * in each Convert or PushArguments call is passed to the formatter, so that
261: * one such function may implement several formats, in order to share code.
262: *
263: * Remove just forgets about any handler associated with format. Add does not
264: * copy format, it points at the string storage allocated by the caller, which
265: * is typically a string constant. If format is in dynamic storage, it is up
266: * to the caller to keep the string alive until Remove is called.
267: */
268: extern JS_PUBLIC_API(JSBool)
269: JS_AddArgumentFormatter(JSContext *cx, const char *format,
270: JSArgumentFormatter formatter);
271:
272: extern JS_PUBLIC_API(void)
273: JS_RemoveArgumentFormatter(JSContext *cx, const char *format);
274:
275: #endif /* JS_ARGUMENT_FORMATTER_DEFINED */
276:
277: extern JS_PUBLIC_API(JSBool)
278: JS_ConvertValue(JSContext *cx, jsval v, JSType type, jsval *vp);
279:
280: extern JS_PUBLIC_API(JSBool)
281: JS_ValueToObject(JSContext *cx, jsval v, JSObject **objp);
282:
283: extern JS_PUBLIC_API(JSFunction *)
284: JS_ValueToFunction(JSContext *cx, jsval v);
285:
286: extern JS_PUBLIC_API(JSFunction *)
287: JS_ValueToConstructor(JSContext *cx, jsval v);
288:
289: extern JS_PUBLIC_API(JSString *)
290: JS_ValueToString(JSContext *cx, jsval v);
291:
292: extern JS_PUBLIC_API(JSBool)
293: JS_ValueToNumber(JSContext *cx, jsval v, jsdouble *dp);
294:
295: /*
296: * Convert a value to a number, then to an int32, according to the ECMA rules
297: * for ToInt32.
298: */
299: extern JS_PUBLIC_API(JSBool)
300: JS_ValueToECMAInt32(JSContext *cx, jsval v, int32 *ip);
301:
302: /*
303: * Convert a value to a number, then to a uint32, according to the ECMA rules
304: * for ToUint32.
305: */
306: extern JS_PUBLIC_API(JSBool)
307: JS_ValueToECMAUint32(JSContext *cx, jsval v, uint32 *ip);
308:
309: /*
310: * Convert a value to a number, then to an int32 if it fits by rounding to
311: * nearest; but failing with an error report if the double is out of range
312: * or unordered.
313: */
314: extern JS_PUBLIC_API(JSBool)
315: JS_ValueToInt32(JSContext *cx, jsval v, int32 *ip);
316:
317: /*
318: * ECMA ToUint16, for mapping a jsval to a Unicode point.
319: */
320: extern JS_PUBLIC_API(JSBool)
321: JS_ValueToUint16(JSContext *cx, jsval v, uint16 *ip);
322:
323: extern JS_PUBLIC_API(JSBool)
324: JS_ValueToBoolean(JSContext *cx, jsval v, JSBool *bp);
325:
326: extern JS_PUBLIC_API(JSType)
327: JS_TypeOfValue(JSContext *cx, jsval v);
328:
329: extern JS_PUBLIC_API(const char *)
330: JS_GetTypeName(JSContext *cx, JSType type);
331:
332: /************************************************************************/
333:
334: /*
335: * Initialization, locking, contexts, and memory allocation.
336: */
337: #define JS_NewRuntime JS_Init
338: #define JS_DestroyRuntime JS_Finish
339: #define JS_LockRuntime JS_Lock
340: #define JS_UnlockRuntime JS_Unlock
341:
342: extern JS_PUBLIC_API(JSRuntime *)
343: JS_NewRuntime(uint32 maxbytes);
344:
345: extern JS_PUBLIC_API(void)
346: JS_DestroyRuntime(JSRuntime *rt);
347:
348: extern JS_PUBLIC_API(void)
349: JS_ShutDown(void);
350:
351: JS_PUBLIC_API(void *)
352: JS_GetRuntimePrivate(JSRuntime *rt);
353:
354: JS_PUBLIC_API(void)
355: JS_SetRuntimePrivate(JSRuntime *rt, void *data);
356:
357: #ifdef JS_THREADSAFE
358:
359: extern JS_PUBLIC_API(void)
360: JS_BeginRequest(JSContext *cx);
361:
362: extern JS_PUBLIC_API(void)
363: JS_EndRequest(JSContext *cx);
364:
365: /* Yield to pending GC operations, regardless of request depth */
366: extern JS_PUBLIC_API(void)
367: JS_YieldRequest(JSContext *cx);
368:
369: extern JS_PUBLIC_API(jsrefcount)
370: JS_SuspendRequest(JSContext *cx);
371:
372: extern JS_PUBLIC_API(void)
373: JS_ResumeRequest(JSContext *cx, jsrefcount saveDepth);
374:
375: #endif /* JS_THREADSAFE */
376:
377: extern JS_PUBLIC_API(void)
378: JS_Lock(JSRuntime *rt);
379:
380: extern JS_PUBLIC_API(void)
381: JS_Unlock(JSRuntime *rt);
382:
383: extern JS_PUBLIC_API(JSContext *)
384: JS_NewContext(JSRuntime *rt, size_t stackChunkSize);
385:
386: extern JS_PUBLIC_API(void)
387: JS_DestroyContext(JSContext *cx);
388:
389: extern JS_PUBLIC_API(void)
390: JS_DestroyContextNoGC(JSContext *cx);
391:
392: extern JS_PUBLIC_API(void)
393: JS_DestroyContextMaybeGC(JSContext *cx);
394:
395: extern JS_PUBLIC_API(void *)
396: JS_GetContextPrivate(JSContext *cx);
397:
398: extern JS_PUBLIC_API(void)
399: JS_SetContextPrivate(JSContext *cx, void *data);
400:
401: extern JS_PUBLIC_API(JSRuntime *)
402: JS_GetRuntime(JSContext *cx);
403:
404: extern JS_PUBLIC_API(JSContext *)
405: JS_ContextIterator(JSRuntime *rt, JSContext **iterp);
406:
407: extern JS_PUBLIC_API(JSVersion)
408: JS_GetVersion(JSContext *cx);
409:
410: extern JS_PUBLIC_API(JSVersion)
411: JS_SetVersion(JSContext *cx, JSVersion version);
412:
413: extern JS_PUBLIC_API(const char *)
414: JS_VersionToString(JSVersion version);
415:
416: extern JS_PUBLIC_API(JSVersion)
417: JS_StringToVersion(const char *string);
418:
419: /*
420: * JS options are orthogonal to version, and may be freely composed with one
421: * another as well as with version.
422: *
423: * JSOPTION_VAROBJFIX is recommended -- see the comments associated with the
424: * prototypes for JS_ExecuteScript, JS_EvaluateScript, etc.
425: */
426: #define JSOPTION_STRICT JS_BIT(0) /* warn on dubious practice */
427: #define JSOPTION_WERROR JS_BIT(1) /* convert warning to error */
428: #define JSOPTION_VAROBJFIX JS_BIT(2) /* make JS_EvaluateScript use
429: the last object on its 'obj'
430: param's scope chain as the
431: ECMA 'variables object' */
432: #define JSOPTION_PRIVATE_IS_NSISUPPORTS \
433: JS_BIT(3) /* context private data points
434: to an nsISupports subclass */
435:
436: extern JS_PUBLIC_API(uint32)
437: JS_GetOptions(JSContext *cx);
438:
439: extern JS_PUBLIC_API(uint32)
440: JS_SetOptions(JSContext *cx, uint32 options);
441:
442: extern JS_PUBLIC_API(uint32)
443: JS_ToggleOptions(JSContext *cx, uint32 options);
444:
445: extern JS_PUBLIC_API(const char *)
446: JS_GetImplementationVersion(void);
447:
448: extern JS_PUBLIC_API(JSObject *)
449: JS_GetGlobalObject(JSContext *cx);
450:
451: extern JS_PUBLIC_API(void)
452: JS_SetGlobalObject(JSContext *cx, JSObject *obj);
453:
454: /*
455: * Initialize standard JS class constructors, prototypes, and any top-level
456: * functions and constants associated with the standard classes (e.g. isNaN
457: * for Number).
458: *
459: * NB: This sets cx's global object to obj if it was null.
460: */
461: extern JS_PUBLIC_API(JSBool)
462: JS_InitStandardClasses(JSContext *cx, JSObject *obj);
463:
464: /*
465: * Resolve id, which must contain either a string or an int, to a standard
466: * class name in obj if possible, defining the class's constructor and/or
467: * prototype and storing true in *resolved. If id does not name a standard
468: * class or a top-level property induced by initializing a standard class,
469: * store false in *resolved and just return true. Return false on error,
470: * as usual for JSBool result-typed API entry points.
471: *
472: * This API can be called directly from a global object class's resolve op,
473: * to define standard classes lazily. The class's enumerate op should call
474: * JS_EnumerateStandardClasses(cx, obj), to define eagerly during for..in
475: * loops any classes not yet resolved lazily.
476: */
477: extern JS_PUBLIC_API(JSBool)
478: JS_ResolveStandardClass(JSContext *cx, JSObject *obj, jsval id,
479: JSBool *resolved);
480:
481: extern JS_PUBLIC_API(JSBool)
482: JS_EnumerateStandardClasses(JSContext *cx, JSObject *obj);
483:
484: extern JS_PUBLIC_API(JSObject *)
485: JS_GetScopeChain(JSContext *cx);
486:
487: extern JS_PUBLIC_API(void *)
488: JS_malloc(JSContext *cx, size_t nbytes);
489:
490: extern JS_PUBLIC_API(void *)
491: JS_realloc(JSContext *cx, void *p, size_t nbytes);
492:
493: extern JS_PUBLIC_API(void)
494: JS_free(JSContext *cx, void *p);
495:
496: extern JS_PUBLIC_API(char *)
497: JS_strdup(JSContext *cx, const char *s);
498:
499: extern JS_PUBLIC_API(jsdouble *)
500: JS_NewDouble(JSContext *cx, jsdouble d);
501:
502: extern JS_PUBLIC_API(JSBool)
503: JS_NewDoubleValue(JSContext *cx, jsdouble d, jsval *rval);
504:
505: extern JS_PUBLIC_API(JSBool)
506: JS_NewNumberValue(JSContext *cx, jsdouble d, jsval *rval);
507:
508: /*
509: * A JS GC root is a pointer to a JSObject *, JSString *, or jsdouble * that
510: * itself points into the GC heap (more recently, we support this extension:
511: * a root may be a pointer to a jsval v for which JSVAL_IS_GCTHING(v) is true).
512: *
513: * Therefore, you never pass JSObject *obj to JS_AddRoot(cx, obj). You always
514: * call JS_AddRoot(cx, &obj), passing obj by reference. And later, before obj
515: * or the structure it is embedded within goes out of scope or is freed, you
516: * must call JS_RemoveRoot(cx, &obj).
517: *
518: * Also, use JS_AddNamedRoot(cx, &structPtr->memberObj, "structPtr->memberObj")
519: * in preference to JS_AddRoot(cx, &structPtr->memberObj), in order to identify
520: * roots by their source callsites. This way, you can find the callsite while
521: * debugging if you should fail to do JS_RemoveRoot(cx, &structPtr->memberObj)
522: * before freeing structPtr's memory.
523: */
524: extern JS_PUBLIC_API(JSBool)
525: JS_AddRoot(JSContext *cx, void *rp);
526:
527: #ifdef NAME_ALL_GC_ROOTS
528: #define JS_DEFINE_TO_TOKEN(def) #def
529: #define JS_DEFINE_TO_STRING(def) JS_DEFINE_TO_TOKEN(def)
530: #define JS_AddRoot(cx,rp) JS_AddNamedRoot((cx), (rp), (__FILE__ ":" JS_TOKEN_TO_STRING(__LINE__))
531: #endif
532:
533: extern JS_PUBLIC_API(JSBool)
534: JS_AddNamedRoot(JSContext *cx, void *rp, const char *name);
535:
536: extern JS_PUBLIC_API(JSBool)
537: JS_AddNamedRootRT(JSRuntime *rt, void *rp, const char *name);
538:
539: extern JS_PUBLIC_API(JSBool)
540: JS_RemoveRoot(JSContext *cx, void *rp);
541:
542: extern JS_PUBLIC_API(JSBool)
543: JS_RemoveRootRT(JSRuntime *rt, void *rp);
544:
545: /*
546: * The last GC thing of each type (object, string, double, external string
547: * types) created on a given context is kept alive until another thing of the
548: * same type is created, using a newborn root in the context. These newborn
549: * roots help native code protect newly-created GC-things from GC invocations
550: * activated before those things can be rooted using local or global roots.
551: *
552: * However, the newborn roots can also entrain great gobs of garbage, so the
553: * JS_GC entry point clears them for the context on which GC is being forced.
554: * Embeddings may need to do likewise for all contexts.
555: *
556: * XXXbe See bug 40757 (http://bugzilla.mozilla.org/show_bug.cgi?id=40757),
557: * which proposes switching (with an #ifdef, alas, if we want to maintain API
558: * compatibility) to a JNI-like extensible local root frame stack model.
559: */
560: extern JS_PUBLIC_API(void)
561: JS_ClearNewbornRoots(JSContext *cx);
562:
563: #ifdef DEBUG
564: extern JS_PUBLIC_API(void)
565: JS_DumpNamedRoots(JSRuntime *rt,
566: void (*dump)(const char *name, void *rp, void *data),
567: void *data);
568: #endif
569:
570: /*
571: * Call JS_MapGCRoots to map the GC's roots table using map(rp, name, data).
572: * The root is pointed at by rp; if the root is unnamed, name is null; data is
573: * supplied from the third parameter to JS_MapGCRoots.
574: *
575: * The map function should return JS_MAP_GCROOT_REMOVE to cause the currently
576: * enumerated root to be removed. To stop enumeration, set JS_MAP_GCROOT_STOP
577: * in the return value. To keep on mapping, return JS_MAP_GCROOT_NEXT. These
578: * constants are flags; you can OR them together.
579: *
580: * This function acquires and releases rt's GC lock around the mapping of the
581: * roots table, so the map function should run to completion in as few cycles
582: * as possible. Of course, map cannot call JS_GC, JS_MaybeGC, JS_BeginRequest,
583: * or any JS API entry point that acquires locks, without double-tripping or
584: * deadlocking on the GC lock.
585: *
586: * JS_MapGCRoots returns the count of roots that were successfully mapped.
587: */
588: #define JS_MAP_GCROOT_NEXT 0 /* continue mapping entries */
589: #define JS_MAP_GCROOT_STOP 1 /* stop mapping entries */
590: #define JS_MAP_GCROOT_REMOVE 2 /* remove and free the current entry */
591:
592: typedef intN
593: (* JS_DLL_CALLBACK JSGCRootMapFun)(void *rp, const char *name, void *data);
594:
595: extern JS_PUBLIC_API(uint32)
596: JS_MapGCRoots(JSRuntime *rt, JSGCRootMapFun map, void *data);
597:
598: extern JS_PUBLIC_API(JSBool)
599: JS_LockGCThing(JSContext *cx, void *thing);
600:
601: extern JS_PUBLIC_API(JSBool)
602: JS_LockGCThingRT(JSRuntime *rt, void *thing);
603:
604: extern JS_PUBLIC_API(JSBool)
605: JS_UnlockGCThing(JSContext *cx, void *thing);
606:
607: extern JS_PUBLIC_API(JSBool)
608: JS_UnlockGCThingRT(JSRuntime *rt, void *thing);
609:
610: /*
611: * For implementors of JSObjectOps.mark, to mark a GC-thing reachable via a
612: * property or other strong ref identified for debugging purposes by name.
613: * The name argument's storage needs to live only as long as the call to
614: * this routine.
615: *
616: * The final arg is used by GC_MARK_DEBUG code to build a ref path through
617: * the GC's live thing graph. Implementors of JSObjectOps.mark should pass
618: * its final arg through to this function when marking all GC-things that are
619: * directly reachable from the object being marked.
620: *
621: * See the JSMarkOp typedef in jspubtd.h, and the JSObjectOps struct below.
622: */
623: extern JS_PUBLIC_API(void)
624: JS_MarkGCThing(JSContext *cx, void *thing, const char *name, void *arg);
625:
626: extern JS_PUBLIC_API(void)
627: JS_GC(JSContext *cx);
628:
629: extern JS_PUBLIC_API(void)
630: JS_MaybeGC(JSContext *cx);
631:
632: extern JS_PUBLIC_API(JSGCCallback)
633: JS_SetGCCallback(JSContext *cx, JSGCCallback cb);
634:
635: extern JS_PUBLIC_API(JSGCCallback)
636: JS_SetGCCallbackRT(JSRuntime *rt, JSGCCallback cb);
637:
638: extern JS_PUBLIC_API(JSBool)
639: JS_IsAboutToBeFinalized(JSContext *cx, void *thing);
640:
641: /*
642: * Add an external string finalizer, one created by JS_NewExternalString (see
643: * below) using a type-code returned from this function, and that understands
644: * how to free or release the memory pointed at by JS_GetStringChars(str).
645: *
646: * Return a nonnegative type index if there is room for finalizer in the
647: * global GC finalizers table, else return -1. If the engine is compiled
648: * JS_THREADSAFE and used in a multi-threaded environment, this function must
649: * be invoked on the primordial thread only, at startup -- or else the entire
650: * program must single-thread itself while loading a module that calls this
651: * function.
652: */
653: extern JS_PUBLIC_API(intN)
654: JS_AddExternalStringFinalizer(JSStringFinalizeOp finalizer);
655:
656: /*
657: * Remove finalizer from the global GC finalizers table, returning its type
658: * code if found, -1 if not found.
659: *
660: * As with JS_AddExternalStringFinalizer, there is a threading restriction
661: * if you compile the engine JS_THREADSAFE: this function may be called for a
662: * given finalizer pointer on only one thread; different threads may call to
663: * remove distinct finalizers safely.
664: *
665: * You must ensure that all strings with finalizer's type have been collected
666: * before calling this function. Otherwise, string data will be leaked by the
667: * GC, for want of a finalizer to call.
668: */
669: extern JS_PUBLIC_API(intN)
670: JS_RemoveExternalStringFinalizer(JSStringFinalizeOp finalizer);
671:
672: /*
673: * Create a new JSString whose chars member refers to external memory, i.e.,
674: * memory requiring special, type-specific finalization. The type code must
675: * be a nonnegative return value from JS_AddExternalStringFinalizer.
676: */
677: extern JS_PUBLIC_API(JSString *)
678: JS_NewExternalString(JSContext *cx, jschar *chars, size_t length, intN type);
679:
680: /*
681: * Returns the external-string finalizer index for this string, or -1 if it is
682: * an "internal" (native to JS engine) string.
683: */
684: extern JS_PUBLIC_API(intN)
685: JS_GetExternalStringGCType(JSRuntime *rt, JSString *str);
686:
687: /************************************************************************/
688:
689: /*
690: * Classes, objects, and properties.
691: */
692:
693: /* For detailed comments on the function pointer types, see jspubtd.h. */
694: struct JSClass {
695: const char *name;
696: uint32 flags;
697:
698: /* Mandatory non-null function pointer members. */
699: JSPropertyOp addProperty;
700: JSPropertyOp delProperty;
701: JSPropertyOp getProperty;
702: JSPropertyOp setProperty;
703: JSEnumerateOp enumerate;
704: JSResolveOp resolve;
705: JSConvertOp convert;
706: JSFinalizeOp finalize;
707:
708: /* Optionally non-null members start here. */
709: JSGetObjectOps getObjectOps;
710: JSCheckAccessOp checkAccess;
711: JSNative call;
712: JSNative construct;
713: JSXDRObjectOp xdrObject;
714: JSHasInstanceOp hasInstance;
715: JSMarkOp mark;
716: jsword spare;
717: };
718:
719: #define JSCLASS_HAS_PRIVATE (1<<0) /* objects have private slot */
720: #define JSCLASS_NEW_ENUMERATE (1<<1) /* has JSNewEnumerateOp hook */
721: #define JSCLASS_NEW_RESOLVE (1<<2) /* has JSNewResolveOp hook */
722: #define JSCLASS_PRIVATE_IS_NSISUPPORTS (1<<3) /* private is (nsISupports *) */
723: #define JSCLASS_SHARE_ALL_PROPERTIES (1<<4) /* all properties are SHARED */
724: #define JSCLASS_NEW_RESOLVE_GETS_START (1<<5) /* JSNewResolveOp gets starting
725: object in prototype chain
726: passed in via *objp in/out
727: parameter */
728:
729: /*
730: * To reserve slots fetched and stored via JS_Get/SetReservedSlot, bitwise-or
731: * JSCLASS_HAS_RESERVED_SLOTS(n) into the initializer for JSClass.flags, where
732: * n is a constant in [1, 255]. Reserved slots are indexed from 0 to n-1.
733: */
734: #define JSCLASS_RESERVED_SLOTS_SHIFT 8 /* room for 8 flags below */
735: #define JSCLASS_RESERVED_SLOTS_WIDTH 8 /* and 16 above this field */
736: #define JSCLASS_RESERVED_SLOTS_MASK JS_BITMASK(JSCLASS_RESERVED_SLOTS_WIDTH)
737: #define JSCLASS_HAS_RESERVED_SLOTS(n) (((n) & JSCLASS_RESERVED_SLOTS_MASK) \
738: << JSCLASS_RESERVED_SLOTS_SHIFT)
739: #define JSCLASS_RESERVED_SLOTS(clasp) (((clasp)->flags \
740: >> JSCLASS_RESERVED_SLOTS_SHIFT) \
741: & JSCLASS_RESERVED_SLOTS_MASK)
742:
743: /* Initializer for unused members of statically initialized JSClass structs. */
744: #define JSCLASS_NO_OPTIONAL_MEMBERS 0,0,0,0,0,0,0,0
745:
746: /* For detailed comments on these function pointer types, see jspubtd.h. */
747: struct JSObjectOps {
748: /* Mandatory non-null function pointer members. */
749: JSNewObjectMapOp newObjectMap;
750: JSObjectMapOp destroyObjectMap;
751: JSLookupPropOp lookupProperty;
752: JSDefinePropOp defineProperty;
753: JSPropertyIdOp getProperty;
754: JSPropertyIdOp setProperty;
755: JSAttributesOp getAttributes;
756: JSAttributesOp setAttributes;
757: JSPropertyIdOp deleteProperty;
758: JSConvertOp defaultValue;
759: JSNewEnumerateOp enumerate;
760: JSCheckAccessIdOp checkAccess;
761:
762: /* Optionally non-null members start here. */
763: JSObjectOp thisObject;
764: JSPropertyRefOp dropProperty;
765: JSNative call;
766: JSNative construct;
767: JSXDRObjectOp xdrObject;
768: JSHasInstanceOp hasInstance;
769: JSSetObjectSlotOp setProto;
770: JSSetObjectSlotOp setParent;
771: JSMarkOp mark;
772: JSFinalizeOp clear;
773: JSGetRequiredSlotOp getRequiredSlot;
774: JSSetRequiredSlotOp setRequiredSlot;
775: };
776:
777: /*
778: * Classes that expose JSObjectOps via a non-null getObjectOps class hook may
779: * derive a property structure from this struct, return a pointer to it from
780: * lookupProperty and defineProperty, and use the pointer to avoid rehashing
781: * in getAttributes and setAttributes.
782: *
783: * The jsid type contains either an int jsval (see JSVAL_IS_INT above), or an
784: * internal pointer that is opaque to users of this API, but which users may
785: * convert from and to a jsval using JS_ValueToId and JS_IdToValue.
786: */
787: struct JSProperty {
788: jsid id;
789: };
790:
791: struct JSIdArray {
792: jsint length;
793: jsid vector[1]; /* actually, length jsid words */
794: };
795:
796: extern JS_PUBLIC_API(void)
797: JS_DestroyIdArray(JSContext *cx, JSIdArray *ida);
798:
799: extern JS_PUBLIC_API(JSBool)
800: JS_ValueToId(JSContext *cx, jsval v, jsid *idp);
801:
802: extern JS_PUBLIC_API(JSBool)
803: JS_IdToValue(JSContext *cx, jsid id, jsval *vp);
804:
805: #define JSRESOLVE_QUALIFIED 0x01 /* resolve a qualified property id */
806: #define JSRESOLVE_ASSIGNING 0x02 /* resolve on the left of assignment */
807:
808: extern JS_PUBLIC_API(JSBool)
809: JS_PropertyStub(JSContext *cx, JSObject *obj, jsval id, jsval *vp);
810:
811: extern JS_PUBLIC_API(JSBool)
812: JS_EnumerateStub(JSContext *cx, JSObject *obj);
813:
814: extern JS_PUBLIC_API(JSBool)
815: JS_ResolveStub(JSContext *cx, JSObject *obj, jsval id);
816:
817: extern JS_PUBLIC_API(JSBool)
818: JS_ConvertStub(JSContext *cx, JSObject *obj, JSType type, jsval *vp);
819:
820: extern JS_PUBLIC_API(void)
821: JS_FinalizeStub(JSContext *cx, JSObject *obj);
822:
823: struct JSConstDoubleSpec {
824: jsdouble dval;
825: const char *name;
826: uint8 flags;
827: uint8 spare[3];
828: };
829:
830: /*
831: * To define an array element rather than a named property member, cast the
832: * element's index to (const char *) and initialize name with it, and set the
833: * JSPROP_INDEX bit in flags.
834: */
835: struct JSPropertySpec {
836: const char *name;
837: int8 tinyid;
838: uint8 flags;
839: JSPropertyOp getter;
840: JSPropertyOp setter;
841: };
842:
843: struct JSFunctionSpec {
844: const char *name;
845: JSNative call;
846: uint8 nargs;
847: uint8 flags;
848: uint16 extra; /* number of arg slots for local GC roots */
849: };
850:
851: extern JS_PUBLIC_API(JSObject *)
852: JS_InitClass(JSContext *cx, JSObject *obj, JSObject *parent_proto,
853: JSClass *clasp, JSNative constructor, uintN nargs,
854: JSPropertySpec *ps, JSFunctionSpec *fs,
855: JSPropertySpec *static_ps, JSFunctionSpec *static_fs);
856:
857: #ifdef JS_THREADSAFE
858: extern JS_PUBLIC_API(JSClass *)
859: JS_GetClass(JSContext *cx, JSObject *obj);
860:
861: #define JS_GET_CLASS(cx,obj) JS_GetClass(cx, obj)
862: #else
863: extern JS_PUBLIC_API(JSClass *)
864: JS_GetClass(JSObject *obj);
865:
866: #define JS_GET_CLASS(cx,obj) JS_GetClass(obj)
867: #endif
868:
869: extern JS_PUBLIC_API(JSBool)
870: JS_InstanceOf(JSContext *cx, JSObject *obj, JSClass *clasp, jsval *argv);
871:
872: extern JS_PUBLIC_API(void *)
873: JS_GetPrivate(JSContext *cx, JSObject *obj);
874:
875: extern JS_PUBLIC_API(JSBool)
876: JS_SetPrivate(JSContext *cx, JSObject *obj, void *data);
877:
878: extern JS_PUBLIC_API(void *)
879: JS_GetInstancePrivate(JSContext *cx, JSObject *obj, JSClass *clasp,
880: jsval *argv);
881:
882: extern JS_PUBLIC_API(JSObject *)
883: JS_GetPrototype(JSContext *cx, JSObject *obj);
884:
885: extern JS_PUBLIC_API(JSBool)
886: JS_SetPrototype(JSContext *cx, JSObject *obj, JSObject *proto);
887:
888: extern JS_PUBLIC_API(JSObject *)
889: JS_GetParent(JSContext *cx, JSObject *obj);
890:
891: extern JS_PUBLIC_API(JSBool)
892: JS_SetParent(JSContext *cx, JSObject *obj, JSObject *parent);
893:
894: extern JS_PUBLIC_API(JSObject *)
895: JS_GetConstructor(JSContext *cx, JSObject *proto);
896:
897: extern JS_PUBLIC_API(JSObject *)
898: JS_NewObject(JSContext *cx, JSClass *clasp, JSObject *proto, JSObject *parent);
899:
900: extern JS_PUBLIC_API(JSBool)
901: JS_SealObject(JSContext *cx, JSObject *obj, JSBool deep);
902:
903: extern JS_PUBLIC_API(JSBool)
904: JS_UnsealObject(JSContext *cx, JSObject *obj, JSBool deep);
905:
906: extern JS_PUBLIC_API(JSObject *)
907: JS_ConstructObject(JSContext *cx, JSClass *clasp, JSObject *proto,
908: JSObject *parent);
909:
910: extern JS_PUBLIC_API(JSObject *)
911: JS_ConstructObjectWithArguments(JSContext *cx, JSClass *clasp, JSObject *proto,
912: JSObject *parent, uintN argc, jsval *argv);
913:
914: extern JS_PUBLIC_API(JSObject *)
915: JS_DefineObject(JSContext *cx, JSObject *obj, const char *name, JSClass *clasp,
916: JSObject *proto, uintN attrs);
917:
918: extern JS_PUBLIC_API(JSBool)
919: JS_DefineConstDoubles(JSContext *cx, JSObject *obj, JSConstDoubleSpec *cds);
920:
921: extern JS_PUBLIC_API(JSBool)
922: JS_DefineProperties(JSContext *cx, JSObject *obj, JSPropertySpec *ps);
923:
924: extern JS_PUBLIC_API(JSBool)
925: JS_DefineProperty(JSContext *cx, JSObject *obj, const char *name, jsval value,
926: JSPropertyOp getter, JSPropertyOp setter, uintN attrs);
927:
928: /*
929: * Determine the attributes (JSPROP_* flags) of a property on a given object.
930: *
931: * If the object does not have a property by that name, *foundp will be
932: * JS_FALSE and the value of *attrsp is undefined.
933: */
934: extern JS_PUBLIC_API(JSBool)
935: JS_GetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name,
936: uintN *attrsp, JSBool *foundp);
937:
938: /*
939: * Set the attributes of a property on a given object.
940: *
941: * If the object does not have a property by that name, *foundp will be
942: * JS_FALSE and nothing will be altered.
943: */
944: extern JS_PUBLIC_API(JSBool)
945: JS_SetPropertyAttributes(JSContext *cx, JSObject *obj, const char *name,
946: uintN attrs, JSBool *foundp);
947:
948: extern JS_PUBLIC_API(JSBool)
949: JS_DefinePropertyWithTinyId(JSContext *cx, JSObject *obj, const char *name,
950: int8 tinyid, jsval value,
951: JSPropertyOp getter, JSPropertyOp setter,
952: uintN attrs);
953:
954: extern JS_PUBLIC_API(JSBool)
955: JS_AliasProperty(JSContext *cx, JSObject *obj, const char *name,
956: const char *alias);
957:
958: extern JS_PUBLIC_API(JSBool)
959: JS_LookupProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);
960:
961: extern JS_PUBLIC_API(JSBool)
962: JS_GetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);
963:
964: extern JS_PUBLIC_API(JSBool)
965: JS_SetProperty(JSContext *cx, JSObject *obj, const char *name, jsval *vp);
966:
967: extern JS_PUBLIC_API(JSBool)
968: JS_DeleteProperty(JSContext *cx, JSObject *obj, const char *name);
969:
970: extern JS_PUBLIC_API(JSBool)
971: JS_DeleteProperty2(JSContext *cx, JSObject *obj, const char *name,
972: jsval *rval);
973:
974: extern JS_PUBLIC_API(JSBool)
975: JS_DefineUCProperty(JSContext *cx, JSObject *obj,
976: const jschar *name, size_t namelen, jsval value,
977: JSPropertyOp getter, JSPropertyOp setter,
978: uintN attrs);
979:
980: /*
981: * Determine the attributes (JSPROP_* flags) of a property on a given object.
982: *
983: * If the object does not have a property by that name, *foundp will be
984: * JS_FALSE and the value of *attrsp is undefined.
985: */
986: extern JS_PUBLIC_API(JSBool)
987: JS_GetUCPropertyAttributes(JSContext *cx, JSObject *obj,
988: const jschar *name, size_t namelen,
989: uintN *attrsp, JSBool *foundp);
990:
991: /*
992: * Set the attributes of a property on a given object.
993: *
994: * If the object does not have a property by that name, *foundp will be
995: * JS_FALSE and nothing will be altered.
996: */
997: extern JS_PUBLIC_API(JSBool)
998: JS_SetUCPropertyAttributes(JSContext *cx, JSObject *obj,
999: const jschar *name, size_t namelen,
1000: uintN attrs, JSBool *foundp);
1001:
1002:
1003: extern JS_PUBLIC_API(JSBool)
1004: JS_DefineUCPropertyWithTinyId(JSContext *cx, JSObject *obj,
1005: const jschar *name, size_t namelen,
1006: int8 tinyid, jsval value,
1007: JSPropertyOp getter, JSPropertyOp setter,
1008: uintN attrs);
1009:
1010: extern JS_PUBLIC_API(JSBool)
1011: JS_LookupUCProperty(JSContext *cx, JSObject *obj,
1012: const jschar *name, size_t namelen,
1013: jsval *vp);
1014:
1015: extern JS_PUBLIC_API(JSBool)
1016: JS_GetUCProperty(JSContext *cx, JSObject *obj,
1017: const jschar *name, size_t namelen,
1018: jsval *vp);
1019:
1020: extern JS_PUBLIC_API(JSBool)
1021: JS_SetUCProperty(JSContext *cx, JSObject *obj,
1022: const jschar *name, size_t namelen,
1023: jsval *vp);
1024:
1025: extern JS_PUBLIC_API(JSBool)
1026: JS_DeleteUCProperty2(JSContext *cx, JSObject *obj,
1027: const jschar *name, size_t namelen,
1028: jsval *rval);
1029:
1030: extern JS_PUBLIC_API(JSObject *)
1031: JS_NewArrayObject(JSContext *cx, jsint length, jsval *vector);
1032:
1033: extern JS_PUBLIC_API(JSBool)
1034: JS_IsArrayObject(JSContext *cx, JSObject *obj);
1035:
1036: extern JS_PUBLIC_API(JSBool)
1037: JS_GetArrayLength(JSContext *cx, JSObject *obj, jsuint *lengthp);
1038:
1039: extern JS_PUBLIC_API(JSBool)
1040: JS_SetArrayLength(JSContext *cx, JSObject *obj, jsuint length);
1041:
1042: extern JS_PUBLIC_API(JSBool)
1043: JS_HasArrayLength(JSContext *cx, JSObject *obj, jsuint *lengthp);
1044:
1045: extern JS_PUBLIC_API(JSBool)
1046: JS_DefineElement(JSContext *cx, JSObject *obj, jsint index, jsval value,
1047: JSPropertyOp getter, JSPropertyOp setter, uintN attrs);
1048:
1049: extern JS_PUBLIC_API(JSBool)
1050: JS_AliasElement(JSContext *cx, JSObject *obj, const char *name, jsint alias);
1051:
1052: extern JS_PUBLIC_API(JSBool)
1053: JS_LookupElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp);
1054:
1055: extern JS_PUBLIC_API(JSBool)
1056: JS_GetElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp);
1057:
1058: extern JS_PUBLIC_API(JSBool)
1059: JS_SetElement(JSContext *cx, JSObject *obj, jsint index, jsval *vp);
1060:
1061: extern JS_PUBLIC_API(JSBool)
1062: JS_DeleteElement(JSContext *cx, JSObject *obj, jsint index);
1063:
1064: extern JS_PUBLIC_API(JSBool)
1065: JS_DeleteElement2(JSContext *cx, JSObject *obj, jsint index, jsval *rval);
1066:
1067: extern JS_PUBLIC_API(void)
1068: JS_ClearScope(JSContext *cx, JSObject *obj);
1069:
1070: extern JS_PUBLIC_API(JSIdArray *)
1071: JS_Enumerate(JSContext *cx, JSObject *obj);
1072:
1073: extern JS_PUBLIC_API(JSBool)
1074: JS_CheckAccess(JSContext *cx, JSObject *obj, jsid id, JSAccessMode mode,
1075: jsval *vp, uintN *attrsp);
1076:
1077: extern JS_PUBLIC_API(JSCheckAccessOp)
1078: JS_SetCheckObjectAccessCallback(JSRuntime *rt, JSCheckAccessOp acb);
1079:
1080: extern JS_PUBLIC_API(JSBool)
1081: JS_GetReservedSlot(JSContext *cx, JSObject *obj, uint32 index, jsval *vp);
1082:
1083: extern JS_PUBLIC_API(JSBool)
1084: JS_SetReservedSlot(JSContext *cx, JSObject *obj, uint32 index, jsval v);
1085:
1086: /************************************************************************/
1087:
1088: /*
1089: * Security protocol.
1090: */
1091: struct JSPrincipals {
1092: char *codebase;
1093: void * (* JS_DLL_CALLBACK getPrincipalArray)(JSContext *cx, JSPrincipals *);
1094: JSBool (* JS_DLL_CALLBACK globalPrivilegesEnabled)(JSContext *cx, JSPrincipals *);
1095:
1096: /* Don't call "destroy"; use reference counting macros below. */
1097: uintN refcount;
1098: void (* JS_DLL_CALLBACK destroy)(JSContext *cx, struct JSPrincipals *);
1099: };
1100:
1101: #define JSPRINCIPALS_HOLD(cx, principals) \
1102: ((principals)->refcount++)
1103: #define JSPRINCIPALS_DROP(cx, principals) \
1104: ((--((principals)->refcount) == 0) \
1105: ? (*(principals)->destroy)((cx), (principals)) \
1106: : (void) 0)
1107:
1108: extern JS_PUBLIC_API(JSPrincipalsTranscoder)
1109: JS_SetPrincipalsTranscoder(JSRuntime *rt, JSPrincipalsTranscoder px);
1110:
1111: /************************************************************************/
1112:
1113: /*
1114: * Functions and scripts.
1115: */
1116: extern JS_PUBLIC_API(JSFunction *)
1117: JS_NewFunction(JSContext *cx, JSNative call, uintN nargs, uintN flags,
1118: JSObject *parent, const char *name);
1119:
1120: extern JS_PUBLIC_API(JSObject *)
1121: JS_GetFunctionObject(JSFunction *fun);
1122:
1123: /*
1124: * Deprecated, useful only for diagnostics. Use JS_GetFunctionId instead for
1125: * anonymous vs. "anonymous" disambiguation and Unicode fidelity.
1126: */
1127: extern JS_PUBLIC_API(const char *)
1128: JS_GetFunctionName(JSFunction *fun);
1129:
1130: /*
1131: * Return the function's identifier as a JSString, or null if fun is unnamed.
1132: * The returned string lives as long as fun, so you don't need to root a saved
1133: * reference to it if fun is well-connected or rooted, and provided you bound
1134: * the use of the saved reference by fun's lifetime.
1135: *
1136: * Prefer JS_GetFunctionId over JS_GetFunctionName because it returns null for
1137: * truly anonymous functions, and because it doesn't chop to ISO-Latin-1 chars
1138: * from UTF-16-ish jschars.
1139: */
1140: extern JS_PUBLIC_API(JSString *)
1141: JS_GetFunctionId(JSFunction *fun);
1142:
1143: /*
1144: * Return JSFUN_* flags for fun.
1145: */
1146: extern JS_PUBLIC_API(uintN)
1147: JS_GetFunctionFlags(JSFunction *fun);
1148:
1149: /*
1150: * Infallible predicate to test whether obj is a function object (faster than
1151: * comparing obj's class name to "Function", but equivalent unless someone has
1152: * overwritten the "Function" identifier with a different constructor and then
1153: * created instances using that constructor that might be passed in as obj).
1154: */
1155: extern JS_PUBLIC_API(JSBool)
1156: JS_ObjectIsFunction(JSContext *cx, JSObject *obj);
1157:
1158: extern JS_PUBLIC_API(JSBool)
1159: JS_DefineFunctions(JSContext *cx, JSObject *obj, JSFunctionSpec *fs);
1160:
1161: extern JS_PUBLIC_API(JSFunction *)
1162: JS_DefineFunction(JSContext *cx, JSObject *obj, const char *name, JSNative call,
1163: uintN nargs, uintN attrs);
1164:
1165: extern JS_PUBLIC_API(JSObject *)
1166: JS_CloneFunctionObject(JSContext *cx, JSObject *funobj, JSObject *parent);
1167:
1168: /*
1169: * Given a buffer, return JS_FALSE if the buffer might become a valid
1170: * javascript statement with the addition of more lines. Otherwise return
1171: * JS_TRUE. The intent is to support interactive compilation - accumulate
1172: * lines in a buffer until JS_BufferIsCompilableUnit is true, then pass it to
1173: * the compiler.
1174: */
1175: extern JS_PUBLIC_API(JSBool)
1176: JS_BufferIsCompilableUnit(JSContext *cx, JSObject *obj,
1177: const char *bytes, size_t length);
1178:
1179: /*
1180: * The JSScript objects returned by the following functions refer to string and
1181: * other kinds of literals, including doubles and RegExp objects. These
1182: * literals are vulnerable to garbage collection; to root script objects and
1183: * prevent literals from being collected, create a rootable object using
1184: * JS_NewScriptObject, and root the resulting object using JS_Add[Named]Root.
1185: */
1186: extern JS_PUBLIC_API(JSScript *)
1187: JS_CompileScript(JSContext *cx, JSObject *obj,
1188: const char *bytes, size_t length,
1189: const char *filename, uintN lineno);
1190:
1191: extern JS_PUBLIC_API(JSScript *)
1192: JS_CompileScriptForPrincipals(JSContext *cx, JSObject *obj,
1193: JSPrincipals *principals,
1194: const char *bytes, size_t length,
1195: const char *filename, uintN lineno);
1196:
1197: extern JS_PUBLIC_API(JSScript *)
1198: JS_CompileUCScript(JSContext *cx, JSObject *obj,
1199: const jschar *chars, size_t length,
1200: const char *filename, uintN lineno);
1201:
1202: extern JS_PUBLIC_API(JSScript *)
1203: JS_CompileUCScriptForPrincipals(JSContext *cx, JSObject *obj,
1204: JSPrincipals *principals,
1205: const jschar *chars, size_t length,
1206: const char *filename, uintN lineno);
1207:
1208: extern JS_PUBLIC_API(JSScript *)
1209: JS_CompileFile(JSContext *cx, JSObject *obj, const char *filename);
1210:
1211: extern JS_PUBLIC_API(JSScript *)
1212: JS_CompileFileHandle(JSContext *cx, JSObject *obj, const char *filename,
1213: FILE *fh);
1214:
1215: extern JS_PUBLIC_API(JSScript *)
1216: JS_CompileFileHandleForPrincipals(JSContext *cx, JSObject *obj,
1217: const char *filename, FILE *fh,
1218: JSPrincipals *principals);
1219:
1220: /*
1221: * NB: you must use JS_NewScriptObject and root a pointer to its return value
1222: * in order to keep a JSScript and its atoms safe from garbage collection after
1223: * creating the script via JS_Compile* and before a JS_ExecuteScript* call.
1224: * E.g., and without error checks:
1225: *
1226: * JSScript *script = JS_CompileFile(cx, global, filename);
1227: * JSObject *scrobj = JS_NewScriptObject(cx, script);
1228: * JS_AddNamedRoot(cx, &scrobj, "scrobj");
1229: * do {
1230: * jsval result;
1231: * JS_ExecuteScript(cx, global, script, &result);
1232: * JS_GC();
1233: * } while (!JSVAL_IS_BOOLEAN(result) || JSVAL_TO_BOOLEAN(result));
1234: * JS_RemoveRoot(cx, &scrobj);
1235: */
1236: extern JS_PUBLIC_API(JSObject *)
1237: JS_NewScriptObject(JSContext *cx, JSScript *script);
1238:
1239: /*
1240: * Infallible getter for a script's object. If JS_NewScriptObject has not been
1241: * called on script yet, the return value will be null.
1242: */
1243: extern JS_PUBLIC_API(JSObject *)
1244: JS_GetScriptObject(JSScript *script);
1245:
1246: extern JS_PUBLIC_API(void)
1247: JS_DestroyScript(JSContext *cx, JSScript *script);
1248:
1249: extern JS_PUBLIC_API(JSFunction *)
1250: JS_CompileFunction(JSContext *cx, JSObject *obj, const char *name,
1251: uintN nargs, const char **argnames,
1252: const char *bytes, size_t length,
1253: const char *filename, uintN lineno);
1254:
1255: extern JS_PUBLIC_API(JSFunction *)
1256: JS_CompileFunctionForPrincipals(JSContext *cx, JSObject *obj,
1257: JSPrincipals *principals, const char *name,
1258: uintN nargs, const char **argnames,
1259: const char *bytes, size_t length,
1260: const char *filename, uintN lineno);
1261:
1262: extern JS_PUBLIC_API(JSFunction *)
1263: JS_CompileUCFunction(JSContext *cx, JSObject *obj, const char *name,
1264: uintN nargs, const char **argnames,
1265: const jschar *chars, size_t length,
1266: const char *filename, uintN lineno);
1267:
1268: extern JS_PUBLIC_API(JSFunction *)
1269: JS_CompileUCFunctionForPrincipals(JSContext *cx, JSObject *obj,
1270: JSPrincipals *principals, const char *name,
1271: uintN nargs, const char **argnames,
1272: const jschar *chars, size_t length,
1273: const char *filename, uintN lineno);
1274:
1275: extern JS_PUBLIC_API(JSString *)
1276: JS_DecompileScript(JSContext *cx, JSScript *script, const char *name,
1277: uintN indent);
1278:
1279: /*
1280: * API extension: OR this into indent to avoid pretty-printing the decompiled
1281: * source resulting from JS_DecompileFunction{,Body}.
1282: */
1283: #define JS_DONT_PRETTY_PRINT ((uintN)0x8000)
1284:
1285: extern JS_PUBLIC_API(JSString *)
1286: JS_DecompileFunction(JSContext *cx, JSFunction *fun, uintN indent);
1287:
1288: extern JS_PUBLIC_API(JSString *)
1289: JS_DecompileFunctionBody(JSContext *cx, JSFunction *fun, uintN indent);
1290:
1291: /*
1292: * NB: JS_ExecuteScript, JS_ExecuteScriptPart, and the JS_Evaluate*Script*
1293: * quadruplets all use the obj parameter as the initial scope chain header,
1294: * the 'this' keyword value, and the variables object (ECMA parlance for where
1295: * 'var' and 'function' bind names) of the execution context for script.
1296: *
1297: * Using obj as the variables object is problematic if obj's parent (which is
1298: * the scope chain link; see JS_SetParent and JS_NewObject) is not null: in
1299: * this case, variables created by 'var x = 0', e.g., go in obj, but variables
1300: * created by assignment to an unbound id, 'x = 0', go in the last object on
1301: * the scope chain linked by parent.
1302: *
1303: * ECMA calls that last scoping object the "global object", but note that many
1304: * embeddings have several such objects. ECMA requires that "global code" be
1305: * executed with the variables object equal to this global object. But these
1306: * JS API entry points provide freedom to execute code against a "sub-global",
1307: * i.e., a parented or scoped object, in which case the variables object will
1308: * differ from the last object on the scope chain, resulting in confusing and
1309: * non-ECMA explicit vs. implicit variable creation.
1310: *
1311: * Caveat embedders: unless you already depend on this buggy variables object
1312: * binding behavior, you should call JS_SetOptions(cx, JSOPTION_VAROBJFIX) or
1313: * JS_SetOptions(cx, JS_GetOptions(cx) | JSOPTION_VAROBJFIX) -- the latter if
1314: * someone may have set other options on cx already -- for each context in the
1315: * application, if you pass parented objects as the obj parameter, or may ever
1316: * pass such objects in the future.
1317: *
1318: * Why a runtime option? The alternative is to add six or so new API entry
1319: * points with signatures matching the following six, and that doesn't seem
1320: * worth the code bloat cost. Such new entry points would probably have less
1321: * obvious names, too, so would not tend to be used. The JS_SetOption call,
1322: * OTOH, can be more easily hacked into existing code that does not depend on
1323: * the bug; such code can continue to use the familiar JS_EvaluateScript,
1324: * etc., entry points.
1325: */
1326: extern JS_PUBLIC_API(JSBool)
1327: JS_ExecuteScript(JSContext *cx, JSObject *obj, JSScript *script, jsval *rval);
1328:
1329: /*
1330: * Execute either the function-defining prolog of a script, or the script's
1331: * main body, but not both.
1332: */
1333: typedef enum JSExecPart { JSEXEC_PROLOG, JSEXEC_MAIN } JSExecPart;
1334:
1335: extern JS_PUBLIC_API(JSBool)
1336: JS_ExecuteScriptPart(JSContext *cx, JSObject *obj, JSScript *script,
1337: JSExecPart part, jsval *rval);
1338:
1339: extern JS_PUBLIC_API(JSBool)
1340: JS_EvaluateScript(JSContext *cx, JSObject *obj,
1341: const char *bytes, uintN length,
1342: const char *filename, uintN lineno,
1343: jsval *rval);
1344:
1345: extern JS_PUBLIC_API(JSBool)
1346: JS_EvaluateScriptForPrincipals(JSContext *cx, JSObject *obj,
1347: JSPrincipals *principals,
1348: const char *bytes, uintN length,
1349: const char *filename, uintN lineno,
1350: jsval *rval);
1351:
1352: extern JS_PUBLIC_API(JSBool)
1353: JS_EvaluateUCScript(JSContext *cx, JSObject *obj,
1354: const jschar *chars, uintN length,
1355: const char *filename, uintN lineno,
1356: jsval *rval);
1357:
1358: extern JS_PUBLIC_API(JSBool)
1359: JS_EvaluateUCScriptForPrincipals(JSContext *cx, JSObject *obj,
1360: JSPrincipals *principals,
1361: const jschar *chars, uintN length,
1362: const char *filename, uintN lineno,
1363: jsval *rval);
1364:
1365: extern JS_PUBLIC_API(JSBool)
1366: JS_CallFunction(JSContext *cx, JSObject *obj, JSFunction *fun, uintN argc,
1367: jsval *argv, jsval *rval);
1368:
1369: extern JS_PUBLIC_API(JSBool)
1370: JS_CallFunctionName(JSContext *cx, JSObject *obj, const char *name, uintN argc,
1371: jsval *argv, jsval *rval);
1372:
1373: extern JS_PUBLIC_API(JSBool)
1374: JS_CallFunctionValue(JSContext *cx, JSObject *obj, jsval fval, uintN argc,
1375: jsval *argv, jsval *rval);
1376:
1377: extern JS_PUBLIC_API(JSBranchCallback)
1378: JS_SetBranchCallback(JSContext *cx, JSBranchCallback cb);
1379:
1380: extern JS_PUBLIC_API(JSBool)
1381: JS_IsRunning(JSContext *cx);
1382:
1383: extern JS_PUBLIC_API(JSBool)
1384: JS_IsConstructing(JSContext *cx);
1385:
1386: /*
1387: * Returns true if a script is executing and its current bytecode is a set
1388: * (assignment) operation, even if there are native (no script) stack frames
1389: * between the script and the caller to JS_IsAssigning.
1390: */
1391: extern JS_FRIEND_API(JSBool)
1392: JS_IsAssigning(JSContext *cx);
1393:
1394: /*
1395: * Set the second return value, which should be a string or int jsval that
1396: * identifies a property in the returned object, to form an ECMA reference
1397: * type value (obj, id). Only native methods can return reference types,
1398: * and if the returned value is used on the left-hand side of an assignment
1399: * op, the identified property will be set. If the return value is in an
1400: * r-value, the interpreter just gets obj[id]'s value.
1401: */
1402: extern JS_PUBLIC_API(void)
1403: JS_SetCallReturnValue2(JSContext *cx, jsval v);
1404:
1405: /************************************************************************/
1406:
1407: /*
1408: * Strings.
1409: *
1410: * NB: JS_NewString takes ownership of bytes on success, avoiding a copy; but
1411: * on error (signified by null return), it leaves bytes owned by the caller.
1412: * So the caller must free bytes in the error case, if it has no use for them.
1413: * In contrast, all the JS_New*StringCopy* functions do not take ownership of
1414: * the character memory passed to them -- they copy it.
1415: */
1416: extern JS_PUBLIC_API(JSString *)
1417: JS_NewString(JSContext *cx, char *bytes, size_t length);
1418:
1419: extern JS_PUBLIC_API(JSString *)
1420: JS_NewStringCopyN(JSContext *cx, const char *s, size_t n);
1421:
1422: extern JS_PUBLIC_API(JSString *)
1423: JS_NewStringCopyZ(JSContext *cx, const char *s);
1424:
1425: extern JS_PUBLIC_API(JSString *)
1426: JS_InternString(JSContext *cx, const char *s);
1427:
1428: extern JS_PUBLIC_API(JSString *)
1429: JS_NewUCString(JSContext *cx, jschar *chars, size_t length);
1430:
1431: extern JS_PUBLIC_API(JSString *)
1432: JS_NewUCStringCopyN(JSContext *cx, const jschar *s, size_t n);
1433:
1434: extern JS_PUBLIC_API(JSString *)
1435: JS_NewUCStringCopyZ(JSContext *cx, const jschar *s);
1436:
1437: extern JS_PUBLIC_API(JSString *)
1438: JS_InternUCStringN(JSContext *cx, const jschar *s, size_t length);
1439:
1440: extern JS_PUBLIC_API(JSString *)
1441: JS_InternUCString(JSContext *cx, const jschar *s);
1442:
1443: extern JS_PUBLIC_API(char *)
1444: JS_GetStringBytes(JSString *str);
1445:
1446: extern JS_PUBLIC_API(jschar *)
1447: JS_GetStringChars(JSString *str);
1448:
1449: extern JS_PUBLIC_API(size_t)
1450: JS_GetStringLength(JSString *str);
1451:
1452: extern JS_PUBLIC_API(intN)
1453: JS_CompareStrings(JSString *str1, JSString *str2);
1454:
1455: /*
1456: * Mutable string support. A string's characters are never mutable in this JS
1457: * implementation, but a growable string has a buffer that can be reallocated,
1458: * and a dependent string is a substring of another (growable, dependent, or
1459: * immutable) string. The direct data members of the (opaque to API clients)
1460: * JSString struct may be changed in a single-threaded way for growable and
1461: * dependent strings.
1462: *
1463: * Therefore mutable strings cannot be used by more than one thread at a time.
1464: * You may call JS_MakeStringImmutable to convert the string from a mutable
1465: * (growable or dependent) string to an immutable (and therefore thread-safe)
1466: * string. The engine takes care of converting growable and dependent strings
1467: * to immutable for you if you store strings in multi-threaded objects using
1468: * JS_SetProperty or kindred API entry points.
1469: *
1470: * If you store a JSString pointer in a native data structure that is (safely)
1471: * accessible to multiple threads, you must call JS_MakeStringImmutable before
1472: * retiring the store.
1473: */
1474: extern JS_PUBLIC_API(JSString *)
1475: JS_NewGrowableString(JSContext *cx, jschar *chars, size_t length);
1476:
1477: /*
1478: * Create a dependent string, i.e., a string that owns no character storage,
1479: * but that refers to a slice of another string's chars. Dependent strings
1480: * are mutable by definition, so the thread safety comments above apply.
1481: */
1482: extern JS_PUBLIC_API(JSString *)
1483: JS_NewDependentString(JSContext *cx, JSString *str, size_t start,
1484: size_t length);
1485:
1486: /*
1487: * Concatenate two strings, resulting in a new growable string. If you create
1488: * the left string and pass it to JS_ConcatStrings on a single thread, try to
1489: * use JS_NewGrowableString to create the left string -- doing so helps Concat
1490: * avoid allocating a new buffer for the result and copying left's chars into
1491: * the new buffer. See above for thread safety comments.
1492: */
1493: extern JS_PUBLIC_API(JSString *)
1494: JS_ConcatStrings(JSContext *cx, JSString *left, JSString *right);
1495:
1496: /*
1497: * Convert a dependent string into an independent one. This function does not
1498: * change the string's mutability, so the thread safety comments above apply.
1499: */
1500: extern JS_PUBLIC_API(const jschar *)
1501: JS_UndependString(JSContext *cx, JSString *str);
1502:
1503: /*
1504: * Convert a mutable string (either growable or dependent) into an immutable,
1505: * thread-safe one.
1506: */
1507: extern JS_PUBLIC_API(JSBool)
1508: JS_MakeStringImmutable(JSContext *cx, JSString *str);
1509:
1510: /************************************************************************/
1511:
1512: /*
1513: * Locale specific string conversion callback.
1514: */
1515: struct JSLocaleCallbacks {
1516: JSLocaleToUpperCase localeToUpperCase;
1517: JSLocaleToLowerCase localeToLowerCase;
1518: JSLocaleCompare localeCompare;
1519: };
1520:
1521: /*
1522: * Establish locale callbacks. The pointer must persist as long as the
1523: * JSContext. Passing NULL restores the default behaviour.
1524: */
1525: extern JS_PUBLIC_API(void)
1526: JS_SetLocaleCallbacks(JSContext *cx, JSLocaleCallbacks *callbacks);
1527:
1528: /*
1529: * Return the address of the current locale callbacks struct, which may
1530: * be NULL.
1531: */
1532: extern JS_PUBLIC_API(JSLocaleCallbacks *)
1533: JS_GetLocaleCallbacks(JSContext *cx);
1534:
1535: /************************************************************************/
1536:
1537: /*
1538: * Error reporting.
1539: */
1540:
1541: /*
1542: * Report an exception represented by the sprintf-like conversion of format
1543: * and its arguments. This exception message string is passed to a pre-set
1544: * JSErrorReporter function (set by JS_SetErrorReporter; see jspubtd.h for
1545: * the JSErrorReporter typedef).
1546: */
1547: extern JS_PUBLIC_API(void)
1548: JS_ReportError(JSContext *cx, const char *format, ...);
1549:
1550: /*
1551: * Use an errorNumber to retrieve the format string, args are char *
1552: */
1553: extern JS_PUBLIC_API(void)
1554: JS_ReportErrorNumber(JSContext *cx, JSErrorCallback errorCallback,
1555: void *userRef, const uintN errorNumber, ...);
1556:
1557: /*
1558: * Use an errorNumber to retrieve the format string, args are jschar *
1559: */
1560: extern JS_PUBLIC_API(void)
1561: JS_ReportErrorNumberUC(JSContext *cx, JSErrorCallback errorCallback,
1562: void *userRef, const uintN errorNumber, ...);
1563:
1564: /*
1565: * As above, but report a warning instead (JSREPORT_IS_WARNING(report.flags)).
1566: * Return true if there was no error trying to issue the warning, and if the
1567: * warning was not converted into an error due to the JSOPTION_WERROR option
1568: * being set, false otherwise.
1569: */
1570: extern JS_PUBLIC_API(JSBool)
1571: JS_ReportWarning(JSContext *cx, const char *format, ...);
1572:
1573: extern JS_PUBLIC_API(JSBool)
1574: JS_ReportErrorFlagsAndNumber(JSContext *cx, uintN flags,
1575: JSErrorCallback errorCallback, void *userRef,
1576: const uintN errorNumber, ...);
1577:
1578: extern JS_PUBLIC_API(JSBool)
1579: JS_ReportErrorFlagsAndNumberUC(JSContext *cx, uintN flags,
1580: JSErrorCallback errorCallback, void *userRef,
1581: const uintN errorNumber, ...);
1582:
1583: /*
1584: * Complain when out of memory.
1585: */
1586: extern JS_PUBLIC_API(void)
1587: JS_ReportOutOfMemory(JSContext *cx);
1588:
1589: struct JSErrorReport {
1590: const char *filename; /* source file name, URL, etc., or null */
1591: uintN lineno; /* source line number */
1592: const char *linebuf; /* offending source line without final \n */
1593: const char *tokenptr; /* pointer to error token in linebuf */
1594: const jschar *uclinebuf; /* unicode (original) line buffer */
1595: const jschar *uctokenptr; /* unicode (original) token pointer */
1596: uintN flags; /* error/warning, etc. */
1597: uintN errorNumber; /* the error number, e.g. see js.msg */
1598: const jschar *ucmessage; /* the (default) error message */
1599: const jschar **messageArgs; /* arguments for the error message */
1600: };
1601:
1602: /*
1603: * JSErrorReport flag values. These may be freely composed.
1604: */
1605: #define JSREPORT_ERROR 0x0 /* pseudo-flag for default case */
1606: #define JSREPORT_WARNING 0x1 /* reported via JS_ReportWarning */
1607: #define JSREPORT_EXCEPTION 0x2 /* exception was thrown */
1608: #define JSREPORT_STRICT 0x4 /* error or warning due to strict option */
1609:
1610: /*
1611: * If JSREPORT_EXCEPTION is set, then a JavaScript-catchable exception
1612: * has been thrown for this runtime error, and the host should ignore it.
1613: * Exception-aware hosts should also check for JS_IsExceptionPending if
1614: * JS_ExecuteScript returns failure, and signal or propagate the exception, as
1615: * appropriate.
1616: */
1617: #define JSREPORT_IS_WARNING(flags) (((flags) & JSREPORT_WARNING) != 0)
1618: #define JSREPORT_IS_EXCEPTION(flags) (((flags) & JSREPORT_EXCEPTION) != 0)
1619: #define JSREPORT_IS_STRICT(flags) (((flags) & JSREPORT_STRICT) != 0)
1620:
1621: extern JS_PUBLIC_API(JSErrorReporter)
1622: JS_SetErrorReporter(JSContext *cx, JSErrorReporter er);
1623:
1624: /************************************************************************/
1625:
1626: /*
1627: * Regular Expressions.
1628: */
1629: #define JSREG_FOLD 0x01 /* fold uppercase to lowercase */
1630: #define JSREG_GLOB 0x02 /* global exec, creates array of matches */
1631: #define JSREG_MULTILINE 0x04 /* treat ^ and $ as begin and end of line */
1632:
1633: extern JS_PUBLIC_API(JSObject *)
1634: JS_NewRegExpObject(JSContext *cx, char *bytes, size_t length, uintN flags);
1635:
1636: extern JS_PUBLIC_API(JSObject *)
1637: JS_NewUCRegExpObject(JSContext *cx, jschar *chars, size_t length, uintN flags);
1638:
1639: extern JS_PUBLIC_API(void)
1640: JS_SetRegExpInput(JSContext *cx, JSString *input, JSBool multiline);
1641:
1642: extern JS_PUBLIC_API(void)
1643: JS_ClearRegExpStatics(JSContext *cx);
1644:
1645: extern JS_PUBLIC_API(void)
1646: JS_ClearRegExpRoots(JSContext *cx);
1647:
1648: /* TODO: compile, exec, get/set other statics... */
1649:
1650: /************************************************************************/
1651:
1652: extern JS_PUBLIC_API(JSBool)
1653: JS_IsExceptionPending(JSContext *cx);
1654:
1655: extern JS_PUBLIC_API(JSBool)
1656: JS_GetPendingException(JSContext *cx, jsval *vp);
1657:
1658: extern JS_PUBLIC_API(void)
1659: JS_SetPendingException(JSContext *cx, jsval v);
1660:
1661: extern JS_PUBLIC_API(void)
1662: JS_ClearPendingException(JSContext *cx);
1663:
1664: /*
1665: * Save the current exception state. This takes a snapshot of cx's current
1666: * exception state without making any change to that state.
1667: *
1668: * The returned state pointer MUST be passed later to JS_RestoreExceptionState
1669: * (to restore that saved state, overriding any more recent state) or else to
1670: * JS_DropExceptionState (to free the state struct in case it is not correct
1671: * or desirable to restore it). Both Restore and Drop free the state struct,
1672: * so callers must stop using the pointer returned from Save after calling the
1673: * Release or Drop API.
1674: */
1675: extern JS_PUBLIC_API(JSExceptionState *)
1676: JS_SaveExceptionState(JSContext *cx);
1677:
1678: extern JS_PUBLIC_API(void)
1679: JS_RestoreExceptionState(JSContext *cx, JSExceptionState *state);
1680:
1681: extern JS_PUBLIC_API(void)
1682: JS_DropExceptionState(JSContext *cx, JSExceptionState *state);
1683:
1684: /*
1685: * If the given value is an exception object that originated from an error,
1686: * the exception will contain an error report struct, and this API will return
1687: * the address of that struct. Otherwise, it returns NULL. The lifetime of
1688: * the error report struct that might be returned is the same as the lifetime
1689: * of the exception object.
1690: */
1691: extern JS_PUBLIC_API(JSErrorReport *)
1692: JS_ErrorFromException(JSContext *cx, jsval v);
1693:
1694: #ifdef JS_THREADSAFE
1695:
1696: /*
1697: * Associate the current thread with the given context. This is done
1698: * implicitly by JS_NewContext.
1699: *
1700: * Returns the old thread id for this context, which should be treated as
1701: * an opaque value. This value is provided for comparison to 0, which
1702: * indicates that ClearContextThread has been called on this context
1703: * since the last SetContextThread, or non-0, which indicates the opposite.
1704: */
1705: extern JS_PUBLIC_API(jsword)
1706: JS_GetContextThread(JSContext *cx);
1707:
1708: extern JS_PUBLIC_API(jsword)
1709: JS_SetContextThread(JSContext *cx);
1710:
1711: extern JS_PUBLIC_API(intN)
1712: JS_ClearContextThread(JSContext *cx);
1713:
1714: #endif /* JS_THREADSAFE */
1715:
1716: /************************************************************************/
1717:
1718: JS_END_EXTERN_C
1719:
1720: #endif /* jsapi_h___ */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.