1/* 2 * Copyright (C) 2004, 2006, 2007 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 WebScriptObject_h 27#define WebScriptObject_h 28 29#import <Foundation/Foundation.h> 30#import <JavaScriptCore/JSBase.h> 31#import <WebCore/WebKitAvailability.h> 32 33// NSObject (WebScripting) ----------------------------------------------------- 34 35/* 36 Classes may implement one or more methods in WebScripting to export interfaces 37 to WebKit's JavaScript environment. 38 39 By default, no properties or functions are exported. A class must implement 40 +isKeyExcludedFromWebScript: and/or +isSelectorExcludedFromWebScript: to 41 expose selected properties and methods, respectively, to JavaScript. 42 43 Access to exported properties is done using KVC -- specifically, the following 44 KVC methods: 45 46 - (void)setValue:(id)value forKey:(NSString *)key 47 - (id)valueForKey:(NSString *)key 48 49 Clients may also intercept property set/get operations that are made by the 50 scripting environment for properties that are not exported. This is done using 51 the KVC methods: 52 53 - (void)setValue:(id)value forUndefinedKey:(NSString *)key 54 - (id)valueForUndefinedKey:(NSString *)key 55 56 Similarly, clients may intercept method invocations that are made by the 57 scripting environment for methods that are not exported. This is done using 58 the method: 59 60 - (id)invokeUndefinedMethodFromWebScript:(NSString *)name withArguments:(NSArray *)args; 61 62 If clients need to raise an exception in the script environment 63 they can call [WebScriptObject throwException:]. Note that throwing an 64 exception using this method will only succeed if the method that throws the exception 65 is being called within the scope of a script invocation. 66 67 Not all methods are exposed. Only those methods whose parameters and return 68 type meets the export criteria are exposed. Valid types are Objective-C instances 69 and scalars. Other types are not allowed. 70 71 Types will be converted automatically between JavaScript and Objective-C in 72 the following manner: 73 74 JavaScript ObjC 75 ---------- ---------- 76 null => nil 77 undefined => WebUndefined 78 number => NSNumber 79 boolean => CFBoolean 80 string => NSString 81 object => id 82 83 The object => id conversion occurs as follows: if the object wraps an underlying 84 Objective-C object (i.e., if it was created by a previous ObjC => JavaScript conversion), 85 then the underlying Objective-C object is returned. Otherwise, a new WebScriptObject 86 is created and returned. 87 88 The above conversions occur only if the declared ObjC type is an object type. 89 For primitive types like int and char, a numeric cast is performed. 90 91 ObjC JavaScript 92 ---- ---------- 93 NSNull => null 94 nil => undefined 95 WebUndefined => undefined 96 CFBoolean => boolean 97 NSNumber => number 98 NSString => string 99 NSArray => array object 100 WebScriptObject => object 101 102 The above conversions occur only if the declared ObjC type is an object type. 103 For primitive type like int and char, a numeric cast is performed. 104*/ 105@interface NSObject (WebScripting) 106 107/*! 108 @method webScriptNameForSelector: 109 @param selector The selector that will be exposed to the script environment. 110 @discussion Use the returned string as the exported name for the selector 111 in the script environment. It is the responsibility of the class to ensure 112 uniqueness of the returned name. If nil is returned or this 113 method is not implemented the default name for the selector will 114 be used. The default name concatenates the components of the 115 Objective-C selector name and replaces ':' with '_'. '_' characters 116 are escaped with an additional '$', i.e. '_' becomes "$_". '$' are 117 also escaped, i.e. 118 Objective-C name Default script name 119 moveTo:: move__ 120 moveTo_ moveTo$_ 121 moveTo$_ moveTo$$$_ 122 @result Returns the name to be used to represent the specified selector in the 123 scripting environment. 124*/ 125+ (NSString *)webScriptNameForSelector:(SEL)selector WEBKIT_AVAILABLE_MAC(10_4); 126 127/*! 128 @method isSelectorExcludedFromWebScript: 129 @param selector The selector the will be exposed to the script environment. 130 @discussion Return NO to export the selector to the script environment. 131 Return YES to prevent the selector from being exported to the script environment. 132 If this method is not implemented on the class no selectors will be exported. 133 @result Returns YES to hide the selector, NO to export the selector. 134*/ 135+ (BOOL)isSelectorExcludedFromWebScript:(SEL)selector WEBKIT_AVAILABLE_MAC(10_4); 136 137/*! 138 @method webScriptNameForKey: 139 @param name The name of the instance variable that will be exposed to the 140 script environment. Only instance variables that meet the export criteria will 141 be exposed. 142 @discussion Provide an alternate name for a property. 143 @result Returns the name to be used to represent the specified property in the 144 scripting environment. 145*/ 146+ (NSString *)webScriptNameForKey:(const char *)name WEBKIT_AVAILABLE_MAC(10_4); 147 148/*! 149 @method isKeyExcludedFromWebScript: 150 @param name The name of the instance variable that will be exposed to the 151 script environment. 152 @discussion Return NO to export the property to the script environment. 153 Return YES to prevent the property from being exported to the script environment. 154 @result Returns YES to hide the property, NO to export the property. 155*/ 156+ (BOOL)isKeyExcludedFromWebScript:(const char *)name WEBKIT_AVAILABLE_MAC(10_4); 157 158/*! 159 @method invokeUndefinedMethodFromWebScript:withArguments: 160 @param name The name of the method to invoke. 161 @param arguments The arguments to pass the method. 162 @discussion If a script attempts to invoke a method that is not exported, 163 invokeUndefinedMethodFromWebScript:withArguments: will be called. 164 @result The return value of the invocation. The value will be converted as appropriate 165 for the script environment. 166*/ 167- (id)invokeUndefinedMethodFromWebScript:(NSString *)name withArguments:(NSArray *)arguments WEBKIT_AVAILABLE_MAC(10_4); 168 169/*! 170 @method invokeDefaultMethodWithArguments: 171 @param arguments The arguments to pass the method. 172 @discussion If a script attempts to call an exposed object as a function, 173 this method will be called. 174 @result The return value of the call. The value will be converted as appropriate 175 for the script environment. 176*/ 177- (id)invokeDefaultMethodWithArguments:(NSArray *)arguments WEBKIT_AVAILABLE_MAC(10_4); 178 179/*! 180 @method finalizeForWebScript 181 @discussion finalizeForScript is called on objects exposed to the script 182 environment just before the script environment garbage collects the object. 183 Subsequently, any references to WebScriptObjects made by the exposed object will 184 be invalid and have undefined consequences. 185*/ 186- (void)finalizeForWebScript WEBKIT_AVAILABLE_MAC(10_4); 187 188@end 189 190 191// WebScriptObject -------------------------------------------------- 192 193@class JSValue; 194@class WebScriptObjectPrivate; 195@class WebFrame; 196 197/*! 198 @class WebScriptObject 199 @discussion WebScriptObjects are used to wrap script objects passed from 200 script environments to Objective-C. WebScriptObjects cannot be created 201 directly. In normal uses of WebKit, you gain access to the script 202 environment using the "windowScriptObject" method on WebView. 203 204 The following KVC methods are commonly used to access properties of the 205 WebScriptObject: 206 207 - (void)setValue:(id)value forKey:(NSString *)key 208 - (id)valueForKey:(NSString *)key 209 210 As it possible to remove attributes from web script objects, the following 211 additional method augments the basic KVC methods: 212 213 - (void)removeWebScriptKey:(NSString *)name; 214 215 Also, since the sparse array access allowed in script objects doesn't map well 216 to NSArray, the following methods can be used to access index based properties: 217 218 - (id)webScriptValueAtIndex:(unsigned)index; 219 - (void)setWebScriptValueAtIndex:(unsigned)index value:(id)value; 220*/ 221WEBKIT_CLASS_AVAILABLE_MAC(10_4) 222@interface WebScriptObject : NSObject 223{ 224 WebScriptObjectPrivate *_private; 225} 226 227/*! 228 @method throwException: 229 @discussion Throws an exception in the current script execution context. 230 @result Either NO if an exception could not be raised, YES otherwise. 231*/ 232+ (BOOL)throwException:(NSString *)exceptionMessage; 233 234/*! 235 @method JSObject 236 @result The equivalent JSObjectRef for this WebScriptObject. 237 @discussion Use this method to bridge between the WebScriptObject and 238 JavaScriptCore APIs. 239*/ 240- (JSObjectRef)JSObject WEBKIT_AVAILABLE_MAC(10_5); 241 242/*! 243 @method callWebScriptMethod:withArguments: 244 @param name The name of the method to call in the script environment. 245 @param arguments The arguments to pass to the script environment. 246 @discussion Calls the specified method in the script environment using the 247 specified arguments. 248 @result Returns the result of calling the script method. 249 Returns WebUndefined when an exception is thrown in the script environment. 250*/ 251- (id)callWebScriptMethod:(NSString *)name withArguments:(NSArray *)arguments; 252 253/*! 254 @method evaluateWebScript: 255 @param script The script to execute in the target script environment. 256 @discussion The script will be executed in the target script environment. The format 257 of the script is dependent of the target script environment. 258 @result Returns the result of evaluating the script in the script environment. 259 Returns WebUndefined when an exception is thrown in the script environment. 260*/ 261- (id)evaluateWebScript:(NSString *)script; 262 263/*! 264 @method removeWebScriptKey: 265 @param name The name of the property to remove. 266 @discussion Removes the property from the object in the script environment. 267*/ 268- (void)removeWebScriptKey:(NSString *)name; 269 270/*! 271 @method stringRepresentation 272 @discussion Converts the target object to a string representation. The coercion 273 of non string objects type is dependent on the script environment. 274 @result Returns the string representation of the object. 275*/ 276- (NSString *)stringRepresentation; 277 278/*! 279 @method webScriptValueAtIndex: 280 @param index The index of the property to return. 281 @discussion Gets the value of the property at the specified index. 282 @result The value of the property. Returns WebUndefined when an exception is 283 thrown in the script environment. 284*/ 285- (id)webScriptValueAtIndex:(unsigned)index; 286 287/*! 288 @method setWebScriptValueAtIndex:value: 289 @param index The index of the property to set. 290 @param value The value of the property to set. 291 @discussion Sets the property value at the specified index. 292*/ 293- (void)setWebScriptValueAtIndex:(unsigned)index value:(id)value; 294 295/*! 296 @method setException: 297 @param description The description of the exception. 298 @discussion Raises an exception in the script environment in the context of the 299 current object. 300*/ 301- (void)setException:(NSString *)description; 302 303 304#if JSC_OBJC_API_ENABLED 305/*! 306 @method JSValue 307 @result The equivalent Objective-C JSValue for this WebScriptObject. 308 @discussion Use this method to bridge between the WebScriptObject and 309 JavaScriptCore Objective-C APIs. 310*/ 311- (JSValue *)JSValue; 312#endif 313 314@end 315 316 317// WebUndefined -------------------------------------------------------------- 318 319/*! 320 @class WebUndefined 321*/ 322WEBKIT_CLASS_AVAILABLE_MAC(10_4) 323@interface WebUndefined : NSObject <NSCoding, NSCopying> 324 325/*! 326 @method undefined 327 @result The WebUndefined shared instance. 328*/ 329+ (WebUndefined *)undefined; 330 331@end 332 333#endif // WebScriptObject_h 334