334 lines
13 KiB
Objective-C
334 lines
13 KiB
Objective-C
/*
|
|
* Copyright (C) 2004, 2006, 2007 Apple Inc. All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions
|
|
* are met:
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
|
|
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR
|
|
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
|
|
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
|
|
#ifndef WebScriptObject_h
|
|
#define WebScriptObject_h
|
|
|
|
#import <Foundation/Foundation.h>
|
|
#import <JavaScriptCore/JSBase.h>
|
|
#import <WebCore/WebKitAvailability.h>
|
|
|
|
// NSObject (WebScripting) -----------------------------------------------------
|
|
|
|
/*
|
|
Classes may implement one or more methods in WebScripting to export interfaces
|
|
to WebKit's JavaScript environment.
|
|
|
|
By default, no properties or functions are exported. A class must implement
|
|
+isKeyExcludedFromWebScript: and/or +isSelectorExcludedFromWebScript: to
|
|
expose selected properties and methods, respectively, to JavaScript.
|
|
|
|
Access to exported properties is done using KVC -- specifically, the following
|
|
KVC methods:
|
|
|
|
- (void)setValue:(id)value forKey:(NSString *)key
|
|
- (id)valueForKey:(NSString *)key
|
|
|
|
Clients may also intercept property set/get operations that are made by the
|
|
scripting environment for properties that are not exported. This is done using
|
|
the KVC methods:
|
|
|
|
- (void)setValue:(id)value forUndefinedKey:(NSString *)key
|
|
- (id)valueForUndefinedKey:(NSString *)key
|
|
|
|
Similarly, clients may intercept method invocations that are made by the
|
|
scripting environment for methods that are not exported. This is done using
|
|
the method:
|
|
|
|
- (id)invokeUndefinedMethodFromWebScript:(NSString *)name withArguments:(NSArray *)args;
|
|
|
|
If clients need to raise an exception in the script environment
|
|
they can call [WebScriptObject throwException:]. Note that throwing an
|
|
exception using this method will only succeed if the method that throws the exception
|
|
is being called within the scope of a script invocation.
|
|
|
|
Not all methods are exposed. Only those methods whose parameters and return
|
|
type meets the export criteria are exposed. Valid types are Objective-C instances
|
|
and scalars. Other types are not allowed.
|
|
|
|
Types will be converted automatically between JavaScript and Objective-C in
|
|
the following manner:
|
|
|
|
JavaScript ObjC
|
|
---------- ----------
|
|
null => nil
|
|
undefined => WebUndefined
|
|
number => NSNumber
|
|
boolean => CFBoolean
|
|
string => NSString
|
|
object => id
|
|
|
|
The object => id conversion occurs as follows: if the object wraps an underlying
|
|
Objective-C object (i.e., if it was created by a previous ObjC => JavaScript conversion),
|
|
then the underlying Objective-C object is returned. Otherwise, a new WebScriptObject
|
|
is created and returned.
|
|
|
|
The above conversions occur only if the declared ObjC type is an object type.
|
|
For primitive types like int and char, a numeric cast is performed.
|
|
|
|
ObjC JavaScript
|
|
---- ----------
|
|
NSNull => null
|
|
nil => undefined
|
|
WebUndefined => undefined
|
|
CFBoolean => boolean
|
|
NSNumber => number
|
|
NSString => string
|
|
NSArray => array object
|
|
WebScriptObject => object
|
|
|
|
The above conversions occur only if the declared ObjC type is an object type.
|
|
For primitive type like int and char, a numeric cast is performed.
|
|
*/
|
|
@interface NSObject (WebScripting)
|
|
|
|
/*!
|
|
@method webScriptNameForSelector:
|
|
@param selector The selector that will be exposed to the script environment.
|
|
@discussion Use the returned string as the exported name for the selector
|
|
in the script environment. It is the responsibility of the class to ensure
|
|
uniqueness of the returned name. If nil is returned or this
|
|
method is not implemented the default name for the selector will
|
|
be used. The default name concatenates the components of the
|
|
Objective-C selector name and replaces ':' with '_'. '_' characters
|
|
are escaped with an additional '$', i.e. '_' becomes "$_". '$' are
|
|
also escaped, i.e.
|
|
Objective-C name Default script name
|
|
moveTo:: move__
|
|
moveTo_ moveTo$_
|
|
moveTo$_ moveTo$$$_
|
|
@result Returns the name to be used to represent the specified selector in the
|
|
scripting environment.
|
|
*/
|
|
+ (NSString *)webScriptNameForSelector:(SEL)selector WEBKIT_AVAILABLE_MAC(10_4);
|
|
|
|
/*!
|
|
@method isSelectorExcludedFromWebScript:
|
|
@param selector The selector the will be exposed to the script environment.
|
|
@discussion Return NO to export the selector to the script environment.
|
|
Return YES to prevent the selector from being exported to the script environment.
|
|
If this method is not implemented on the class no selectors will be exported.
|
|
@result Returns YES to hide the selector, NO to export the selector.
|
|
*/
|
|
+ (BOOL)isSelectorExcludedFromWebScript:(SEL)selector WEBKIT_AVAILABLE_MAC(10_4);
|
|
|
|
/*!
|
|
@method webScriptNameForKey:
|
|
@param name The name of the instance variable that will be exposed to the
|
|
script environment. Only instance variables that meet the export criteria will
|
|
be exposed.
|
|
@discussion Provide an alternate name for a property.
|
|
@result Returns the name to be used to represent the specified property in the
|
|
scripting environment.
|
|
*/
|
|
+ (NSString *)webScriptNameForKey:(const char *)name WEBKIT_AVAILABLE_MAC(10_4);
|
|
|
|
/*!
|
|
@method isKeyExcludedFromWebScript:
|
|
@param name The name of the instance variable that will be exposed to the
|
|
script environment.
|
|
@discussion Return NO to export the property to the script environment.
|
|
Return YES to prevent the property from being exported to the script environment.
|
|
@result Returns YES to hide the property, NO to export the property.
|
|
*/
|
|
+ (BOOL)isKeyExcludedFromWebScript:(const char *)name WEBKIT_AVAILABLE_MAC(10_4);
|
|
|
|
/*!
|
|
@method invokeUndefinedMethodFromWebScript:withArguments:
|
|
@param name The name of the method to invoke.
|
|
@param arguments The arguments to pass the method.
|
|
@discussion If a script attempts to invoke a method that is not exported,
|
|
invokeUndefinedMethodFromWebScript:withArguments: will be called.
|
|
@result The return value of the invocation. The value will be converted as appropriate
|
|
for the script environment.
|
|
*/
|
|
- (id)invokeUndefinedMethodFromWebScript:(NSString *)name withArguments:(NSArray *)arguments WEBKIT_AVAILABLE_MAC(10_4);
|
|
|
|
/*!
|
|
@method invokeDefaultMethodWithArguments:
|
|
@param arguments The arguments to pass the method.
|
|
@discussion If a script attempts to call an exposed object as a function,
|
|
this method will be called.
|
|
@result The return value of the call. The value will be converted as appropriate
|
|
for the script environment.
|
|
*/
|
|
- (id)invokeDefaultMethodWithArguments:(NSArray *)arguments WEBKIT_AVAILABLE_MAC(10_4);
|
|
|
|
/*!
|
|
@method finalizeForWebScript
|
|
@discussion finalizeForScript is called on objects exposed to the script
|
|
environment just before the script environment garbage collects the object.
|
|
Subsequently, any references to WebScriptObjects made by the exposed object will
|
|
be invalid and have undefined consequences.
|
|
*/
|
|
- (void)finalizeForWebScript WEBKIT_AVAILABLE_MAC(10_4);
|
|
|
|
@end
|
|
|
|
|
|
// WebScriptObject --------------------------------------------------
|
|
|
|
@class JSValue;
|
|
@class WebScriptObjectPrivate;
|
|
@class WebFrame;
|
|
|
|
/*!
|
|
@class WebScriptObject
|
|
@discussion WebScriptObjects are used to wrap script objects passed from
|
|
script environments to Objective-C. WebScriptObjects cannot be created
|
|
directly. In normal uses of WebKit, you gain access to the script
|
|
environment using the "windowScriptObject" method on WebView.
|
|
|
|
The following KVC methods are commonly used to access properties of the
|
|
WebScriptObject:
|
|
|
|
- (void)setValue:(id)value forKey:(NSString *)key
|
|
- (id)valueForKey:(NSString *)key
|
|
|
|
As it possible to remove attributes from web script objects, the following
|
|
additional method augments the basic KVC methods:
|
|
|
|
- (void)removeWebScriptKey:(NSString *)name;
|
|
|
|
Also, since the sparse array access allowed in script objects doesn't map well
|
|
to NSArray, the following methods can be used to access index based properties:
|
|
|
|
- (id)webScriptValueAtIndex:(unsigned)index;
|
|
- (void)setWebScriptValueAtIndex:(unsigned)index value:(id)value;
|
|
*/
|
|
WEBKIT_CLASS_DEPRECATED_MAC(10_4, 10_14)
|
|
WEBCORE_EXPORT @interface WebScriptObject : NSObject
|
|
{
|
|
WebScriptObjectPrivate *_private;
|
|
}
|
|
|
|
/*!
|
|
@method throwException:
|
|
@discussion Throws an exception in the current script execution context.
|
|
@result Either NO if an exception could not be raised, YES otherwise.
|
|
*/
|
|
+ (BOOL)throwException:(NSString *)exceptionMessage;
|
|
|
|
/*!
|
|
@method JSObject
|
|
@result The equivalent JSObjectRef for this WebScriptObject.
|
|
@discussion Use this method to bridge between the WebScriptObject and
|
|
JavaScriptCore APIs.
|
|
*/
|
|
- (JSObjectRef)JSObject WEBKIT_AVAILABLE_MAC(10_5);
|
|
|
|
/*!
|
|
@method callWebScriptMethod:withArguments:
|
|
@param name The name of the method to call in the script environment.
|
|
@param arguments The arguments to pass to the script environment.
|
|
@discussion Calls the specified method in the script environment using the
|
|
specified arguments.
|
|
@result Returns the result of calling the script method.
|
|
Returns WebUndefined when an exception is thrown in the script environment.
|
|
*/
|
|
- (id)callWebScriptMethod:(NSString *)name withArguments:(NSArray *)arguments;
|
|
|
|
/*!
|
|
@method evaluateWebScript:
|
|
@param script The script to execute in the target script environment.
|
|
@discussion The script will be executed in the target script environment. The format
|
|
of the script is dependent of the target script environment.
|
|
@result Returns the result of evaluating the script in the script environment.
|
|
Returns WebUndefined when an exception is thrown in the script environment.
|
|
*/
|
|
- (id)evaluateWebScript:(NSString *)script;
|
|
|
|
/*!
|
|
@method removeWebScriptKey:
|
|
@param name The name of the property to remove.
|
|
@discussion Removes the property from the object in the script environment.
|
|
*/
|
|
- (void)removeWebScriptKey:(NSString *)name;
|
|
|
|
/*!
|
|
@method stringRepresentation
|
|
@discussion Converts the target object to a string representation. The coercion
|
|
of non string objects type is dependent on the script environment.
|
|
@result Returns the string representation of the object.
|
|
*/
|
|
- (NSString *)stringRepresentation;
|
|
|
|
/*!
|
|
@method webScriptValueAtIndex:
|
|
@param index The index of the property to return.
|
|
@discussion Gets the value of the property at the specified index.
|
|
@result The value of the property. Returns WebUndefined when an exception is
|
|
thrown in the script environment.
|
|
*/
|
|
- (id)webScriptValueAtIndex:(unsigned)index;
|
|
|
|
/*!
|
|
@method setWebScriptValueAtIndex:value:
|
|
@param index The index of the property to set.
|
|
@param value The value of the property to set.
|
|
@discussion Sets the property value at the specified index.
|
|
*/
|
|
- (void)setWebScriptValueAtIndex:(unsigned)index value:(id)value;
|
|
|
|
/*!
|
|
@method setException:
|
|
@param description The description of the exception.
|
|
@discussion Raises an exception in the script environment in the context of the
|
|
current object.
|
|
*/
|
|
- (void)setException:(NSString *)description;
|
|
|
|
|
|
#if JSC_OBJC_API_ENABLED
|
|
/*!
|
|
@method JSValue
|
|
@result The equivalent Objective-C JSValue for this WebScriptObject.
|
|
@discussion Use this method to bridge between the WebScriptObject and
|
|
JavaScriptCore Objective-C APIs.
|
|
*/
|
|
- (JSValue *)JSValue;
|
|
#endif
|
|
|
|
@end
|
|
|
|
|
|
// WebUndefined --------------------------------------------------------------
|
|
|
|
/*!
|
|
@class WebUndefined
|
|
*/
|
|
WEBKIT_CLASS_DEPRECATED_MAC(10_4, 10_14)
|
|
WEBCORE_EXPORT @interface WebUndefined : NSObject <NSCoding, NSCopying>
|
|
|
|
/*!
|
|
@method undefined
|
|
@result The WebUndefined shared instance.
|
|
*/
|
|
+ (WebUndefined *)undefined;
|
|
|
|
@end
|
|
|
|
#endif // WebScriptObject_h
|