1  /*
  2   * Copyright (C) 2013-2019 Apple 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 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
 23   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 24   */
 25  
 26  #import <JavaScriptCore/JavaScript.h>
 27  #import <JavaScriptCore/WebKitAvailability.h>
 28  
 29  #if JSC_OBJC_API_ENABLED
 30  
 31  #if defined(DARLING) && __i386__
 32  #import <wtf/WeakObjCPtr.h>
 33  #import "JSVirtualMachine.h"
 34  #import "DarlingJSContextPrivate.h"
 35  #import "StrongInlines.h"
 36  #endif // __i386__
 37  
 38  @class JSScript, JSVirtualMachine, JSValue, JSContext;
 39  
 40  /*!
 41  @interface
 42  @discussion A JSContext is a JavaScript execution environment. All
 43   JavaScript execution takes place within a context, and all JavaScript values
 44   are tied to a context.
 45  */
 46  JSC_CLASS_AVAILABLE(macos(10.9), ios(7.0))
 47  #if defined(DARLING) && __i386__
 48  @interface JSContext : NSObject {
 49      JSVirtualMachine *m_virtualMachine;
 50      JSGlobalContextRef m_context;
 51      JSC::Strong<JSC::JSObject> m_exception;
 52      WeakObjCPtr<id <JSModuleLoaderDelegate>> m_moduleLoaderDelegate;
 53      void(^_exceptionHandler)(JSContext *context, JSValue *exception);
 54  }
 55  #else
 56  @interface JSContext : NSObject
 57  #endif
 58  
 59  /*!
 60  @methodgroup Creating New JSContexts
 61  */
 62  /*!
 63  @method
 64  @abstract Create a JSContext.
 65  @result The new context.
 66  */
 67  - (instancetype)init;
 68  
 69  /*!
 70  @method
 71  @abstract Create a JSContext in the specified virtual machine.
 72  @param virtualMachine The JSVirtualMachine in which the context will be created.
 73  @result The new context.
 74  */
 75  - (instancetype)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine;
 76  
 77  /*!
 78  @methodgroup Evaluating Scripts
 79  */
 80  /*!
 81  @method
 82  @abstract Evaluate a string of JavaScript code.
 83  @param script A string containing the JavaScript code to evaluate.
 84  @result The last value generated by the script.
 85  */
 86  - (JSValue *)evaluateScript:(NSString *)script;
 87  
 88  /*!
 89  @method
 90  @abstract Evaluate a string of JavaScript code, with a URL for the script's source file.
 91  @param script A string containing the JavaScript code to evaluate.
 92  @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.
 93  @result The last value generated by the script.
 94  */
 95  - (JSValue *)evaluateScript:(NSString *)script withSourceURL:(NSURL *)sourceURL JSC_API_AVAILABLE(macos(10.10), ios(8.0));
 96  
 97  /*!
 98  @methodgroup Callback Accessors
 99  */
