barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 1 | /* |
keith_miller@apple.com | 16bf741 | 2019-01-14 20:27:17 +0000 | [diff] [blame] | 2 | * Copyright (C) 2013-2019 Apple Inc. All rights reserved. |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 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 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 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 |
joepeck@webkit.org | b4ba412 | 2013-12-12 18:41:35 +0000 | [diff] [blame] | 23 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 24 | */ |
| 25 | |
mhahnenberg@apple.com | f0712f9 | 2013-02-21 20:00:33 +0000 | [diff] [blame] | 26 | #ifndef JSContext_h |
| 27 | #define JSContext_h |
| 28 | |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 29 | #include <JavaScriptCore/JavaScript.h> |
mhahnenberg@apple.com | 4f18e95 | 2014-02-07 01:56:45 +0000 | [diff] [blame] | 30 | #include <JavaScriptCore/WebKitAvailability.h> |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 31 | |
mhahnenberg@apple.com | f0712f9 | 2013-02-21 20:00:33 +0000 | [diff] [blame] | 32 | #if JSC_OBJC_API_ENABLED |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 33 | |
keith_miller@apple.com | 16bf741 | 2019-01-14 20:27:17 +0000 | [diff] [blame] | 34 | @class JSScript, JSVirtualMachine, JSValue, JSContext; |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 35 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 36 | /*! |
| 37 | @interface |
ggaren@apple.com | 58b8967 | 2015-10-16 23:57:35 +0000 | [diff] [blame] | 38 | @discussion A JSContext is a JavaScript execution environment. All |
| 39 | JavaScript execution takes place within a context, and all JavaScript values |
| 40 | are tied to a context. |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 41 | */ |
timothy@apple.com | bd06ade | 2019-03-22 15:45:13 +0000 | [diff] [blame] | 42 | JSC_CLASS_AVAILABLE(macos(10.9), ios(7.0)) |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 43 | @interface JSContext : NSObject |
| 44 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 45 | /*! |
| 46 | @methodgroup Creating New JSContexts |
| 47 | */ |
| 48 | /*! |
| 49 | @method |
| 50 | @abstract Create a JSContext. |
| 51 | @result The new context. |
| 52 | */ |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 53 | - (instancetype)init; |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 54 | |
| 55 | /*! |
| 56 | @method |
| 57 | @abstract Create a JSContext in the specified virtual machine. |
| 58 | @param virtualMachine The JSVirtualMachine in which the context will be created. |
| 59 | @result The new context. |
| 60 | */ |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 61 | - (instancetype)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine; |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 62 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 63 | /*! |
| 64 | @methodgroup Evaluating Scripts |
| 65 | */ |
| 66 | /*! |
| 67 | @method |
| 68 | @abstract Evaluate a string of JavaScript code. |
| 69 | @param script A string containing the JavaScript code to evaluate. |
| 70 | @result The last value generated by the script. |
| 71 | */ |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 72 | - (JSValue *)evaluateScript:(NSString *)script; |
| 73 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 74 | /*! |
joepeck@webkit.org | 824b747 | 2014-03-11 02:39:40 +0000 | [diff] [blame] | 75 | @method |
| 76 | @abstract Evaluate a string of JavaScript code, with a URL for the script's source file. |
| 77 | @param script A string containing the JavaScript code to evaluate. |
| 78 | @param sourceURL A URL for the script's source file. Used by debuggers and when reporting exceptions. This parameter is informative only: it does not change the behavior of the script. |
| 79 | @result The last value generated by the script. |
| 80 | */ |
timothy@apple.com | bd06ade | 2019-03-22 15:45:13 +0000 | [diff] [blame] | 81 | - (JSValue *)evaluateScript:(NSString *)script withSourceURL:(NSURL *)sourceURL JSC_API_AVAILABLE(macos(10.10), ios(8.0)); |
joepeck@webkit.org | 824b747 | 2014-03-11 02:39:40 +0000 | [diff] [blame] | 82 | |
| 83 | /*! |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 84 | @methodgroup Callback Accessors |
| 85 | */ |
| 86 | /*! |
| 87 | @method |
| 88 | @abstract Get the JSContext that is currently executing. |
| 89 | @discussion This method may be called from within an Objective-C block or method invoked |
| 90 | as a callback from JavaScript to retrieve the callback's context. Outside of |
| 91 | a callback from JavaScript this method will return nil. |
| 92 | @result The currently executing JSContext or nil if there isn't one. |
| 93 | */ |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 94 | + (JSContext *)currentContext; |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 95 | |
| 96 | /*! |
| 97 | @method |
mhahnenberg@apple.com | 4f18e95 | 2014-02-07 01:56:45 +0000 | [diff] [blame] | 98 | @abstract Get the JavaScript function that is currently executing. |
| 99 | @discussion This method may be called from within an Objective-C block or method invoked |
| 100 | as a callback from JavaScript to retrieve the callback's context. Outside of |
| 101 | a callback from JavaScript this method will return nil. |
| 102 | @result The currently executing JavaScript function or nil if there isn't one. |
| 103 | */ |
timothy@apple.com | bd06ade | 2019-03-22 15:45:13 +0000 | [diff] [blame] | 104 | + (JSValue *)currentCallee JSC_API_AVAILABLE(macos(10.10), ios(8.0)); |
mhahnenberg@apple.com | 4f18e95 | 2014-02-07 01:56:45 +0000 | [diff] [blame] | 105 | |
| 106 | /*! |
| 107 | @method |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 108 | @abstract Get the <code>this</code> value of the currently executing method. |
| 109 | @discussion This method may be called from within an Objective-C block or method invoked |
| 110 | as a callback from JavaScript to retrieve the callback's this value. Outside |
| 111 | of a callback from JavaScript this method will return nil. |
| 112 | @result The current <code>this</code> value or nil if there isn't one. |
| 113 | */ |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 114 | + (JSValue *)currentThis; |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 115 | |
| 116 | /*! |
| 117 | @method |
| 118 | @abstract Get the arguments to the current callback. |
| 119 | @discussion This method may be called from within an Objective-C block or method invoked |
| 120 | as a callback from JavaScript to retrieve the callback's arguments, objects |
| 121 | in the returned array are instances of JSValue. Outside of a callback from |
| 122 | JavaScript this method will return nil. |
| 123 | @result An NSArray of the arguments nil if there is no current callback. |
| 124 | */ |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 125 | + (NSArray *)currentArguments; |
| 126 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 127 | /*! |
mitz@apple.com | 5de0d14 | 2016-10-19 17:18:27 +0000 | [diff] [blame] | 128 | @functiongroup Global Properties |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 129 | */ |
mitz@apple.com | 5de0d14 | 2016-10-19 17:18:27 +0000 | [diff] [blame] | 130 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 131 | /*! |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 132 | @property |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 133 | @abstract Get the global object of the context. |
| 134 | @discussion This method retrieves the global object of the JavaScript execution context. |
| 135 | Instances of JSContext originating from WebKit will return a reference to the |
| 136 | WindowProxy object. |
| 137 | @result The global object. |
| 138 | */ |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 139 | @property (readonly, strong) JSValue *globalObject; |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 140 | |
| 141 | /*! |
| 142 | @property |
| 143 | @discussion The <code>exception</code> property may be used to throw an exception to JavaScript. |
| 144 | |
| 145 | Before a callback is made from JavaScript to an Objective-C block or method, |
| 146 | the prior value of the exception property will be preserved and the property |
| 147 | will be set to nil. After the callback has completed the new value of the |
| 148 | exception property will be read, and prior value restored. If the new value |
| 149 | of exception is not nil, the callback will result in that value being thrown. |
| 150 | |
| 151 | This property may also be used to check for uncaught exceptions arising from |
| 152 | API function calls (since the default behaviour of <code>exceptionHandler</code> is to |
| 153 | assign an uncaught exception to this property). |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 154 | */ |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 155 | @property (strong) JSValue *exception; |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 156 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 157 | /*! |
| 158 | @property |
| 159 | @discussion If a call to an API function results in an uncaught JavaScript exception, the |
| 160 | <code>exceptionHandler</code> block will be invoked. The default implementation for the |
| 161 | exception handler will store the exception to the exception property on |
ggaren@apple.com | 58b8967 | 2015-10-16 23:57:35 +0000 | [diff] [blame] | 162 | context. As a consequence the default behaviour is for uncaught exceptions |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 163 | occurring within a callback from JavaScript to be rethrown upon return. |
ggaren@apple.com | 58b8967 | 2015-10-16 23:57:35 +0000 | [diff] [blame] | 164 | Setting this value to nil will cause all exceptions occurring |
| 165 | within a callback from JavaScript to be silently caught. |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 166 | */ |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 167 | @property (copy) void(^exceptionHandler)(JSContext *context, JSValue *exception); |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 168 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 169 | /*! |
| 170 | @property |
ggaren@apple.com | 58b8967 | 2015-10-16 23:57:35 +0000 | [diff] [blame] | 171 | @discussion All instances of JSContext are associated with a JSVirtualMachine. |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 172 | */ |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 173 | @property (readonly, strong) JSVirtualMachine *virtualMachine; |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 174 | |
joepeck@webkit.org | d2ecf37 | 2013-12-04 18:20:37 +0000 | [diff] [blame] | 175 | /*! |
| 176 | @property |
| 177 | @discussion Name of the JSContext. Exposed when remote debugging the context. |
| 178 | */ |
timothy@apple.com | bd06ade | 2019-03-22 15:45:13 +0000 | [diff] [blame] | 179 | @property (copy) NSString *name JSC_API_AVAILABLE(macos(10.10), ios(8.0)); |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 180 | @end |
| 181 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 182 | /*! |
| 183 | @category |
| 184 | @discussion Instances of JSContext implement the following methods in order to enable |
| 185 | support for subscript access by key and index, for example: |
| 186 | |
| 187 | @textblock |
| 188 | JSContext *context; |
| 189 | JSValue *v = context[@"X"]; // Get value for "X" from the global object. |
| 190 | context[@"Y"] = v; // Assign 'v' to "Y" on the global object. |
| 191 | @/textblock |
| 192 | |
| 193 | An object key passed as a subscript will be converted to a JavaScript value, |
| 194 | and then the value converted to a string used to resolve a property of the |
| 195 | global object. |
| 196 | */ |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 197 | @interface JSContext (SubscriptSupport) |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 198 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 199 | /*! |
mitz@apple.com | 5de0d14 | 2016-10-19 17:18:27 +0000 | [diff] [blame] | 200 | @method |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 201 | @abstract Get a particular property on the global object. |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 202 | @result The JSValue for the global object's property. |
| 203 | */ |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 204 | - (JSValue *)objectForKeyedSubscript:(id)key; |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 205 | |
| 206 | /*! |
mitz@apple.com | 5de0d14 | 2016-10-19 17:18:27 +0000 | [diff] [blame] | 207 | @method |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 208 | @abstract Set a particular property on the global object. |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 209 | */ |
barraclough@apple.com | a56aeb2 | 2013-01-02 23:34:48 +0000 | [diff] [blame] | 210 | - (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key; |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 211 | |
| 212 | @end |
| 213 | |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 214 | /*! |
| 215 | @category |
| 216 | @discussion These functions are for bridging between the C API and the Objective-C API. |
| 217 | */ |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 218 | @interface JSContext (JSContextRefSupport) |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 219 | |
| 220 | /*! |
| 221 | @method |
| 222 | @abstract Create a JSContext, wrapping its C API counterpart. |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 223 | @result The JSContext equivalent of the provided JSGlobalContextRef. |
| 224 | */ |
ggaren@apple.com | 58bf4ea | 2013-04-30 21:55:43 +0000 | [diff] [blame] | 225 | + (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef; |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 226 | |
| 227 | /*! |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 228 | @property |
mhahnenberg@apple.com | fc0b672 | 2013-11-23 02:54:31 +0000 | [diff] [blame] | 229 | @abstract Get the C API counterpart wrapped by a JSContext. |
| 230 | @result The C API equivalent of this JSContext. |
| 231 | */ |
mrowe@apple.com | 4a0e6c1 | 2013-12-11 22:13:23 +0000 | [diff] [blame] | 232 | @property (readonly) JSGlobalContextRef JSGlobalContextRef; |
keith_miller@apple.com | 16bf741 | 2019-01-14 20:27:17 +0000 | [diff] [blame] | 233 | |
ggaren@apple.com | 58bf4ea | 2013-04-30 21:55:43 +0000 | [diff] [blame] | 234 | @end |
| 235 | |
barraclough@apple.com | fc38188 | 2013-01-02 03:51:15 +0000 | [diff] [blame] | 236 | #endif |
mhahnenberg@apple.com | f0712f9 | 2013-02-21 20:00:33 +0000 | [diff] [blame] | 237 | |
| 238 | #endif // JSContext_h |