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 import "IWebView.idl"; 30 import "IWebURLRequest.idl"; 31 #endif 32 33 interface IWebError; 34 interface IWebURLResponse; 35 interface IWebURLRequest; 36 interface IWebView; 37 interface IWebFrame; 38 interface IWebPolicyPrivate; 39 40 /*! 41 @enum WebNavigationType 42 @abstract The type of action that triggered a possible navigation. 43 @constant WebNavigationTypeLinkClicked A link with an href was clicked. 44 @constant WebNavigationTypeFormSubmitted A form was submitted. 45 @constant WebNavigationTypeBackForward The user chose back or forward. 46 @constant WebNavigationTypeReload The User hit the reload button. 47 @constant WebNavigationTypeFormResubmitted A form was resubmitted (by virtue of doing back, forward or reload). 48 @constant WebNavigationTypeOther Navigation is taking place for some other reason. 49 */ 50 51 typedef enum WebNavigationType { 52 WebNavigationTypeLinkClicked, 53 WebNavigationTypeFormSubmitted, 54 WebNavigationTypeBackForward, 55 WebNavigationTypeReload, 56 WebNavigationTypeFormResubmitted, 57 WebNavigationTypeOther 58 } WebNavigationType; 59 60 cpp_quote("#define WebActionButtonKey TEXT(\"WebActionButtonKey\")") 61 cpp_quote("#define WebActionElementKey TEXT(\"WebActionElementKey\")") 62 cpp_quote("#define WebActionFormKey TEXT(\"WebActionFormKey\")") 63 cpp_quote("#define WebActionModifierFlagsKey TEXT(\"WebActionModifierFlagsKey\")") 64 cpp_quote("#define WebActionNavigationTypeKey TEXT(\"WebActionNavigationTypeKey\")") 65 cpp_quote("#define WebActionOriginalURLKey TEXT(\"WebActionOriginalURLKey\")") 66 67 /*! 68 @protocol WebPolicyDecisionListener 69 @discussion This protocol is used to call back with the results of a 70 policy decision. This provides the ability to make these decisions 71 asyncrhonously, which means the decision can be made by prompting 72 with a sheet, for example. 73 @protocol WebPolicyDecisionListener <NSObject> 74 */ 75 [ 76 object, 77 oleautomation, 78 uuid(DFCDE523-FD96-4f95-958B-151540FE122A), 79 pointer_default(unique) 80 ] 81 interface IWebPolicyDecisionListener : IUnknown 82 { 83 /*! 84 @method use 85 @abstract Use the resource 86 @discussion If there remain more policy decisions to be made, then 87 the next policy delegate method gets to decide. This will be 88 either the next navigation policy delegate if there is a redirect, 89 or the content policy delegate. If there are no more policy 90 decisions to be made, the resource will be displayed inline if 91 possible. If there is no view available to display the resource 92 inline, then unableToImplementPolicyWithError:frame: will be 93 called with an appropriate error. 94 95 <p>If a new window is going to be created for this navigation as a 96 result of frame targetting, then it will be created once you call 97 this method. 98 - (void)use; 99 */ 100 HRESULT use(); 101 102 /*! 103 @method download 104 @abstract Download the resource instead of displaying it. 105 @discussion This method is more than just a convenience because it 106 allows an in-progress navigation to be converted to a download 107 based on content type, without having to stop and restart the 108 load. 109 - (void)download; 110 */ 111 HRESULT download(); 112 113 /*! 114 @method ignore 115 @abstract Do nothing (but the client may choose to handle the request itself) 116 @discussion A policy of ignore prevents WebKit from doing anything 117 further with the load, however, the client is still free to handle 118 the request in some other way, such as opening a new window, 119 opening a new window behind the current one, opening the URL in an 120 external app, revealing the location in Finder if a file URL, etc. 121 - (void)ignore; 122 */ 123 HRESULT ignore(); 124 } 125 126 /*! 127 @category WebPolicyDelegate 128 @discussion While loading a URL, WebKit asks the WebPolicyDelegate for 129 policies that determine the action of what to do with the URL or the data that 130 the URL represents. Typically, the policy handler methods are called in this order: 131 132 decidePolicyForNewWindowAction:request:newFrameName:decisionListener: (at most once)<BR> 133 decidePolicyForNavigationAction:request:frame:decisionListener: (zero or more times)<BR> 134 decidePolicyForMIMEType:request:frame: (zero or more times)<BR> 135 136 New window policy is always checked. Navigation policy is checked 137 for the initial load and every redirect unless blocked by an 138 earlier policy. Content policy is checked once the content type is 139 known, unless an earlier policy prevented it. 140 141 In rare cases, content policy might be checked more than 142 once. This occurs when loading a "multipart/x-mixed-replace" 143 document, also known as "server push". In this case, multiple 144 documents come in one navigation, with each replacing the last. In 145 this case, conent policy will be checked for each one. 146 @interface NSObject (WebPolicyDelegate) 147 */ 148 [ 149 object, 150 oleautomation, 151 uuid(9B0BAE6C-A496-4000-9E22-2E89F0747401), 152 pointer_default(unique) 153 ] 154 interface IWebPolicyDelegate : IUnknown 155 { 156 /*! 157 @method webView:decidePolicyForNavigationAction:request:frame:decisionListener: 158 @abstract This method is called to decide what to do with a proposed navigation. 159 @param actionInformation Dictionary that describes the action that triggered this navigation. 160 @param request The request for the proposed navigation 161 @param frame The WebFrame in which the navigation is happening 162 @param listener The object to call when the decision is made 163 @discussion This method will be called before loading starts, and 164 on every redirect. 165 - (void)webView:(WebView *)webView decidePolicyForNavigationAction:(NSDictionary *)actionInformation 166 request:(NSURLRequest *)request 167 frame:(WebFrame *)frame 168 decisionListener:(id<WebPolicyDecisionListener>)listener; 169 */ 170 HRESULT decidePolicyForNavigationAction([in] IWebView* webView, [in] IPropertyBag* actionInformation, [in] IWebURLRequest* request, [in] IWebFrame* frame, [in] IWebPolicyDecisionListener* listener); 171 172 /*! 173 @method webView:decidePolicyForNewWindowAction:request:newFrameName:decisionListener: 174 @discussion This method is called to decide what to do with an targetted nagivation that would open a new window. 175 @param actionInformation Dictionary that describes the action that triggered this navigation. 176 @param request The request for the proposed navigation 177 @param frame The frame in which the navigation is taking place 178 @param listener The object to call when the decision is made 179 @discussion This method is provided so that modified clicks on a targetted link which 180 opens a new frame can prevent the new window from being opened if they decide to 181 do something else, like download or present the new frame in a specialized way. 182 183 <p>If this method picks a policy of Use, the new window will be 184 opened, and decidePolicyForNavigationAction:request:frame:decisionListner: 185 will be called with a WebNavigationType of WebNavigationTypeOther 186 in its action. This is to avoid possible confusion about the modifiers. 187 - (void)webView:(WebView *)webView decidePolicyForNewWindowAction:(NSDictionary *)actionInformation 188 request:(NSURLRequest *)request 189 newFrameName:(NSString *)frameName 190 decisionListener:(id<WebPolicyDecisionListener>)listener; 191 */ 192 HRESULT decidePolicyForNewWindowAction([in] IWebView* webView, [in] IPropertyBag* actionInformation, [in] IWebURLRequest* request, [in] BSTR frameName, [in] IWebPolicyDecisionListener* listener); 193 194 /*! 195 @method webView:decidePolicyForMIMEType:request:frame: 196 @discussion Returns the policy for content which has been partially loaded. 197 Sent after webView:didStartProvisionalLoadForFrame: is sent on the WebFrameLoadDelegate. 198 @param type MIME type for the resource. 199 @param request A NSURLRequest for the partially loaded content. 200 @param frame The frame which is loading the URL. 201 @param listener The object to call when the decision is made 202 - (void)webView:(WebView *)webView decidePolicyForMIMEType:(NSString *)type 203 request:(NSURLRequest *)request 204 frame:(WebFrame *)frame 205 decisionListener:(id<IWebPolicyDecisionListener>)listener; 206 */ 207 HRESULT decidePolicyForMIMEType([in] IWebView* webView, [in] BSTR type, [in] IWebURLRequest* request, [in] IWebFrame* frame, [in] IWebPolicyDecisionListener* listener); 208 209 /*! 210 @method webView:unableToImplementPolicy:error:forURL:inFrame: 211 @discussion Called when a WebPolicy could not be implemented. It is up to the client to display appropriate feedback. 212 @param policy The policy that could not be implemented. 213 @param error The error that caused the policy to not be implemented. 214 @param URL The URL of the resource for which a particular action was requested but failed. 215 @param frame The frame in which the policy could not be implemented. 216 - (void)webView:(WebView *)webView unableToImplementPolicyWithError:(NSError *)error frame:(WebFrame *)frame; 217 */ 218 HRESULT unableToImplementPolicyWithError([in] IWebView* webView, [in] IWebError* error, [in] IWebFrame* frame); 219 } 220