100  /*!
101  @method
102  @abstract Get the JSContext that is currently executing.
103  @discussion This method may be called from within an Objective-C block or method invoked
104   as a callback from JavaScript to retrieve the callback's context. Outside of
105   a callback from JavaScript this method will return nil.
106  @result The currently executing JSContext or nil if there isn't one.
107  */
108  + (JSContext *)currentContext;
109  
110  /*!
111  @method
112  @abstract Get the JavaScript function that is currently executing.
113  @discussion This method may be called from within an Objective-C block or method invoked
114   as a callback from JavaScript to retrieve the callback's context. Outside of
115   a callback from JavaScript this method will return nil.
116  @result The currently executing JavaScript function or nil if there isn't one.
117  */
118  + (JSValue *)currentCallee JSC_API_AVAILABLE(macos(10.10), ios(8.0));
119  
120  /*!
121  @method
122  @abstract Get the <code>this</code> value of the currently executing method.
123  @discussion This method may be called from within an Objective-C block or method invoked
124   as a callback from JavaScript to retrieve the callback's this value. Outside
125   of a callback from JavaScript this method will return nil.
126  @result The current <code>this</code> value or nil if there isn't one.
127  */
128  + (JSValue *)currentThis;
129  
130  /*!
131  @method
132  @abstract Get the arguments to the current callback.
133  @discussion This method may be called from within an Objective-C block or method invoked
134   as a callback from JavaScript to retrieve the callback's arguments, objects
135   in the returned array are instances of JSValue. Outside of a callback from
136   JavaScript this method will return nil.
137  @result An NSArray of the arguments nil if there is no current callback.
138  */
139  + (NSArray *)currentArguments;
140  
141  /*!
142  @functiongroup Global Properties
143  */
144  
145  /*!
146  @property
147  @abstract Get the global object of the context.
148  @discussion This method retrieves the global object of the JavaScript execution context.
149   Instances of JSContext originating from WebKit will return a reference to the
150   WindowProxy object.
151  @result The global object.
152  */
153  @property (readonly, strong) JSValue *globalObject;
154  
155  /*!
156  @property
157  @discussion The <code>exception</code> property may be used to throw an exception to JavaScript.
158   
159   Before a callback is made from JavaScript to an Objective-C block or method,
160   the prior value of the exception property will be preserved and the property
161   will be set to nil. After the callback has completed the new value of the
162   exception property will be read, and prior value restored. If the new value
163   of exception is not nil, the callback will result in that value being thrown.
164   
165   This property may also be used to check for uncaught exceptions arising from
166   API function calls (since the default behaviour of <code>exceptionHandler</code> is to
167   assign an uncaught exception to this property).
168  */
169  @property (strong) JSValue *exception;
170  
171  /*!
172  @property
173  @discussion If a call to an API function results in an uncaught JavaScript exception, the
174   <code>exceptionHandler</code> block will be invoked. The default implementation for the
175   exception handler will store the exception to the exception property on
176   context. As a consequence the default behaviour is for uncaught exceptions
177   occurring within a callback from JavaScript to be rethrown upon return.
178   Setting this value to nil will cause all exceptions occurring
179   within a callback from JavaScript to be silently caught.
180  */
181  @property (copy) void(^exceptionHandler)(JSContext *context, JSValue *exception);
182  
183  /*!
184  @property
185  @discussion All instances of JSContext are associated with a JSVirtualMachine.
186  */
187  @property (readonly, strong) JSVirtualMachine *virtualMachine;
188  
189  /*!
190  @property
191  @discussion Name of the JSContext. Exposed when remote debugging the context.
192  */
193  @property (copy) NSString *name JSC_API_AVAILABLE(macos(10.10), ios(8.0));
194  @end
195  
196  /*!
197  @category
198  @discussion Instances of JSContext implement the following methods in order to enable
199   support for subscript access by key and index, for example:
200  
201  @textblock
202      JSContext *context;
203      JSValue *v = context[@"X"]; // Get value for "X" from the global object.
204      context[@"Y"] = v;          // Assign 'v' to "Y" on the global object.
205  @/textblock
206  
207   An object key passed as a subscript will be converted to a JavaScript value,
208   and then the value converted to a string used to resolve a property of the
209   global object.
210  */
211  @interface JSContext (SubscriptSupport)
212  
213  /*!
214  @method
215  @abstract Get a particular property on the global object.
216  @result The JSValue for the global object's property.
217  */
218  - (JSValue *)objectForKeyedSubscript:(id)key;
219  
220  /*!
221  @method
222  @abstract Set a particular property on the global object.
223  */
224  - (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key;
225  
226  @end
227  
228  /*!
229  @category
230  @discussion These functions are for bridging between the C API and the Objective-C API.
231  */
232  @interface JSContext (JSContextRefSupport)
233  
234  /*!
235  @method
236  @abstract Create a JSContext, wrapping its C API counterpart.
237  @result The JSContext equivalent of the provided JSGlobalContextRef.
238  */
239  + (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef;
240  
241  /*!
242  @property
243  @abstract Get the C API counterpart wrapped by a JSContext.
244  @result The C API equivalent of this JSContext.
245  */
246  @property (readonly) JSGlobalContextRef JSGlobalContextRef;
247  
248  @end
249  
250  #if defined(DARLING) && __i386__
251  // Taken from JSContextPrivate.h
252  @interface JSContext(Private)
253  @property (setter=_setRemoteInspectionEnabled:) BOOL _remoteInspectionEnabled JSC_API_AVAILABLE(macos(10.10), ios(8.0));
254  @property (setter=_setIncludesNativeCallStackWhenReportingExceptions:) BOOL _includesNativeCallStackWhenReportingExceptions JSC_API_AVAILABLE(macos(10.10), ios(8.0));
255  @property (setter=_setDebuggerRunLoop:) CFRunLoopRef _debuggerRunLoop JSC_API_AVAILABLE(macos(10.10), ios(8.0));
256  @property (nonatomic, weak) id <JSModuleLoaderDelegate> moduleLoaderDelegate JSC_API_AVAILABLE(macos(10.15), ios(13.0));
257  - (JSValue *)evaluateJSScript:(JSScript *)script JSC_API_AVAILABLE(macos(10.15), ios(13.0));
258  - (JSValue *)dependencyIdentifiersForModuleJSScript:(JSScript *)script JSC_API_AVAILABLE(macos(10.15), ios(13.0));
259  - (void)_setITMLDebuggableType JSC_API_AVAILABLE(macos(11.0), ios(14.0));
260  @end
261  #endif // defined(DARLING) && __i386__
262  
263  #endif