1 /* 2 * Copyright (C) 2006, 2007, 2008 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 COMPUTER, 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 COMPUTER, 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 DO_NO_IMPORTS 27 import "oaidl.idl"; 28 import "ocidl.idl"; 29 #endif 30 31 /*! 32 @class WebScriptObject 33 @discussion WebScriptObjects are used to wrap script objects passed from 34 script environments to Objective-C. WebScriptObjects cannot be created 35 directly. In normal uses of WebKit, you gain access to the script 36 environment using the "windowScriptObject" method on WebView. 37 38 The following KVC methods are commonly used to access properties of the 39 WebScriptObject: 40 41 - (void)setValue:(id)value forKey:(NSString *)key 42 - (id)valueForKey:(NSString *)key 43 44 As it possible to remove attributes from web script objects the following 45 additional method augments the basic KVC methods: 46 47 - (void)removeWebScriptKey:(NSString *)name; 48 49 Also the sparse array access allowed in web script objects doesn't map well to NSArray, so 50 the following methods can be used to access index based properties: 51 52 - (id)webScriptValueAtIndex:(unsigned int)index; 53 - (void)setWebScriptValueAtIndex:(unsigned int)index value:(id)value; 54 55 @interface WebScriptObject : NSObject 56 */ 57 [ 58 object, 59 oleautomation, 60 uuid(7022340A-649C-43fc-9214-85CA7D3BE3C7), 61 pointer_default(unique) 62 ] 63 interface IWebScriptObject : IUnknown 64 { 65 /*! 66 @method throwException: 67 @discussion Throws an exception in the current script execution context. 68 @result Either NO if an exception could not be raised, YES otherwise. 69 + (BOOL)throwException:(NSString *)exceptionMessage; 70 */ 71 HRESULT throwException([in] BSTR exceptionMessage, [out, retval] BOOL* result); 72 73 /*! 74 @method callWebScriptMethod:withArguments: 75 @param name The name of the method to call in the script environment. 76 @param args The arguments to pass to the script environment. 77 @discussion Calls the specified method in the script environment using the 78 specified arguments. 79 @result Returns the result of calling the script method. 80 - (id)callWebScriptMethod:(NSString *)name withArguments:(NSArray *)args; 81 */ 82 HRESULT callWebScriptMethod([in] BSTR name, [in, size_is(cArgs)] const VARIANT args[], [in] int cArgs, [out, retval] VARIANT* result); 83 84 /*! 85 @method evaluateWebScript: 86 @param script The script to execute in the target script environment. 87 @discussion The script will be executed in the target script environment. The format 88 of the script is dependent of the target script environment. 89 @result Returns the result of evaluating the script in the script environment. 90 - (id)evaluateWebScript:(NSString *)script; 91 */ 92 HRESULT evaluateWebScript([in] BSTR script, [out, retval] VARIANT* result); 93 94 /*! 95 @method removeWebScriptKey: 96 @param name The name of the property to remove. 97 @discussion Removes the property from the object in the script environment. 98 - (void)removeWebScriptKey:(NSString *)name; 99 */ 100 HRESULT removeWebScriptKey([in] BSTR name); 101 102 /*! 103 @method toString 104 @discussion Converts the target object to a string representation. The coercion 105 of non string objects type is dependent on the script environment. 106 @result Returns the string representation of the object. 107 - (NSString *)stringRepresentation; 108 */ 109 HRESULT stringRepresentation([out, retval] BSTR* stringRepresentation); 110 111 /*! 112 @method propertyAtIndex: 113 @param index The index of the property to return. Index based access is dependent 114 @discussion Gets the value of the property at the specified index. 115 @result The value of the property. 116 - (id)webScriptValueAtIndex:(unsigned int)index; 117 */ 118 HRESULT webScriptValueAtIndex([in] unsigned int index, [out, retval] VARIANT* result); 119 120 /*! 121 @method setPropertyAtIndex:value: 122 @param index The index of the property to set. 123 @param value The value of the property to set. 124 @discussion Sets the property value at the specified index. 125 - (void)setWebScriptValueAtIndex:(unsigned int)index value:(id)value; 126 */ 127 HRESULT setWebScriptValueAtIndex([in] unsigned int index, [in] VARIANT val); 128 129 /*! 130 @method setException: 131 @param description The description of the exception. 132 @discussion Raises an exception in the script environment in the context of the 133 current object. 134 - (void)setException: (NSString *)description; 135 */ 136 HRESULT setException([in] BSTR description); 137 } 138
