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