|
1 /* |
|
2 * Copyright (C) 2006 Apple Computer, Inc. All rights reserved. |
|
3 * |
|
4 * Redistribution and use in source and binary forms, with or without |
|
5 * modification, are permitted provided that the following conditions |
|
6 * are met: |
|
7 * 1. Redistributions of source code must retain the above copyright |
|
8 * notice, this list of conditions and the following disclaimer. |
|
9 * 2. Redistributions in binary form must reproduce the above copyright |
|
10 * notice, this list of conditions and the following disclaimer in the |
|
11 * documentation and/or other materials provided with the distribution. |
|
12 * |
|
13 * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY |
|
14 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
|
15 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
|
16 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE COMPUTER, INC. OR |
|
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
|
18 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
|
19 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
|
20 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY |
|
21 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
|
22 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
|
23 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
24 */ |
|
25 |
|
26 #ifndef JSBase_h |
|
27 #define JSBase_h |
|
28 |
|
29 #ifndef __cplusplus |
|
30 #include <stdbool.h> |
|
31 #endif |
|
32 |
|
33 /* JavaScript engine interface */ |
|
34 |
|
35 /*! @typedef JSContextGroupRef A group that associates JavaScript contexts with one another. Contexts in the same group may share and exchange JavaScript objects. */ |
|
36 typedef const struct OpaqueJSContextGroup* JSContextGroupRef; |
|
37 |
|
38 /*! @typedef JSContextRef A JavaScript execution context. Holds the global object and other execution state. */ |
|
39 typedef const struct OpaqueJSContext* JSContextRef; |
|
40 |
|
41 /*! @typedef JSGlobalContextRef A global JavaScript execution context. A JSGlobalContext is a JSContext. */ |
|
42 typedef struct OpaqueJSContext* JSGlobalContextRef; |
|
43 |
|
44 /*! @typedef JSStringRef A UTF16 character buffer. The fundamental string representation in JavaScript. */ |
|
45 typedef struct OpaqueJSString* JSStringRef; |
|
46 |
|
47 /*! @typedef JSClassRef A JavaScript class. Used with JSObjectMake to construct objects with custom behavior. */ |
|
48 typedef struct OpaqueJSClass* JSClassRef; |
|
49 |
|
50 /*! @typedef JSPropertyNameArrayRef An array of JavaScript property names. */ |
|
51 typedef struct OpaqueJSPropertyNameArray* JSPropertyNameArrayRef; |
|
52 |
|
53 /*! @typedef JSPropertyNameAccumulatorRef An ordered set used to collect the names of a JavaScript object's properties. */ |
|
54 typedef struct OpaqueJSPropertyNameAccumulator* JSPropertyNameAccumulatorRef; |
|
55 |
|
56 |
|
57 /* JavaScript data types */ |
|
58 |
|
59 /*! @typedef JSValueRef A JavaScript value. The base type for all JavaScript values, and polymorphic functions on them. */ |
|
60 typedef const struct OpaqueJSValue* JSValueRef; |
|
61 |
|
62 /*! @typedef JSObjectRef A JavaScript object. A JSObject is a JSValue. */ |
|
63 typedef struct OpaqueJSValue* JSObjectRef; |
|
64 |
|
65 /* JavaScript symbol exports */ |
|
66 |
|
67 #undef JS_EXPORT |
|
68 #if defined(JS_NO_EXPORT) |
|
69 #define JS_EXPORT |
|
70 #elif defined(__GNUC__) && !defined(__CC_ARM) && !defined(__ARMCC__) |
|
71 #define JS_EXPORT __attribute__((visibility("default"))) |
|
72 #elif defined(WIN32) || defined(_WIN32) || defined(_WIN32_WCE) |
|
73 #if defined(BUILDING_JavaScriptCore) || defined(BUILDING_WTF) |
|
74 #define JS_EXPORT __declspec(dllexport) |
|
75 #else |
|
76 #define JS_EXPORT __declspec(dllimport) |
|
77 #endif |
|
78 #else |
|
79 #define JS_EXPORT |
|
80 #endif |
|
81 |
|
82 #ifdef __cplusplus |
|
83 extern "C" { |
|
84 #endif |
|
85 |
|
86 /* Script Evaluation */ |
|
87 |
|
88 /*! |
|
89 @function JSEvaluateScript |
|
90 @abstract Evaluates a string of JavaScript. |
|
91 @param ctx The execution context to use. |
|
92 @param script A JSString containing the script to evaluate. |
|
93 @param thisObject The object to use as "this," or NULL to use the global object as "this." |
|
94 @param sourceURL A JSString containing a URL for the script's source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions. |
|
95 @param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions. |
|
96 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception. |
|
97 @result The JSValue that results from evaluating script, or NULL if an exception is thrown. |
|
98 */ |
|
99 JS_EXPORT JSValueRef JSEvaluateScript(JSContextRef ctx, JSStringRef script, JSObjectRef thisObject, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception); |
|
100 |
|
101 /*! |
|
102 @function JSCheckScriptSyntax |
|
103 @abstract Checks for syntax errors in a string of JavaScript. |
|
104 @param ctx The execution context to use. |
|
105 @param script A JSString containing the script to check for syntax errors. |
|
106 @param sourceURL A JSString containing a URL for the script's source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions. |
|
107 @param startingLineNumber An integer value specifying the script's starting line number in the file located at sourceURL. This is only used when reporting exceptions. |
|
108 @param exception A pointer to a JSValueRef in which to store a syntax error exception, if any. Pass NULL if you do not care to store a syntax error exception. |
|
109 @result true if the script is syntactically correct, otherwise false. |
|
110 */ |
|
111 JS_EXPORT bool JSCheckScriptSyntax(JSContextRef ctx, JSStringRef script, JSStringRef sourceURL, int startingLineNumber, JSValueRef* exception); |
|
112 |
|
113 /*! |
|
114 @function JSGarbageCollect |
|
115 @abstract Performs a JavaScript garbage collection. |
|
116 @param ctx The execution context to use. |
|
117 @discussion JavaScript values that are on the machine stack, in a register, |
|
118 protected by JSValueProtect, set as the global object of an execution context, |
|
119 or reachable from any such value will not be collected. |
|
120 |
|
121 During JavaScript execution, you are not required to call this function; the |
|
122 JavaScript engine will garbage collect as needed. JavaScript values created |
|
123 within a context group are automatically destroyed when the last reference |
|
124 to the context group is released. |
|
125 */ |
|
126 JS_EXPORT void JSGarbageCollect(JSContextRef ctx); |
|
127 |
|
128 #ifdef __cplusplus |
|
129 } |
|
130 #endif |
|
131 |
|
132 #endif /* JSBase_h */ |