1/* 2 * Copyright (C) 2003, 2004, 2005, 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 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of Apple Inc. ("Apple") nor the names of 14 * its contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 17 * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY 18 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 19 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 20 * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY 21 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 22 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 24 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29#import <Foundation/Foundation.h> 30 31#if !TARGET_OS_IPHONE 32#import <AppKit/AppKit.h> 33#endif 34 35@class NSError; 36@class NSURLResponse; 37@class NSURLRequest; 38@class WebView; 39@class WebFrame; 40@class WebPolicyPrivate; 41 42/*! 43 @enum WebNavigationType 44 @abstract The type of action that triggered a possible navigation. 45 @constant WebNavigationTypeLinkClicked A link with an href was clicked. 46 @constant WebNavigationTypeFormSubmitted A form was submitted. 47 @constant WebNavigationTypeBackForward The user chose back or forward. 48 @constant WebNavigationTypeReload The User hit the reload button. 49 @constant WebNavigationTypeFormResubmitted A form was resubmitted (by virtue of doing back, forward or reload). 50 @constant WebNavigationTypeOther Navigation is taking place for some other reason. 51*/ 52 53typedef NS_ENUM(NSInteger, WebNavigationType) { 54 WebNavigationTypeLinkClicked, 55 WebNavigationTypeFormSubmitted, 56 WebNavigationTypeBackForward, 57 WebNavigationTypeReload, 58 WebNavigationTypeFormResubmitted, 59 WebNavigationTypeOther 60}; 61 62extern NSString *WebActionNavigationTypeKey; // NSNumber (WebNavigationType) 63extern NSString *WebActionElementKey; // NSDictionary of element info 64extern NSString *WebActionButtonKey; // NSNumber (0 for left button, 1 for middle button, 2 for right button) 65extern NSString *WebActionModifierFlagsKey; // NSNumber (unsigned) 66extern NSString *WebActionOriginalURLKey; // NSURL 67 68/*! 69 @protocol WebPolicyDecisionListener 70 @discussion This protocol is used to call back with the results of a 71 policy decision. This provides the ability to make these decisions 72 asyncrhonously, which means the decision can be made by prompting 73 with a sheet, for example. 74*/ 75 76@protocol WebPolicyDecisionListener <NSObject> 77 78/*! 79 @method use 80 @abstract Use the resource 81 @discussion If there remain more policy decisions to be made, then 82 the next policy delegate method gets to decide. This will be 83 either the next navigation policy delegate if there is a redirect, 84 or the content policy delegate. If there are no more policy 85 decisions to be made, the resource will be displayed inline if 86 possible. If there is no view available to display the resource 87 inline, then unableToImplementPolicyWithError:frame: will be 88 called with an appropriate error. 89 90 <p>If a new window is going to be created for this navigation as a 91 result of frame targetting, then it will be created once you call 92 this method. 93*/ 94- (void)use; 95/*! 96 @method download 97 @abstract Download the resource instead of displaying it. 98 @discussion This method is more than just a convenience because it 99 allows an in-progress navigation to be converted to a download 100 based on content type, without having to stop and restart the 101 load. 102*/ 103- (void)download; 104 105/*! 106 @method ignore 107 @abstract Do nothing (but the client may choose to handle the request itself) 108 @discussion A policy of ignore prevents WebKit from doing anything 109 further with the load, however, the client is still free to handle 110 the request in some other way, such as opening a new window, 111 opening a new window behind the current one, opening the URL in an 112 external app, revealing the location in Finder if a file URL, etc. 113*/ 114- (void)ignore; 115 116@end 117 118 119/*! 120 @category WebPolicyDelegate 121 @discussion While loading a URL, WebKit asks the WebPolicyDelegate for 122 policies that determine the action of what to do with the URL or the data that 123 the URL represents. Typically, the policy handler methods are called in this order: 124 125 decidePolicyForNewWindowAction:request:newFrameName:decisionListener: (at most once)<BR> 126 decidePolicyForNavigationAction:request:frame:decisionListener: (zero or more times)<BR> 127 decidePolicyForMIMEType:request:frame: (zero or more times)<BR> 128 129 New window policy is always checked. Navigation policy is checked 130 for the initial load and every redirect unless blocked by an 131 earlier policy. Content policy is checked once the content type is 132 known, unless an earlier policy prevented it. 133 134 In rare cases, content policy might be checked more than 135 once. This occurs when loading a "multipart/x-mixed-replace" 136 document, also known as "server push". In this case, multiple 137 documents come in one navigation, with each replacing the last. In 138 this case, conent policy will be checked for each one. 139*/ 140@interface NSObject (WebPolicyDelegate) 141 142/*! 143 @method webView:decidePolicyForNavigationAction:request:frame:decisionListener: 144 @abstract This method is called to decide what to do with a proposed navigation. 145 @param actionInformation Dictionary that describes the action that triggered this navigation. 146 @param request The request for the proposed navigation 147 @param frame The WebFrame in which the navigation is happening 148 @param listener The object to call when the decision is made 149 @discussion This method will be called before loading starts, and 150 on every redirect. 151*/ 152- (void)webView:(WebView *)webView decidePolicyForNavigationAction:(NSDictionary *)actionInformation 153 request:(NSURLRequest *)request 154 frame:(WebFrame *)frame 155 decisionListener:(id<WebPolicyDecisionListener>)listener; 156 157/*! 158 @method webView:decidePolicyForNewWindowAction:request:newFrameName:decisionListener: 159 @discussion This method is called to decide what to do with an targetted nagivation that would open a new window. 160 @param actionInformation Dictionary that describes the action that triggered this navigation. 161 @param request The request for the proposed navigation 162 @param frame The frame in which the navigation is taking place 163 @param listener The object to call when the decision is made 164 @discussion This method is provided so that modified clicks on a targetted link which 165 opens a new frame can prevent the new window from being opened if they decide to 166 do something else, like download or present the new frame in a specialized way. 167 168 <p>If this method picks a policy of Use, the new window will be 169 opened, and decidePolicyForNavigationAction:request:frame:decisionListner: 170 will be called with a WebNavigationType of WebNavigationTypeOther 171 in its action. This is to avoid possible confusion about the modifiers. 172*/ 173- (void)webView:(WebView *)webView decidePolicyForNewWindowAction:(NSDictionary *)actionInformation 174 request:(NSURLRequest *)request 175 newFrameName:(NSString *)frameName 176 decisionListener:(id<WebPolicyDecisionListener>)listener; 177 178/*! 179 @method webView:decidePolicyForMIMEType:request:frame: 180 @discussion Returns the policy for content which has been partially loaded. 181 Sent after webView:didStartProvisionalLoadForFrame: is sent on the WebFrameLoadDelegate. 182 @param type MIME type for the resource. 183 @param request A NSURLRequest for the partially loaded content. 184 @param frame The frame which is loading the URL. 185 @param listener The object to call when the decision is made 186*/ 187- (void)webView:(WebView *)webView decidePolicyForMIMEType:(NSString *)type 188 request:(NSURLRequest *)request 189 frame:(WebFrame *)frame 190 decisionListener:(id<WebPolicyDecisionListener>)listener; 191 192/*! 193 @method webView:unableToImplementPolicy:error:forURL:inFrame: 194 @discussion Called when a WebPolicy could not be implemented. It is up to the client to display appropriate feedback. 195 @param policy The policy that could not be implemented. 196 @param error The error that caused the policy to not be implemented. 197 @param URL The URL of the resource for which a particular action was requested but failed. 198 @param frame The frame in which the policy could not be implemented. 199*/ 200- (void)webView:(WebView *)webView unableToImplementPolicyWithError:(NSError *)error frame:(WebFrame *)frame; 201 202@end 203