1/* 2 * Copyright (C) 2013 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#ifndef JSContext_h 27#define JSContext_h 28 29#include <JavaScriptCore/JavaScript.h> 30 31#if JSC_OBJC_API_ENABLED 32 33@class JSVirtualMachine, JSValue; 34 35// An instance of JSContext represents a JavaScript execution environment. All 36// JavaScript execution takes place within a context. 37// JSContext is also used to manage the life-cycle of objects within the 38// JavaScript virtual machine. Every instance of JSValue is associated with a 39// JSContext via a strong reference. The JSValue will keep the JSContext it 40// references alive so long as the JSValue remains alive. When all of the JSValues 41// that reference a particular JSContext have been deallocated the JSContext 42// will be deallocated unless it has been previously retained. 43 44NS_CLASS_AVAILABLE(10_9, NA) 45@interface JSContext : NSObject 46 47// Create a JSContext. 48- (id)init; 49// Create a JSContext in the specified virtual machine. 50- (id)initWithVirtualMachine:(JSVirtualMachine *)virtualMachine; 51 52// Evaluate a string of JavaScript code. 53- (JSValue *)evaluateScript:(NSString *)script; 54 55// This method retrieves the global object of the JavaScript execution context. 56// Instances of JSContext originating from WebKit will return a reference to the 57// WindowProxy object. 58- (JSValue *)globalObject; 59 60// This method may be called from within an Objective-C block or method invoked 61// as a callback from JavaScript to retrieve the callback's context. Outside of 62// a callback from JavaScript this method will return nil. 63+ (JSContext *)currentContext; 64// This method may be called from within an Objective-C block or method invoked 65// as a callback from JavaScript to retrieve the callback's this value. Outside 66// of a callback from JavaScript this method will return nil. 67+ (JSValue *)currentThis; 68// This method may be called from within an Objective-C block or method invoked 69// as a callback from JavaScript to retrieve the callback's arguments, objects 70// in the returned array are instances of JSValue. Outside of a callback from 71// JavaScript this method will return nil. 72+ (NSArray *)currentArguments; 73 74// The "exception" property may be used to throw an exception to JavaScript. 75// Before a callback is made from JavaScript to an Objective-C block or method, 76// the prior value of the exception property will be preserved and the property 77// will be set to nil. After the callback has completed the new value of the 78// exception property will be read, and prior value restored. If the new value 79// of exception is not nil, the callback will result in that value being thrown. 80// This property may also be used to check for uncaught exceptions arising from 81// API function calls (since the default behaviour of "exceptionHandler" is to 82// assign an uncaught exception to this property). 83// If a JSValue originating from a different JSVirtualMachine than this context 84// is assigned to this property, an Objective-C exception will be raised. 85@property(retain) JSValue *exception; 86 87// If a call to an API function results in an uncaught JavaScript exception, the 88// "exceptionHandler" block will be invoked. The default implementation for the 89// exception handler will store the exception to the exception property on 90// context. As a consequence the default behaviour is for unhandled exceptions 91// occurring within a callback from JavaScript to be rethrown upon return. 92// Setting this value to nil will result in all uncaught exceptions thrown from 93// the API being silently consumed. 94@property(copy) void(^exceptionHandler)(JSContext *context, JSValue *exception); 95 96// All instances of JSContext are associated with a single JSVirtualMachine. The 97// virtual machine provides an "object space" or set of execution resources. 98@property(readonly, retain) JSVirtualMachine *virtualMachine; 99 100@end 101 102// Instances of JSContext implement the following methods in order to enable 103// support for subscript access by key and index, for example: 104// 105// JSContext *context; 106// JSValue *v = context[@"X"]; // Get value for "X" from the global object. 107// context[@"Y"] = v; // Assign 'v' to "Y" on the global object. 108// 109// An object key passed as a subscript will be converted to a JavaScript value, 110// and then the value converted to a string used to resolve a property of the 111// global object. 112@interface JSContext(SubscriptSupport) 113 114- (JSValue *)objectForKeyedSubscript:(id)key; 115- (void)setObject:(id)object forKeyedSubscript:(NSObject <NSCopying> *)key; 116 117@end 118 119// These functions are for bridging between the C API and the Objective-C API. 120@interface JSContext(JSContextRefSupport) 121// Creates a JSContext, wrapping its C API counterpart. 122+ (JSContext *)contextWithJSGlobalContextRef:(JSGlobalContextRef)jsGlobalContextRef; 123// Returns the C API counterpart wrapped by a JSContext. 124- (JSGlobalContextRef)JSGlobalContextRef; 125@end 126 127#endif 128 129#endif // JSContext_h 130