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#import <JavaScriptCore/JavaScriptCore.h> 27 28#if JSC_OBJC_API_ENABLED 29 30// When a JavaScript value is created from an instance of an Objective-C class 31// for which no copying conversion is specified a JavaScript wrapper object will 32// be created. 33// 34// In JavaScript inheritance is supported via a chain of prototype objects, and 35// for each Objective-C class (and per JSContext) an object appropriate for use 36// as a prototype will be provided. For the class NSObject the prototype object 37// will be the JavaScript context's Object Prototype. For all other Objective-C 38// classes a Prototype object will be created. The Prototype object for a given 39// Objective-C class will have its internal [Prototype] property set to point to 40// the Prototype object of the Objective-C class's superclass. As such the 41// prototype chain for a JavaScript wrapper object will reflect the wrapped 42// Objective-C type's inheritance hierarchy. 43// 44// In addition to the Prototype object a JavaScript Constructor object will also 45// be produced for each Objective-C class. The Constructor object has a property 46// named 'prototype' that references the Prototype object, and the Prototype 47// object has a property named 'constructor' that references the Constructor. 48// The Constructor object is not callable. 49// 50// By default no methods or properties of the Objective-C class will be exposed 51// to JavaScript, however methods and properties may explicitly be exported. 52// For each protocol that a class conforms to, if the protocol incorporates the 53// protocol JSExport, then the protocol will be interpreted as a list of methods 54// and properties to be exported to JavaScript. 55// 56// For each instance method being exported, a corresponding JavaScript function 57// will be assigned as a property of the Prototype object, for each Objective-C 58// property being exported a JavaScript accessor property will be created on the 59// Prototype, and for each class method exported a JavaScript function will be 60// created on the Constructor object. For example: 61// 62// @protocol MyClassJavaScriptMethods <JSExport> 63// - (void)foo; 64// @end 65// 66// @interface MyClass : NSObject <MyClassJavaScriptMethods> 67// - (void)foo; 68// - (void)bar; 69// @end 70// 71// Data properties that are created on the prototype or constructor objects have 72// the attributes: writable:true, enumerable:false, configurable:true. Accessor 73// properties have the attributes: enumerable:false and configurable:true. 74// 75// If an instance of MyClass is converted to a JavaScript value, the resulting 76// wrapper object will (via its prototype) export the method "foo" to JavaScript, 77// since the class conforms to the MyClassJavaScriptMethods protocol, and this 78// protocol incorporates JSExport. "bar" will not be exported. 79// 80// Properties, arguments, and return values of the following types are 81// supported: 82// 83// Primitive numbers: signed values of up to 32-bits are converted in a manner 84// consistent with valueWithInt32/toInt32, unsigned values of up to 32-bits 85// are converted in a manner consistent with valueWithUInt32/toUInt32, all 86// other numeric values are converted consistently with valueWithDouble/ 87// toDouble. 88// BOOL: values are converted consistently with valueWithBool/toBool. 89// id: values are converted consistently with valueWithObject/toObject. 90// <Objective-C Class>: - where the type is a pointer to a specified Objective-C 91// class, conversion is consistent with valueWithObjectOfClass/toObject. 92// struct types: C struct types are supported, where JSValue provides support 93// for the given type. Support is built in for CGPoint, NSRange, CGRect, and 94// CGSize. 95// block types: In addition to support provided by valueWithObject/toObject for 96// block types, if a JavaScript Function is passed as an argument, where the 97// type required is a block with a void return value (and where the block's 98// arguments are all of supported types), then a special adaptor block 99// will be created, allowing the JavaScript function to be used in the place 100// of a block. 101// 102// For any interface that conforms to JSExport the normal copying conversion for 103// built in types will be inhibited - so, for example, if an instance that 104// derives from NSString but conforms to JSExport is passed to valueWithObject: 105// then a wrapper object for the Objective-C object will be returned rather than 106// a JavaScript string primitive. 107@protocol JSExport 108@end 109 110// When a selector that takes one or more arguments is converted to a JavaScript 111// property name, by default a property name will be generated by performing the 112// following conversion: 113// - All colons are removed from the selector 114// - Any lowercase letter that had followed a colon will be capitalized. 115// Under the default conversion a selector "doFoo:withBar:" will be exported as 116// "doFooWithBar". The default conversion may be overriden using the JSExportAs 117// macro, for example to export a method "doFoo:withBar:" as "doFoo": 118// 119// @protocol MyClassJavaScriptMethods <JSExport> 120// JSExportAs(doFoo, 121// - (void)doFoo:(id)foo withBar:(id)bar 122// ); 123// @end 124// 125// Note that the JSExport macro may only be applied to a selector that takes one 126// or more argument. 127#define JSExportAs(PropertyName, Selector) \ 128 @optional Selector __JS_EXPORT_AS__##PropertyName:(id)argument; @required Selector 129 130#endif 131